Deployment Lifecycle

Forge treats deployments as jobs. A service can have many deployments over time, but only one deployment per service can build at once.

Deployment Triggers

Deployments can be created by:

• Clicking Deploy in the service Deployments tab.
• GitHub push webhooks for GitHub-connected services.
• Railway import automation when Auto-deploy services is enabled.
• Forge migration import follow-up deployment queueing for restored active app services.

Every deployment records its trigger.

Queue and Concurrency

System Settings includes Concurrent deployments. The default is 3; the allowed range is 1 through 10.

Forge uses that global number as the deployment slot limit. It also prevents two deployments for the same service from running at the same time.

If all slots are full, new deployments stay queued until a slot opens.

Statuses

• queued: waiting for an available global slot.
• building: work has started.
• running: the deployment is the current live deployment for the service.
• superseded: a newer deployment became live.
• aborted: a queued or building deployment was stopped.
• failed: the deploy could not complete.

Older running deployments are marked superseded when a newer deployment succeeds.

Aborting Deployments

You can abort queued or building deployments from the Deployments tab.

For queued deployments, Forge marks the job aborted before it starts.

For building deployments, Forge marks the job aborted, asks the active process to stop, then escalates to a force kill if needed. Any temporary containers are cleaned up by the deployment flow.

Web Hot Swaps

For source-built web services and Docker image web services, Forge keeps the old container live while the new container proves it can answer on the configured port.

The hot swap flow is:

1. Build or pull the image.
2. Start a temporary container.
3. Probe the configured internal port.
4. Store the new active port.
5. Reload Caddy.
6. Remove the old stable container.
7. Mark the new deployment running.

If the new container does not become reachable, Forge keeps the previous service state instead of switching traffic.

Rollbacks

Forge supports manual app rollbacks from the Deployments tab for superseded successful app deployments.

A rollback creates a new deployment event with trigger rollback. Forge does not mutate the old deployment record. The rollback flow:

1. Reads the selected deployment’s stored image tag.
2. Reads the encrypted environment snapshot and runtime snapshot captured for that deployment.
3. Verifies the rollback image is still available on the host.
4. Starts a replacement container or exports the static site output.
5. Health-checks the replacement before promotion.
6. Switches Caddy traffic for web services.
7. Marks the rollback deployment running and marks the previous current deployment superseded.

Rollback prefers deployment metadata captured by a recent Forge version. Older deployments that predate rollback metadata can still roll back if their image is still present on the host; Forge uses the selected old image with the current service environment and runtime settings, and shows that warning before queueing the rollback.

Forge does not run release commands during rollback. It also does not undo database migrations or data changes. If an older app version requires older database state, restore a database backup or run an explicit reverse migration.

Workers and Static Sites

Worker deployments check that the process stays running. There is no HTTP port probe.

Static site deployments export files from the built image into the static site directory. Forge verifies that the output contains index.html before marking the deployment running.

Database Deployments

Database deployments are different from app hot swaps. Forge runs database containers with persistent Docker volumes. Deploying a database service ensures the image, volume, runtime network, public hostname route, Postgres TLS assets, and logical replication settings are in place.

Database container replacement can interrupt connections, so schedule database deploys with more care than app deploys.

Logs

Deployment logs show clone, build, image pull, runtime, Caddy, and health check output. Runtime logs show output from the running container after deployment.

When a deployment fails, start with the deployment log. If the service started but did not answer on the configured port, compare the app logs with the service internal port setting.