Zero-downtime deployments

Every time an application is redeployed on Porter (through a GitHub action, configuration change, etc), a new set of application instances will replace the old ones. While the update process attempts to prevent downtime, there are additional configuration settings to ensure zero downtime during re-deployment:

• Health Checks - Ensure new instances are ready before receiving traffic
• Graceful Shutdown - Allow old instances to finish processing before termination

​

Health Checks

Health checks indicate whether an application is healthy and ready to receive traffic. When enabled, traffic won’t switch from the old application instance until the health check confirms the new instance is ready. Health checks can be configured in the Advanced tab of your service settings.

​

Web Services

For Web services, configure HTTP-based health checks where your application returns:

• 200 status code when ready to receive traffic
• 500-level error code when not ready

Health checks can be configured in the Advanced tab: For example, if you configure /healthz as your health check endpoint, no traffic will be routed to the web service until that endpoint returns a 200 status code.

​

Workers

For Worker services, you must set up health checks using custom commands or scripts instead of HTTP endpoints. This is useful for monitoring services like Celery workers that don’t expose HTTP endpoints. To configure command-based health checks, create a health check script that:

1. Executes the necessary commands to check your worker’s health
2. Returns exit code 0 if the worker is healthy
3. Returns a non-zero exit code if the worker is unhealthy

Then specify the path to your health check script in the Advanced tab of your service settings.

​

Graceful Shutdown

When applications are being re-deployed, old instances receive a SIGTERM termination signal. They are then given a Termination Grace Period—the number of seconds before the application is forcefully killed. During this period, your application should:

1. Stop accepting new work
2. Complete or close existing connections
3. Exit gracefully

The termination grace period can be configured in the Advanced tab.

​

Web Services

Web services keep receiving traffic until they are taken out of the routing, which does not happen the moment they start shutting down. The recommended graceful shutdown sequence is:

1. When SIGTERM is received, immediately return a 500-level response on your health check endpoint to mark the instance as unavailable.
2. Keep accepting new requests for a short drain window while routing catches up (see below), and start draining the connections you already hold.
3. Close the server to prevent additional connections once the drain window has passed.
4. Drain all existing connections before the grace period ends, then exit gracefully.

​

Why traffic keeps arriving after SIGTERM

When an instance is replaced, the orchestrator starts two things at around the same time: it sends SIGTERM to your process, and it begins taking the instance out of the routing. Neither one waits on the other, and neither one waits on your health check. Your 500-level response marks the instance as unavailable, but it is not the switch that stops traffic. Removal from the routing takes effect only once the router picks up the change, at least 1 to 5 seconds later. Every request dispatched before that still arrives at the instance, including requests sent after your process has already received SIGTERM. Size your drain window to cover that gap. A window of 5 to 15 seconds is a reasonable starting point, and the termination grace period must be longer than the drain window plus your slowest request.

​

Workers

For Worker services, implement graceful shutdown using signal handling and file-based coordination:

1. Trap the SIGTERM signal in your worker process or an init script for the service.
2. Write a shutdown marker to a file when the signal is received, indicating the worker should stop.
3. Adapt your health check script to check for this shutdown marker:
   • If the marker indicates shutdown is in progress, the script should return a non-zero exit code.
   • This signals to Porter that the worker is no longer healthy and should not receive new work.

​

High Availability

To ensure your applications are fault tolerant and resilient against failures, configure at least 3 instances for production workloads. This can be set in the Resources tab.