Skip to content

Docker Compose Update Process

Docker Compose Update Process

Standard Update Procedure

1. Check Release Notes

  • Review release notes for breaking changes
  • Look for required migrations or database updates
  • Check for new environment variables in .env file

2. Pull New Images

cd /path/to/docker-compose-directory
docker compose pull

Downloads the latest images without stopping containers.

3. Restart Containers

docker compose up -d

Stops old containers and starts new ones with updated images.

Command Syntax Note

Use docker compose (space, not hyphen). The old docker-compose (hyphen) still works but is the legacy standalone tool.

Version Management

Floating Tags (Auto-update)

image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
  • This uses tags like release, latest, or stable
  • Updates to the newest version when you pull
  • Good for staying current automatically

Pinned Versions (Manual control)

image: ghcr.io/immich-app/immich-server:v2.3.1
  • Stays on exact version until you change it
  • Better for production/critical services
  • Prevents surprise updates

Best Practices

Before Major Updates

  • Ensure backups are current
  • Check for special upgrade paths (e.g., v1.x → v2.x)
  • Review documentation for migration steps

After Updates

docker ps                                    # Check containers are running
docker logs <container_name>                 # Verify startup succeeded
docker logs <container_name> 2>&1 | grep -i error  # Check for errors

Quick Reference

# Standard update sequence
cd ~/app/docker
docker compose pull
docker compose up -d
docker ps
docker logs <container_name>

Common Applications

This process works for most containerized apps:

  • Immich
  • Mealie
  • Paperless-ngx
  • Jellyfin
  • And most Docker Compose deployments