Deployments with Docker Compose

Deploying updates to Terrateam with Docker Compose can be done without downtime by following these instructions.

These instructions assume:

You have multiple compute instances running Docker Compose with Terrateam.
A load balancer distributes traffic between these instances.

Run Multiple Instances

To maintain availability during deployments, always run at least two instances of the server container behind a load balancer. This ensures that at least one instance is always handling requests while another is being updated.

Use Load Balancer Health Checks

The load balancer should only route traffic to healthy instances.

Configure the load balancer to check the /health endpoint.
This ensures traffic is not sent to containers that are starting up or failing.

Rolling Updates with Docker Compose

The following steps outline a zero-downtime deployment using Docker Compose.

1. Drain One `server` Instance from the Load Balancer

Mark one instance as draining in the load balancer to stop new connections.
Allow active requests to complete before proceeding.

2. Update `docker-compose.yml` with the New Image Tag

Modify the image field for the drained server instance:

services:
  server:
    image: ghcr.io/terrateamio/terrat-oss:<new-tag>
    # If using the Enterprise Edition, replace `terrat-oss` with `terrat-ee`

3. Pull the New Image and Deploy the Updated Instance

Fetch the latest image:
```
docker-compose pull server
```
Restart the server service:
```
docker-compose up -d server
```
This stops the old container and starts a new one with the updated image.

4. Verify Health Before Putting It Back in Rotation

Wait for the load balancer to detect the instance as healthy via /health.
Once healthy, allow traffic to the instance.

5. Repeat for the Second Instance

Drain the second instance.
Pull the new image:
```
docker-compose pull server
```
Restart it:
```
docker-compose up -d server
```
Wait for health checks to pass, then reintroduce it to the load balancer.

Key Takeaways

Always run at least two instances behind a load balancer.
Use /health for load balancer health checks.
Drain connections before restarting a container.
Ensure the new instance is marked healthy before sending traffic.

By following these instructions, you can ensure zero-downtime deployments for Terrateam with Docker Compose.