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/healthendpoint.
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
- Use
.dockerignore:.git __pycache__ *.pyc .env .streamlit/secrets.toml venv/ - Don’t bake secrets into the image — pass via env vars or mount secrets.
- 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"] - Pin dependency versions in
requirements.txt(streamlit==1.40.0). - Set resource limits in compose:
deploy.resources.limits.memory: 1G. - Use health checks and restart policies.
- Log to stdout — Docker captures stdout/stderr; use
loggingto 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.
fileWatcherTypenot disabled — wastes CPU in production.- Not pinning versions —
pip install streamlitcan 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:.