Deployment Strategies

ACT provides two primary strategies for updating your applications. Choosing the correct strategy is vital for maintaining uptime and preventing data corruption, especially for stateful applications.

Blue/Green Deployment (Default)

Blue/Green is the safest way to deploy stateless applications (like web APIs, frontend apps, or microservices). It ensures zero-downtime by running two versions of your application simultaneously during the transition.

[!WARNING] Host Port Binding Incompatibility: Blue/Green deployment is NOT compatible with Host Port Bindings (HostConfig.PortBindings). Since two containers cannot bind the same host port (e.g., port 80) simultaneously on a single server, Blue/Green deployments require using the built-in Traefik routing for HTTP/HTTPS traffic. Do not use host port bindings with Blue/Green strategy.

How it works:

1. Build: ACT builds the new container image (the “Blue” version).
2. Start: The Blue container is started alongside the existing “Green” container.
3. Health Check: ACT waits for the Blue container to pass health checks (configured via health_check_path).
4. Traffic Switch: Once healthy, ACT instructs Traefik to route 100% of new traffic to the Blue container.
5. Draining: The Green container remains running for a “Drain Timeout” period (default: 5 seconds) to allow existing requests to finish. Learn more about Draining.
6. Cleanup: The Green container is stopped and removed.

Memory Warning: During step 2-5, both containers are running simultaneously. If your application uses 300MB of RAM and your server only has 512MB total, the deployment will likely fail depending on swap configuration (OOM Kill). For memory-constrained servers, consider using the Recreate strategy or ensuring you have 2x the required RAM available for the service.

State 1: Steady          State 2: Deploying          State 3: Switch & Drain
───────────────          ──────────────────          ───────────────────────

    [Green]                   [Green]                      [Green]
   (Active)                  (Active)                     (Draining)
                                │                             
                                ▼                             │
                              [Blue]                        [Blue]
                            (Starting)                     (Active)

Recreate Deployment

The Recreate strategy stops the existing container before starting the new one. This results in a brief period of downtime but is required for certain types of applications.

When to use Recreate:

• RWO Volumes (ReadWriteOnce): Cloud volumes (like AWS EBS or DigitalOcean Block Storage) often only allow a single container to mount them at a time.
• SQLite Databases: Since SQLite is a file-based database, multiple containers writing to the same file simultaneously can cause “Database is locked” errors or corruption.
• Singleton Workers: Background workers that should never have two instances running simultaneously (e.g., a cron worker that processes a queue).

[!CAUTION] Stateful App Warning: If your service uses a persistent volume for a database (like SQLite), you MUST use the “Recreate” strategy to prevent data corruption.

Connection Draining

Connection Draining is the period ACT waits between switching traffic to a new container and stopping the old one.

• Stateless APIs: A short timeout (5-10 seconds) is usually sufficient.
• WebSockets/Long-Polling: Use a longer timeout (30-60 seconds) to allow clients to reconnect gracefully.
• Long-Running Tasks: If your app processes long uploads or complex calculations, set the timeout higher (up to 300 seconds).

You can configure the drain_timeout per service in the Advanced deployment settings.

Summary Comparison

Build Engine: Nixpacks & Dockerfiles

ACT uses Nixpacks to automatically detect and build your application if no Dockerfile is present.

Nixpacks Auto-Detection

Nixpacks looks for specific files to determine the language:

• Node.js: package.json
• Python: requirements.txt or pyproject.toml
• Go: go.mod
• Rust: Cargo.toml
• PHP: composer.json or index.php

If your project structure is non-standard (e.g., source code in a /backend subdirectory), you may need to specify the Build Context Directory in the service settings, or provide a custom nixpacks.toml.

Registry Matching Logic

When deploying a private image (e.g., ghcr.io/user/repo), ACT needs to know which credentials to use. It uses “Synonym Matching” to find the right registry.

• Exact Match: If you added a registry ghcr.io, it matches.
• Synonyms:
  • index.docker.io matches docker.io and images like myuser/myrepo (which implies Docker Hub).
  • registry-1.docker.io is treated as a synonym for Docker Hub.

Troubleshooting: If you get an “Access Denied” or “Manifest not found” error during pull, ensure the Registry URL you entered in ACT matches the domain part of your image string.