Generation 1 » Health Checks


This documentation is for Generation 1 applications.

By default, for a deployment to succeed, it must pass certain “health checks.”

If the Process does not expose ports it is considered healthy if it starts and doesn’t immediately exit or crash.

If the Process exposes ports is it considered healthy after it:

  • Registers behind a load balancer
  • Passes a certain number of network connection health checks

Common causes for not passing health checks are:

  • The cluster does not have sufficient memory or CPU resources available to start a new process
  • The cluster does not have sufficient instances where a new process port is not already reserved by an older release
  • A process crashes immediately after starting due to a problem in the latest code
  • A process takes too long to initialize its server and therefore fails a network health check

Health Check Options

By default Convox will set up a tcp health check to your application, defining that a process must boot and pass the network health check in 3 seconds. If your app takes longer to boot, you may need to increase this to up to 60 seconds by adding a label by adding one or more of the following labels to your docker-compose.yml file.

version: "2"
services:
  web:
    labels:
        - convox.health.interval=10
        - convox.health.path=/_health
        - convox.health.port=5000
        - convox.health.threshold.healthy=3
        - convox.health.threshold.unhealthy=4
        - convox.health.timeout=3
    ports:
      - "443:5000"
Label Notes
interval The amount of time in between health checks. Default is timeout + 2 seconds.
path The endpoint the load balancer will use to determine the application's health.
port This is the port that your container is set up to listen on, not the load balancer port.
threshold.healthy The number of consecutive successful health checks that must occur before declaring an EC2 instance healthy. Default is 2.
threshold.unhealthy The number of consecutive failed health checks that must occur before declaring an EC2 instance unhealthy. Default is 2.
timeout The time in seconds after which no response means a failed health check (3 seconds by default; 60 seconds maximum).

See also