How a deployment works

The stages

1. Clone

   The branch's latest commit is cloned with your GitHub access. Nothing else of the repository's history is kept.

2. Detect

   The project is recognised from its files — a Dockerfile first, then the frameworks in What it can build.

3. Build

   An image is built with Docker BuildKit. A build may take up to 15 minutes.

4. Release command

   If you set one, it runs once in the new image before anything of the new version starts — the place for database migrations. If it fails, the deployment stops here.

5. Health check

   A new container starts next to the running one. It must answer an HTTP request on its health check path (/ unless you change it) with a status from 200 to 399, within about a minute.

6. Switch

   Traffic moves to the new container and the old one is stopped. Visitors see no gap.

When something fails

A deployment that fails at any stage changes nothing: the version that was running keeps serving. The reason is on the deployment, with the end of the log, and a notification is sent if you set one up.

When the log shows why — a package that does not exist, the app listening on the wrong port or only on localhost, a variable that is not set, running out of memory, a syntax error, a start command that is not installed — the deployment says so under Likely cause, with what to change and the lines of the log that show it. It names a cause only when such a line is in the log; otherwise there is none, and the log speaks for itself. The CLI prints it, and agents read it as likely_cause.

Deploying on every push

With Deploy automatically on push on, the branch is checked about once a minute and a new commit is deployed by itself. A push during a build is deployed when that build finishes. A commit whose deployment failed is not retried until the next push. For instant deploys, add the optional webhook shown in the project's settings to the repository.

Rolling back

The images of the last three successful deployments are kept. Roll back starts one of them again and switches traffic once it is healthy — a few seconds, because nothing is cloned or built. Only the code goes back; variables and settings stay as they are now.

arrah rollback my-api            # the previous deployment
arrah rollback my-api --to 12    # a particular one

Rolling back by itself

If a new version crashes, or fails three health checks in a row (they run once a minute), within 10 minutes of going live, the version before it is started again — without a build — and you are told. The failed deployment is marked failed with the reason. The earlier version must pass its own health check before it takes traffic, and a rollback is never rolled back by itself. It is on for every project; turn it off under Roll back automatically in the project's settings.

Previews and branch environments

A branch environment is an isolated copy of a project: its own address, variables, private network and — if the project has a database — its own copy of the data. With pull request previews on, each open pull request from the project's own repository gets one automatically, announced in a comment and removed when the pull request closes. Up to 5 branch environments per project, 3 of them previews. They sleep when idle.