Deploying Docker Compose Service Updates

This guide covers the deployment workflow for applying modifications (like code logic or layout styles) to active containerized services running via Docker Compose. It details how to invalidate the layer cache and force container recreation.

• Deploying Docker Compose Service Updates
  • 🚀 Deployment Checklist
  • 💡 Troubleshooting Stale UI or Logic
    • 1. Active Container Lifecycle Out-of-Sync
    • 2. Aggressive Browser Caching
  • 📚 Related Concepts

---

🚀 Deployment Checklist

Follow this checklist to build, deploy, and verify changes to a specific service in your Compose stack.

• Step 1: Pull the latest codebase changes Execute a git pull in your target production/staging directory:

git pull

• Step 2: Force Rebuild the Service Image Instruct Docker to compile a fresh image. Use --no-cache if you updated package dependencies or system libraries to force complete retrieval:

docker compose -f docker-compose-prod.yml build --no-cache fastapi-app

• Step 3: Recreate the Service Container Recreate the running container using the newly compiled image without bringing down unrelated services:

docker compose -f docker-compose-prod.yml up -d --no-deps fastapi-app

¹

• Step 4: Verify Container Health Check the log stream of the newly deployed container to ensure no initialization errors:

docker compose -f docker-compose-prod.yml logs --tail=50 -f fastapi-app

---

💡 Troubleshooting Stale UI or Logic

If your code changes are not reflecting on the client browser after deployment, run through these check points:

1. Active Container Lifecycle Out-of-Sync

Staging vs Active Lifecycle

Running docker compose build only updates the stored disk image; it does not automatically replace the active running container instance. The container remains executing the older layer until it is destroyed and recreated via docker compose up.

You can combine the build and recreate steps into a single atomic execution to prevent this out-of-sync state:

docker compose -f docker-compose-prod.yml up -d --build --no-deps fastapi-app

Note: Why --no-deps?

The --no-deps flag is used to prevent restarting other services that depend on the one you're updating. In this case, it prevents restarting the database container, which would cause possible data loss.

2. Aggressive Browser Caching

Mobile browsers and local caching proxies aggressively store static assets (CSS, JS) and HTML frames to preserve cellular data.

How to Force Clear Client Caches

• Desktop: Perform a Hard Reload using Ctrl + Shift + R (Windows/Linux) or Cmd + Shift + R (macOS).
• Mobile: Open an Incognito/Private tab, or navigate to your browser settings to manually clear cached website files.

---

📚 Related Concepts

• Docker Container Lifecycle and Recreation — Detailed container state and lifecycle boundaries.

• Containerization Theory — Basic building blocks of Docker engine and daemon socket configuration.

---

1. The --no-deps flag tells Docker Compose not to start or restart any services that fastapi-app depends on (like database containers), preventing unnecessary service interruptions. ↩