Deploys and rollbacks

A deploy puts one version of your service online. Ferry starts the new version next to the old version, tests it, then moves the traffic. If the new version fails, the old version stays online.

ferry deploy api --follow

--follow shows the log until the deploy is live. If the deploy fails, the command stops with the exit code 1.

What starts a deployCopy Anchor Link

Each deploy records its trigger: the cause that started it.

A manual deploy builds the newest commit of the branch, pulls the Docker image again, or uses the last upload. It depends on the source of the service.

ferry deploy api --commit <sha>     # build this exact commit (git services)
ferry deploy api --clear-cache      # build without the Docker cache

The steps of a deployCopy Anchor Link

The same steps show in the deploy log. The lines that start with ==> come from Ferry:

==> Starting deploy dep-ba5a7fce730d4061aaa7 (trigger: upload)
==> Build successful 🎉
==> Starting 1 instance(s)
==> Waiting for 1 instance(s) to become healthy: the port must accept TCP connections (timeout 120s)
==> Health check passed
==> Routing traffic to the new instance(s)
==> Stopping 1 old instance(s)
==> Your service is live 🎉

If a step fails, Ferry removes the new instances. It does not touch the old instances. Your service stays online.

See the deploys of a serviceCopy Anchor Link

ferry deploys api                                  # the 20 newest deploys (-n for more)
ferry logs --deploy dep-ba5a7fce730d4061aaa7 -f    # the log of one deploy

ID                         STATUS          TRIGGER      COMMIT   CREATED   DURATION
dep-fad68a5ea71b43ae9820   live            upload       -        7m ago    2s
dep-d21d077ff8464b4a9501   deactivated     manual       -        11m ago   2s
dep-ca4bc7b5862742959b70   deploy_failed   upload       -        17m ago   1s
✗ dep-ca4bc7b5862742959b70: instance d1c6b8 crashed (exit code 1)

The cause of a failure is at the end of the list. In the dashboard, open the deploy from the Deploys page and read the Why it failed box.

Health checksCopy Anchor Link

A health check is the test that a new instance must pass before it gets traffic. Ferry tests each new instance one time each second.

Set a path for a better test. Make an endpoint only for this test. It must answer quickly when the app is ready.

ferry update api --health /healthz

In the dashboard, use Health check path in the settings of the service. The path applies at the next deploy.

When the health check failsCopy Anchor Link

If no good answer comes before the timeout (120 seconds), the deploy gets the status deploy_failed. Ferry removes the new instances, and the old instances continue to answer. To find the cause, read the deploy log:

• Each 10 seconds, the log tells you why an instance is not healthy.
• If an instance stops during the test, the deploy fails immediately. Ferry copies the last 50 lines of its output into the log.
• If an instance uses too much memory, the error is instance ab12cd ran out of memory (limit 512 MiB) — raise the service's memory limit.

A frequent cause is an app that listens on 127.0.0.1 or on a different port. Your app must listen on 0.0.0.0 and on the port in PORT. The log shows the port that Ferry chose:

==> Using port 8000 (EXPOSEd by the image)

To give a slow app more time, start ferryd with --health-check-timeout. After the deploy, Ferry does not use the health check path again.

The zero-downtime switchCopy Anchor Link

With zero downtime, your app answers during the full deploy. The proxy moves the traffic in one step, after all the new instances pass their health check. The previous live deploy becomes deactivated.

Then Ferry stops the old instances. For a web service or a static site, Ferry first waits 2 seconds for the requests in progress. Then each old instance has 10 seconds to stop.

Redeploy or restartCopy Anchor Link

To build your code again, run ferry deploy. To start new instances from the live image with the current settings and variables, run ferry restart. A restart builds nothing, and it also has zero downtime.

ferry restart api --follow

A live deploy keeps a snapshot of its settings. Thus a change applies only at the next deploy or restart:

You cannot restart a service that has no live deploy and no deploy in progress. Deploy it first.

Roll back to a previous deployCopy Anchor Link

A rollback is a new deploy that uses the image of an earlier deploy. Ferry builds nothing.

ferry deploys api                                      # find the id of a good deploy
ferry rollback api dep-3493c505ea9b4415b359 --follow

In the dashboard, open Deploys. In the menu of a deploy, choose Roll back to this deploy.

• You can roll back only to a deploy with the status live or deactivated. A failed or canceled deploy was never live.
• A rollback gives you the old code. The instances start with the current settings and variables.
• Ferry keeps the 5 newest images of each service, and the live image. To keep more, start ferryd with --keep-images.

If Ferry removed the image, the rollback fails and shows the cause. Then deploy from the source again.

Cancel a deployCopy Anchor Link

ferry cancel dep-7d2d938ff3614c238ecb

You can cancel a deploy until the proxy sends traffic to the new version. The dashboard has a Cancel deploy button on the page of the deploy.

==> Build canceled
==> Deploy canceled: canceled by user

error: too late to cancel: traffic was already switched to deploy dep-817fc76633764f7181c0 (roll back to undo it) (conflict)

A new deploy also cancels the older deploys of the same service that wait in the queue.