Deployments & Blue/Green Releases

MicroFly provides zero-downtime blue/green deployment workflows for native binaries and Java applications without requiring container builds or complex registries.

---

Deployment Mechanics

When you run microfly deploy --dir . <app>, MicroFly performs a 6-stage release pipeline:

1. Pack & Archive ──► 2. Stage Immutable Release ──► 3. Pre-Deploy Migration
                                                             │
                                                             ▼
6. Scale-to-Zero  ◄── 5. Ingress Traffic Cutover ◄── 4. Systemd Health Check

1. Pack & Archive: MicroFly packages the target directory into a tar stream, ignoring .git metadata and symlink traversals.
2. Immutable Staging: The release is extracted into an immutable versioned directory: /var/lib/microfly/apps/<app>/releases/<timestamp>-<seq>/ Files are set read-only (mode 0550) owned by root:microfly-app.
3. Pre-Deploy Migration (release_command): If configured in app.toml, MicroFly executes this command inside the newly staged release directory. If it exits with an error, the deployment aborts immediately, leaving the running release untouched.
4. Candidate Unit & Health Check: MicroFly boots a transient candidate service (microfly-<app>-web-<seq>.service) on a temporary port. It polls the configured [health_check] endpoint until receiving the expected HTTP status code.
5. Atomic Traffic Cutover: Once healthy, the ingress router points all configured domains to the new release. The previous release is stopped cleanly after a grace period.
6. Scale-to-Zero Verification: If scale_to_zero = true is configured, the instance is scaled down to 0, ready to awaken in ~200ms upon the next incoming HTTP request.

---

Deploying an Application

To deploy an application from the current directory:

sudo microfly deploy --dir . my-app

To deploy from a specific folder:

sudo microfly deploy --dir /var/projects/my-app my-app

---

Pre-Deploy Release Commands

Production applications often require database migrations or cache warmup tasks to execute before traffic shifts to the new release. Configure release_command in app.toml:

[deploy]
release_command = ["./bin/app", "db", "migrate"]

Safety Guarantees

• The release_command runs inside the candidate release with all environment variables, mounted persistent storage, and decrypted secrets injected.
• If the command fails (non-zero exit status), the release is not activated. Existing production traffic continues serving uninterrupted on the previous release.

---

Zero-Downtime Rolling Restarts

When you update an environment variable or rotate secrets, MicroFly triggers a zero-downtime rolling restart:

sudo microfly restart my-app

MicroFly starts a new candidate process, validates its health checks, and shifts traffic before stopping the old instance. At no point during the restart is the application unreachable.

---

Release History & Instant Rollbacks

Listing Releases

To inspect the immutable release history and see which release is currently active:

sudo microfly releases my-app

Output:

Releases for my-app (current: 20260903T101530.987654321Z-000002):
  * 20260903T101530.987654321Z-000002 (active)
    20260903T100000.123456789Z-000001
    20260903T090000.000000000Z-000000

Instant Rollbacks

If a bad release reaches production, you can instantly roll back to the previously active release:

sudo microfly rollback my-app

Or roll back to an explicit historical release ID from the list:

sudo microfly rollback my-app 20260903T090000.000000000Z-000000

Output:

rolled back my-app to 20260903T090000.000000000Z-000000

Characteristics of MicroFly Rollbacks

• Zero Build Time: Rollbacks do not recompile or download packages; they immediately activate the preserved immutable release directory on disk.
• Storage Persistence: Persistent volumes mounted in [storage] are preserved across rollbacks.
• Fast: Rollback activation occurs within milliseconds.

---

Managing Process Lifecycle

You can manually control workload execution without deleting application data:

# Temporarily stop an application
sudo microfly apps stop my-app

# Resume a stopped application
sudo microfly apps start my-app

# Permanently destroy an application and delete all its releases
sudo microfly apps destroy my-app