Merge pull request #327 from terrateamio/326-deployments-with-docker-…

…compose

#326 ADD deployments with docker-compose documentation

docs/src/content/docs/self-hosted/deployments-with-docker-compose.mdx

@@ -0,0 +1,84 @@
+---
+title: Deployments with Docker Compose
+description: How to deploy Terrateam without downtime using Docker Compose
+---
+
+Deploying updates to Terrateam with [Docker Compose](https://github.com/terrateamio/terrateam/blob/main/docker/terrat/docker-compose.yml) 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.
+
+:::note
+Terrateam does not recommend running Docker Compose in production. Organizations should use a container orchestration platform like Kubernetes or ECS for better scalability and reliability.
+:::
+
+## 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:
+
+```yaml
+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.