Docker + VPS 2026 — Best Practices
Docker Compose v2 (2026 Standard)
# ✅ 2026 — Docker Compose v2 (built into Docker)
docker compose up -d
docker compose build
docker compose logs -f service-name
# ❌ Legacy v1 (deprecated, removed in 2024)
docker-compose up # hyphenated — never use
Python Container (uv-based, 2026)
FROM python:3.12-slim-bookworm
# Copy uv from official image — always pin the version tag
COPY --from=ghcr.io/astral-sh/uv:0.10.7 /uv /uvx /bin/
WORKDIR /app
# Layer cache: install deps before copying app code
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev
COPY . .
RUN uv sync --frozen --no-dev
ENV PATH="/app/.venv/bin:$PATH"
# Never run as root
RUN useradd -m appuser && chown -R appuser:appuser /app
USER appuser
CMD ["python", "-m", "api.main"]
Browser Automation Container (Xvfb + Camoufox)
FROM python:3.12-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:0.10.7 /uv /uvx /bin/
# System deps for Firefox + virtual display
RUN apt-get update && apt-get install -y --no-install-recommends \
xvfb x11vnc \
libgtk-3-0 libdbus-glib-1-2 libxt6 libx11-xcb1 \
libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
libasound2 libpangocairo-1.0-0 libatk1.0-0 \
libatk-bridge2.0-0 libcups2 libdrm2 libgbm1 \
curl procps \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev
# Download Camoufox Firefox binary
# ⚠️ Verify the expected version in pyproject.toml; camoufox fetch downloads
# a pre-built Firefox binary — pin the camoufox package version in uv.lock
# and validate the download hash when possible.
RUN uv run python -m camoufox fetch
COPY . .
RUN uv sync --frozen --no-dev
ENV PATH="/app/.venv/bin:$PATH"
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
Docker Compose — Full Stack
# docker-compose.yml
services:
browser:
build:
context: ./browser
dockerfile: Dockerfile
container_name: threads-browser
restart: unless-stopped
environment:
DISPLAY: ":99"
SCREEN_RES: "1920x1080x24"
ports:
- "127.0.0.1:5900:5900" # VNC — bind to localhost only!
volumes:
- ./sessions:/sessions
- /dev/shm:/dev/shm # shared memory for Firefox
shm_size: "2gb"
api:
build:
context: ./api
container_name: threads-api
restart: unless-stopped
environment:
SESSION_DIR: /sessions
ports:
- "127.0.0.1:8000:8000" # bind to localhost only — Nginx handles external
volumes:
- ./sessions:/sessions
depends_on:
- browser
dashboard:
build:
context: ./dashboard
container_name: threads-dashboard
restart: unless-stopped
environment:
NEXT_PUBLIC_API_URL: http://localhost:8000
ports:
- "127.0.0.1:3000:3000"
nginx:
image: nginx:1.28.2-alpine3.23 # pin stable — never use bare :alpine/:latest
container_name: threads-nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/ssl:ro
Security Rules (2026)
# ✅ Never expose internal services directly to internet
ports:
- "127.0.0.1:8000:8000" # only localhost — Nginx proxies externally
# ❌ Never do this
ports:
- "8000:8000" # exposes to all interfaces
[!CAUTION] The commands below modify host-level firewall rules and require root privileges. Never run them unattended in CI or automated scripts. Review and execute manually on the target VPS only.
# UFW rules on VPS (manual — requires human review)
sudo ufw default deny incoming
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP
sudo ufw allow 443/tcp # HTTPS
sudo ufw deny 5900 # Block VNC from outside after first use
sudo ufw enable
Volume Strategy
volumes:
- ./sessions:/sessions # named bind mount — survives container rebuild
- /dev/shm:/dev/shm # shared memory — required for Firefox stability
# Never lose sessions: backup before any docker operations
tar -czf sessions-backup-$(date +%Y%m%d).tar.gz ./sessions/
Useful Commands (2026)
# Build and start all services
docker compose up -d --build
# Tail logs for a specific service
docker compose logs -f browser
# Shell into running container
docker exec -it threads-browser bash
# Check resource usage
docker stats
# Restart single service without rebuilding
docker compose restart api
# Full teardown (preserves volumes)
docker compose down
# Full teardown including volumes — DANGER, deletes sessions
docker compose down -v
Health Checks
services:
api:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
.dockerignore
.venv/
__pycache__/
*.pyc
.env
.git/
node_modules/
sessions/
*.log
Anti-Patterns
# ❌ Never run as root in production
CMD ["python", "app.py"] # without USER directive — runs as root
# ❌ Never use latest tag for base images in production
FROM python:latest
# ❌ Never install pip packages globally in 2026 Dockerfiles
RUN pip install fastapi # use uv instead
# ❌ Never copy all files before installing deps (kills layer cache)
COPY . .
RUN uv sync # every code change invalidates dep cache
References
