Air-Gapped Deployments: How to Deploy to Servers Without Internet Access (Complete Guide)

Deploying to servers with no internet access—also known as air-gapped environments—is a common requirement in regulated industries, enterprise on-prem setups, and high-security networks. However, most modern CI/CD pipelines assume constant access to public registries, APIs, and external services.

This mismatch is one of the biggest causes of failed deployments when teams move from standard cloud environments to restricted networks.

In this guide, you’ll learn how to deploy applications without internet access, including proven strategies, tools, and patterns used by production engineering teams.

What Is an Air-Gapped Environment?

An air-gapped environment is a system or network that is physically or logically isolated from the public internet. These environments are designed to maximize security by preventing external communication.

Common use cases include:

• Financial institutions and regulated industries
• Government and defense systems
• On-prem enterprise infrastructure
• Internal production networks with strict security policies

Why Deployments Fail Without Internet Access

Most CI/CD pipelines are built around assumptions that break in air-gapped environments:

• Pulling dependencies from npm, pip, Maven, or apt
• Downloading Docker images from Docker Hub
• Calling external APIs during deployment
• Installing packages at runtime

Typical errors teams encounter:

• “Cannot reach package registry”
• “Docker pull failed”
• “Dependency install timeout”

The root cause is simple: deployments rely on external resources that are unavailable.

Core Principle: Build Once, Deploy Anywhere

The key to reliable air-gapped deployments is shifting your pipeline design:

❌ Pull dependencies during deployment
✅ Package everything during CI

This means your CI pipeline must produce a fully self-contained artifact that includes:

• Application code
• All dependencies
• Runtime components (if needed)
• Configuration templates

Once built, deployment becomes a simple transfer + execution step.

Approach 1: Artifact-Based Deployments (Recommended)

This is the most common and reliable method.

Instead of installing dependencies on the target server, you package everything during CI.

Example (Node.js)

npm ci
npm run build
tar -czf app.tar.gz dist/ node_modules package.json

Semaphore CI Example

version: v1.0
name: Build and Package

blocks:
  - name: Build
    task:
      jobs:
        - name: Build app
          commands:
            - checkout
            - npm ci
            - npm run build
            - tar -czf app.tar.gz dist/ node_modules package.json
      artifacts:
        files:
          - app.tar.gz

Deployment (Offline)

tar -xzf app.tar.gz
npm start

No internet required.

Approach 2: Private Package Registries and Mirrors

If your environment allows internal networking, you can mirror dependencies inside the network.

Popular tools:

• npm: Verdaccio, Nexus
• Python (pip): Devpi
• Docker: Private registry
• OS packages: Aptly, Artifactory

Example: Docker Image Push/Pull

docker build -t registry.internal/app:1.0 .
docker push registry.internal/app:1.0

Inside the air-gapped network:

docker pull registry.internal/app:1.0

This approach preserves developer workflows while removing external dependencies.

Approach 3: Docker Image Transfer (Offline)

If no registry access is possible, transfer images as files.

docker save app:1.0 -o app.tar

Transfer the file securely, then:

docker load -i app.tar

This method is widely used in highly restricted environments.

Approach 4: Immutable Infrastructure (Golden Images)

For larger systems, consider building pre-configured machine images.

Using tools like Packer:

packer build image.json

The resulting image includes:

• Application
• Dependencies
• Configuration

Deployment becomes provisioning infrastructure instead of running scripts.

How to Handle Secrets in Air-Gapped Deployments

Secrets management becomes more complex without external services.

Best practices:

• Inject secrets at deploy time (not build time)
• Use encrypted configuration bundles
• Avoid embedding credentials in artifacts
• Use internal secret management systems where possible

Networking Patterns That Work

Common real-world setups:

• Bastion host for controlled access
• One-way artifact transfer (CI → production)
• Scheduled sync between environments

Avoid manual, untracked file transfers whenever possible.

End-to-End Air-Gapped Deployment Workflow

1. Developer pushes code
2. CI pipeline builds application
3. Dependencies are bundled into artifact or image
4. Artifact is transferred into secure network
5. Deployment runs locally (no internet required)

This ensures reproducibility and consistency across environments.

Common Mistakes to Avoid

• Installing dependencies during deployment
• Relying on external APIs at runtime
• Not versioning artifacts
• Manual deployments without audit trail

These issues lead to fragile and non-reproducible systems.

Benefits of Proper Air-Gapped Deployment Strategy

Organizations that adopt these patterns see improvements in:

• Deployment reliability
• Change failure rate
• Security posture
• Operational efficiency

Final Thoughts

Air-gapped deployments introduce constraints—but also force better engineering practices.

By adopting a build once, deploy anywhere model, teams can achieve:

• More predictable releases
• Fewer deployment failures
• Better scalability across environments

If your current pipeline struggles in restricted environments, it’s a strong signal that it relies too heavily on runtime assumptions.

Fixing that will improve your entire delivery process—not just air-gapped deployments.

FAQ: Air-Gapped Deployments