Tech With Galvan
Back to Articles
DevelopmentOct 25, 2026 • 5 min read

Deploy Streamlit with Docker (Production-Ready)

Containerize and deploy a Streamlit app with Docker — Dockerfile, docker-compose, nginx reverse proxy, and production best practices.

Galvan
Galvan

Founder & Creator

Introduction

Streamlit Community Cloud is great for prototypes, but for production you often need Docker: custom dependencies, private networks, persistent storage, and control over scaling. This post containerizes a Streamlit app and deploys it production-ready.

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install dependencies first (cache layer)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy app code
COPY . .

# Expose Streamlit port
EXPOSE 8501

# Health check
HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health || exit 1

# Run
CMD ["streamlit", "run", "app.py", \
     "--server.port=8501", \
     "--server.address=0.0.0.0", \
     "--server.headless=true", \
     "--server.fileWatcherType=none"]

Key points:

  • python:3.11-slim = small image (~150MB).
  • Install deps before copying code = better Docker cache.
  • fileWatcherType=none = disables hot-reload in production (saves CPU).
  • Health check uses Streamlit’s /_stcore/health endpoint.

Build and run

docker build -t my-streamlit-app .
docker run -p 8501:8501 my-streamlit-app

Visit http://localhost:8501.

docker-compose.yml (with Redis + Postgres)

version: "3.8"
services:
  app:
    build: .
    ports:
      - "8501:8501"
    environment:
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    depends_on:
      - redis
      - db
    restart: unless-stopped

  redis:
    image: redis:alpine
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - app
    restart: unless-stopped

volumes:
  pgdata:

Run everything:

docker compose up -d

nginx reverse proxy (with SSL)

# nginx.conf
events {}
http {
    upstream streamlit {
        server app:8501;
    }
    server {
        listen 80;
        server_name yourdomain.com;
        return 301 https://$host$request_uri;
    }
    server {
        listen 443 ssl;
        server_name yourdomain.com;
        ssl_certificate /etc/nginx/certs/cert.pem;
        ssl_certificate_key /etc/nginx/certs/key.pem;

        location / {
            proxy_pass http://streamlit;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_read_timeout 86400;
        }
    }
}

The Upgrade and Connection headers are critical for Streamlit’s WebSocket (used for real-time updates).

Production best practices

  1. Use .dockerignore:
    .git
    __pycache__
    *.pyc
    .env
    .streamlit/secrets.toml
    venv/
  2. Don’t bake secrets into the image — pass via env vars or mount secrets.
  3. Use multi-stage builds for smaller images:
    FROM python:3.11-slim AS builder
    RUN pip install --user -r requirements.txt
    FROM python:3.11-slim
    COPY --from=builder /root/.local /root/.local
    COPY . .
    CMD ["streamlit", "run", "app.py"]
  4. Pin dependency versions in requirements.txt (streamlit==1.40.0).
  5. Set resource limits in compose: deploy.resources.limits.memory: 1G.
  6. Use health checks and restart policies.
  7. Log to stdout — Docker captures stdout/stderr; use logging to stdout.

Scaling

Streamlit is single-threaded per session. To handle more users:

  • Vertical: bigger machine (more RAM/CPU).
  • Horizontal: run N instances behind a load balancer with sticky sessions (session affinity) — Streamlit sessions are stateful, so the same user must hit the same instance.
  • Redis for shared state (see Redis post) — share cache/sessions across instances.

Cloud deployment options

Platform Effort Cost Best for
Streamlit Community Cloud Zero Free Prototypes, demos
Render / Railway Low $5-20/mo Small apps
Fly.io Medium Pay-per-use Global, low latency
AWS/GCP/Azure High Variable Enterprise
Self-hosted Docker Medium Server cost Full control

Common mistakes

  • Forgetting WebSocket headers in nginx — real-time updates break without Upgrade/Connection.
  • Baking secrets into the image — use env vars; never commit .env.
  • No health check — orchestrators can’t tell if the app is alive.
  • fileWatcherType not disabled — wastes CPU in production.
  • Not pinning versions — pip install streamlit can break on upgrades.

Key Concepts

  • Dockerfile = recipe for the container image
  • docker-compose = multi-service orchestration
  • Reverse proxy = nginx in front of Streamlit (SSL, routing)
  • WebSocket = required for Streamlit’s real-time updates
  • Sticky sessions = same user → same instance (stateful)

What to Try Next

  • Deploy your admin panel with Docker.
  • Add Redis for shared state across instances.
  • Set up CI/CD with GitHub Actions (build + push + deploy).
  • Combine with FastAPI in one compose file.

FAQ

Docker vs Streamlit Community Cloud?

Community Cloud = zero setup, free, limited (no custom deps, no private networks). Docker = full control, any deps, private networks, scaling. Start with Community Cloud; move to Docker when you hit limits.

Can I deploy to Kubernetes?

Yes — Streamlit works in K8s. Use a Deployment with multiple replicas and a Service with session affinity (sessionAffinity: ClientIP). Add a HorizontalPodAutoscaler for auto-scaling.

How do I handle secrets in Docker?

Use Docker secrets (Swarm) or mount env files: docker run --env-file .env. Never bake secrets into the image. In compose, use environment: or env_file:.