⚠️ NO OFFICIAL DOCKER IMAGE
There is no official uWSGI Docker image. Community images are available but have limitations.
⚠️ TIANGILO/UWSGI-NGINX DEPRECATED
The popular
tiangolo/uwsgi-nginximage is DEPRECATED. The maintainer recommends using Gunicorn for new projects.
⚠️ PROJECT STATUS: MAINTENANCE MODE
uWSGI is in maintenance mode (announced 2024). For new projects, consider Gunicorn, Uvicorn, or Granian.
uWSGI is an application server (not a web server) that runs Python web applications. It is typically deployed behind a reverse proxy like Nginx.
| Image | Status | Maintainer | Recommendation |
|---|---|---|---|
| Official | ❌ None | - | Does not exist |
| tiangolo/uwsgi-nginx | ⚠️ DEPRECATED | tiangolo | Not recommended for new projects |
| kojiromike/uwsgi | ⚠️ Community | kojiromike | Use with caution |
| Custom build | ✅ Recommended | Self | Best for production |
FROM python:3.12-slim
LABEL maintainer="Your Name <your@email.com>"
LABEL description="Custom uWSGI image for Python applications"
# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential \
&& rm -rf /var/lib/apt/lists/*
# Create app user
RUN useradd --create-home --shell /bin/bash app
# Set working directory
WORKDIR /app
# Install uWSGI
RUN pip install --no-cache-dir uwsgi
# Copy application
COPY --chown=app:app . .
# Install application dependencies
RUN pip install --no-cache-dir -r requirements.txt
# Switch to non-root user
USER app
# Expose uWSGI socket port
EXPOSE 8000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD python -c "import socket; s = socket.socket(); s.connect(('localhost', 8000)); s.close()" || exit 1
# Start uWSGI
CMD ["uwsgi", "--ini", "uwsgi.ini"]
# uwsgi.ini
[uwsgi]
module = app:app
master = true
processes = 4
threads = 2
http = :8000
vacuum = true
die-on-term = true
logto = /var/log/uwsgi/app.log
# docker-compose.yml
services:
uwsgi:
build: .
container_name: myapp-uwsgi
ports:
- "8000:8000"
volumes:
- ./app:/app
- ./logs:/var/log/uwsgi
environment:
- PYTHONUNBUFFERED=1
restart: unless-stopped
healthcheck:
test: ["CMD", "python", "-c", "import socket; s = socket.socket(); s.connect(('localhost', 8000)); s.close()"]
interval: 30s
timeout: 10s
retries: 3
nginx:
image: nginx:alpine
container_name: myapp-nginx
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
- uwsgi
restart: unless-stopped
# nginx.conf
server {
listen 80;
server_name localhost;
location / {
proxy_pass http://uwsgi:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# Build the image
docker compose build
# Start services
docker compose up -d
# Check status
docker compose ps
# View logs
docker compose logs -f uwsgi
⚠️ WARNING: DEPRECATED IMAGE
This image is deprecated by its maintainer. The maintainer recommends building Docker images from scratch or using Gunicorn instead. Use only for legacy deployments.
# Dockerfile
FROM tiangolo/uwsgi-nginx:python3.12
# Install dependencies
COPY ./requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
# Copy application
COPY ./app /app
| Variable | Default | Description |
|---|---|---|
UWSGI_CHEAPER |
2 | Starting number of processes |
UWSGI_PROCESSES |
16 | Maximum number of processes |
NGINX_MAX_UPLOAD |
unlimited | Max upload size |
LISTEN_PORT |
80 | Container listen port |
NGINX_WORKER_PROCESSES |
1 | Number of Nginx workers |
docker build -t myapp:latest .
docker run -d -p 80:80 myapp:latest
services:
uwsgi:
image: kojiromike/uwsgi:latest
volumes:
- ./app:/app
- ./uwsgi.ini:/etc/uwsgi/uwsgi.ini
ports:
- "8000:8000"
⚠️ Note: Community images may not be regularly updated. Verify image security before production use.
docker compose logs -f uwsgi
docker compose restart uwsgi
# Access shell
docker compose exec uwsgi /bin/bash
# Check uWSGI stats
docker compose exec uwsgi uwsgi --connect-and-read :8000
# In docker-compose.yml
services:
uwsgi:
environment:
- UWSGI_PROCESSES=8
⚠️ Maintenance Mode Warning
Security patches may be slower due to maintenance mode status.
Run as Non-Root User
USER app
Use Multi-Stage Builds
FROM python:3.12-slim as builder
# Build steps...
FROM python:3.12-slim
COPY --from=builder /app /app
Scan for Vulnerabilities
docker scout cve myapp:latest
Use Read-Only Root Filesystem
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
Network Isolation
networks:
- internal
See uWSGI Security and uWSGI Hardening for additional guidance.
| Issue | Solution |
|---|---|
| Container exits immediately | Check uWSGI logs: docker compose logs uwsgi |
| Cannot connect to socket | Verify socket binding in uwsgi.ini |
| Permission denied | Ensure correct user ownership |
| High memory usage | Adjust UWSGI_CHEAPER and UWSGI_PROCESSES |
For new projects, consider Gunicorn instead:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir gunicorn
COPY . .
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app:app"]
See Gunicorn documentation for details.
Running containers in production? We help with:
Need help? office@linux-server-admin.com or Contact Us