Software Requirements Specification
Introduction
Purpose
This Software Requirements Specification (SRS) describes the functional and non-functional requirements for AirGap Deploy, a command-line tool for packaging applications and their dependencies for deployment on air-gapped systems.
This document is intended for:
Developers implementing AirGap Deploy
Release engineers using AirGap Deploy to package applications
Technical reviewers evaluating the tool’s capabilities
Scope
Product Name: AirGap Deploy
Product Purpose: Simplify the packaging and installation of software on air-gapped systems
Benefits:
Declarative manifest-based packaging (no custom scripts)
Cross-platform support (Linux, macOS, Windows)
Automated dependency collection and vendoring
Generated installation scripts for air-gapped deployment
Goals:
Enable developers to package any application for air-gap deployment with a single TOML manifest
Reduce manual effort in preparing air-gap packages from days to minutes
Ensure reproducible, verifiable deployments
Out of Scope:
GUI interface (CLI only)
Network-based distribution mechanisms
Digital signature/verification (future enhancement)
Automatic updates (contradicts air-gap philosophy)
Plugin system (deferred to future version)
Definitions, Acronyms, and Abbreviations
Term |
Definition |
|---|---|
Air-gap |
Physical isolation from networks, especially the internet |
Component |
A deployable unit (application, binary, model, package) |
Manifest |
TOML file defining deployment requirements ( |
Package |
Final output archive (.tar.gz or .zip) ready for air-gap transfer |
Vendor |
Process of including all dependencies within a package |
Prep |
Preparation phase on connected machine |
Install |
Installation phase on air-gapped machine |
TOML |
Tom’s Obvious Minimal Language (configuration format) |
SHA-256 |
Cryptographic hash function for checksums |
Overall Description
Product Perspective
AirGap Deploy is a standalone developer tool that integrates into existing software development workflows. It operates in two distinct phases:
Phase 1 - Preparation (Connected System):
Developer creates
AirGapDeploy.tomlmanifestAirGap Deploy collects application source, dependencies, models, binaries
Generates deployment package (.tar.gz or .zip)
Generates installation scripts (install.sh, install.ps1)
Phase 2 - Installation (Air-Gapped System):
User transfers package via USB or other physical media
User executes generated installation script
Script builds/installs application from vendored dependencies
No network access required
Relationship to Other Systems:
AirGap Transfer: Optional integration for large packages (see Meta-Architecture)
Cleanroom Whisper: Reference implementation and primary use case
CI/CD pipelines: Integrates with GitHub Actions, GitLab CI for automated package generation
Product Functions
AirGap Deploy provides the following major functions:
Manifest Parsing - Parse and validate AirGapDeploy.toml files
Component Collection - Download and collect required components:
Rust applications with vendored dependencies
External binaries from Git repositories
Model files from URLs with checksum verification
System packages (Linux distributions)
Packaging - Create compressed archives with all components
Install Script Generation - Generate platform-specific installation scripts
CLI Interface - User-friendly command-line tool with progress reporting
User Characteristics
Primary Users: Application Developers / Release Engineers
Technical expertise: High (familiar with command-line tools, build systems)
Domain knowledge: Understands air-gap deployment constraints
Frequency of use: Occasional (during release cycles)
Environment: Development machine with internet access
Secondary Users: End Users / IT Staff
Technical expertise: Medium (can run installation scripts)
Domain knowledge: Works with air-gapped systems
Frequency of use: Rare (only during installations/updates)
Environment: Air-gapped production system
Constraints
Regulatory Constraints:
Must comply with open-source licensing (AGPL-3.0)
Technical Constraints:
Requires Rust toolchain for building AirGap Deploy itself
Preparation phase requires internet access (by design)
Installation phase must work completely offline
Package size limited by available storage media
Design Constraints:
Command-line interface only (no GUI)
Declarative manifest format (TOML)
Cross-platform compatibility (Linux, macOS, Windows)
Assumptions and Dependencies
Assumptions:
Developer has internet access during package preparation
Target air-gapped system has basic build tools (C compiler, make)
Users can physically transfer files via USB or similar media
Dependencies:
External: Git, cargo, platform-specific package managers
Rust crates: See Roadmap (Dependencies Summary) for complete list
Functional Requirements
Manifest Parsing and Validation
The system SHALL parse AirGapDeploy.toml files using TOML syntax. |
The system SHALL validate manifest structure and required fields before processing. |
The system SHALL support the following manifest sections: |
The system SHALL provide clear error messages for invalid manifests, including line numbers and expected values. |
The system SHALL support schema versioning to enable future manifest evolution. |
Component Collection
Rust Application Component
The system SHALL collect Rust application source code from local directories. |
The system SHALL execute cargo vendor to download and vendor all Cargo dependencies. |
The system SHALL optionally include Rust toolchain installer for offline builds. |
The system SHALL generate .cargo/config.toml to configure vendored dependency usage. |
The system SHALL support configuration options: source, vendor, include_toolchain, prebuild |
External Binary Component
The system SHALL clone Git repositories for external binaries. |
The system SHALL support specifying Git branch, tag, or commit. |
The system SHALL include build instructions in installation scripts. |
The system SHALL support configuration options: name, repo, branch/tag/commit, build_instructions |
Model File Component
The system SHALL download model files from HTTPS URLs. |
The system SHALL verify downloaded files using SHA-256 checksums. |
The system SHALL display download progress with progress bars. |
The system SHALL support resume capability for interrupted downloads. |
The system SHALL support configuration options: name, url, checksum, required, install_path |
System Package Component
The system SHALL detect Linux distribution (Debian, Fedora, Arch). |
The system SHALL download system packages (.deb, .rpm, etc.) with dependencies. |
The system SHALL include system packages in deployment archive. |
The system SHALL configure installation scripts to install system packages. |
Note: SystemPackageComponent is marked as optional for MVP and may be deferred.
Packaging
The system SHALL create tar.gz archives for Linux and macOS deployments. |
The system SHALL create zip archives for Windows deployments. |
The system SHALL organize package contents with standardized directory structure. |
The system SHALL generate airgap-deploy-metadata.json with package information. |
The system SHALL generate SHA-256 checksum for the entire package. |
The system SHALL support configurable compression levels. |
Installation Script Generation
The system SHALL generate Bash installation scripts (install.sh) for Linux/macOS. |
The system SHALL generate PowerShell installation scripts (install.ps1) for Windows. |
Installation scripts SHALL perform dependency checks, display plan, prompt for location, execute builds, configure files, set permissions, and log actions. |
Installation scripts SHALL support interactive mode and automatic (unattended) mode. |
Installation scripts SHALL detect existing installations and offer upgrade path. |
Installation scripts SHALL verify sufficient disk space before proceeding. |
Installation scripts SHALL provide clear error messages and recovery instructions. |
Command-Line Interface
The system SHALL provide commands: prep, validate, init, list-components with appropriate arguments. |
The system SHALL display colored output for improved readability. |
The system SHALL display progress bars for long-running operations (downloads, compression). |
The system SHALL support –verbose flag for detailed logging. |
The system SHALL support –help flag for all commands. |
Configuration Management
The system SHALL support global configuration file at ~/.airgap-deploy/config.toml. |
The system SHALL support global configuration options: default_target, cache_dir, proxy. |
Command-line arguments SHALL override global configuration. |
Error Handling and Recovery
The system SHALL provide clear, actionable error messages for all failure modes. |
The system SHALL suggest recovery steps for common errors: missing dependencies, network failures, disk space issues, invalid manifests. |
The system SHALL exit with non-zero status codes on errors. |
The system SHALL log all operations to enable debugging. |
Non-Functional Requirements
Performance
Package preparation SHALL complete in less than 5 minutes for typical applications (<1GB components). |
Large model downloads (1-10GB) SHALL display progress and support resume. |
Parallel component collection SHALL be used where possible to reduce preparation time. |
Installation scripts SHALL complete in less than 20 minutes for typical applications (including build time). |
Reliability
The system SHALL verify all downloaded files using SHA-256 checksums. |
The system SHALL retry failed network operations up to 3 times with exponential backoff. |
Installation scripts SHALL be idempotent (safe to run multiple times). |
The system SHALL handle interruptions gracefully (Ctrl+C, system shutdown). |
Usability
First-time users SHALL be able to create a deployment package within 10 minutes using provided examples. |
Error messages SHALL include specific details about the failure and suggested fixes. |
The CLI SHALL provide help text accessible via –help for all commands. |
Progress indicators SHALL be shown for all operations taking longer than 2 seconds. |
Maintainability
The codebase SHALL achieve at least 80% test coverage. |
All public APIs SHALL have rustdoc documentation. |
The code SHALL pass cargo clippy with zero warnings. |
The code SHALL be formatted with rustfmt. |
Portability
The system SHALL run on Linux (Ubuntu 20.04+, Fedora 35+, Debian 11+). |
The system SHALL run on macOS (10.15+, both Intel and Apple Silicon). |
The system SHALL run on Windows (Windows 10/11). |
Generated installation scripts SHALL be compatible with Bash 4.0+ (Linux/macOS) and PowerShell 5.1+ (Windows). |
Security
The system SHALL verify checksums for all downloaded files. |
The system SHALL NOT execute arbitrary code from manifests. |
Installation scripts SHALL require explicit confirmation before destructive operations. |
The system SHALL use HTTPS for all network operations. |
Temporary files SHALL be created with restrictive permissions (user-only). |
Scalability
The system SHALL handle packages up to 50GB in size. |
The system SHALL support manifests with up to 100 components. |
Parallel collection SHALL scale with available CPU cores. |
Install scripts SHALL use platform-specific default paths (user: ~/.local on Linux/macOS, %LOCALAPPDATA% on Windows; system: /usr/local on Linux/macOS, C:Program Files on Windows) |
External Interface Requirements
User Interfaces
The system SHALL provide a command-line interface with ANSI color support. |
The system SHALL display progress bars for long-running operations (using indicatif crate). |
The system SHALL provide interactive prompts in generated installation scripts. |
Hardware Interfaces
The system SHALL use standard filesystem I/O (no special hardware requirements). |
The system SHALL use network interface for downloading components during prep phase. |
The system SHALL support removable media (USB drives) for package transfer (OS-provided). |
Software Interfaces
The system SHALL integrate with |
The system SHALL integrate with |
The system SHALL use HTTP/HTTPS clients for downloading models and packages. |
The system SHALL integrate with system package managers (apt, dnf, pacman) for SystemPackageComponent. |
The system SHALL integrate with AirGap Transfer for large package chunking (workflow level, not code level). |
Communications Interfaces
The system SHALL use HTTP/HTTPS for downloading components (preparation phase only). |
The system SHALL NOT use network communication during installation phase (enforced by air-gap). |
Enhanced Installation Features
The following requirements address gaps identified in use case analysis.
Component Selection
Components SHALL support |
The CLI SHALL support |
Configuration Generation
Install scripts SHALL generate configuration files from templates |
Manifests SHALL support |
Manifests SHALL support |
Installation Modes
Install scripts SHALL support interactive mode with user prompts |
Install scripts SHALL support automatic mode with environment variables (MODE=automatic) |
Manifests COULD support |
Dependency Management
Manifests SHALL support |
Install scripts SHALL verify dependencies before building components |
Install scripts SHALL verify sufficient disk space before installation Note This requirement covers disk space verification at install time. For disk space verification during the prep phase, see Verify Disk Space (FR-DEPLOY-035). |
v1.1 — Bill of Materials and Vulnerability Scanning
The following requirements are planned for v1.1 and are not in scope for the MVP release.
SBOM Generation
The system SHALL generate a CycloneDX JSON SBOM during the |
The system SHALL parse |
The system SHALL extract license information for each dependency from |
The SBOM SHALL include component metadata: package name, version, supplier/source URL, and SHA-256 checksums for all collected components. |
The system SHALL include the generated SBOM in the deployment archive by default. |
CBOM Generation
The system SHALL scan |
The CBOM SHALL document hash algorithms used by AirGap Deploy itself (e.g., SHA-256 for checksum verification). |
The CBOM data SHALL be included in the CycloneDX SBOM document as a single unified file, per the CycloneDX specification. |
Vulnerability Scanning
The system SHALL provide an |
The scan subcommand SHALL support an offline vulnerability database provided by the user (e.g., a pre-downloaded Grype or Trivy database), requiring no network access. |
The scan subcommand SHALL generate vulnerability reports in both JSON (machine-readable) and human-readable formats. |
The scan subcommand SHALL exit with a non-zero status code when vulnerabilities exceed a configurable severity threshold (e.g., |
v1.0 — Additional Component and Configuration Support
The following requirements were identified during use case analysis (Ollama deployment) and are included in the v1.0 release.
Config File Component
The system SHALL support a |
GitHub Release Source
The system SHALL support a |
Extended Install Section
The system SHALL support |
Configuration Management Output
The system SHALL support a |
Nested Source Fields
Component configuration SHALL support nested |
Appendices
Example Manifest
[package]
name = "example-app"
version = "1.0.0"
description = "Example application for air-gap deployment"
[targets]
platforms = ["linux-x86_64", "macos-aarch64"]
default = "linux-x86_64"
[[components]]
type = "rust-app"
source = "."
vendor = true
include_toolchain = true
[[components]]
type = "external-binary"
name = "dependency"
repo = "https://github.com/example/dependency.git"
tag = "v1.0.0"
build_instructions = "make"
[[components]]
type = "model-file"
name = "model"
url = "https://example.com/model.bin"
checksum = "sha256:abc123..."
required = true
[install]
method = "build-from-source"
install_to = "user"
mode = "interactive"