Step-by-Step Guide to Deploying a Django Project on a Server
python manage.py runserver is fine on a laptop. Django's own documentation says plainly that it is not meant for production: it hasn't been through security audits or performance testing. The usual production setup on a Linux server has three parts. Gunicorn runs your Django code in several worker processes. Nginx sits in front of it, serves static files, handles HTTPS and passes everything else to Gunicorn. And systemd keeps Gunicorn running and restarts it after a crash or a reboot. Pythous itself runs on Django behind Gunicorn. This guide uses Ubuntu or Debian; the paths and package names differ slightly on other distributions.

Illustration: from your laptop to a production server.
1. Get the settings ready
Four settings matter before anything else. DEBUG must be False: with it on, any error shows a full traceback, including settings and local variables, to whoever caused it. ALLOWED_HOSTS must list your domain, for example ['example.com', 'www.example.com']; with debug off, Django rejects requests for any other host name. SECRET_KEY, which signs sessions and password-reset links, should come from an environment variable, not from a file in your repository. And STATIC_ROOT should point to the folder Nginx will serve static files from.
Django can check most of this for you. Run this with your production settings:
python manage.py check --deploy
It warns about debug mode, missing security headers, cookies that aren't marked secure, and similar problems. Some warnings, such as HSTS, you may decide to switch on only after HTTPS is working.
2. Install the software and the project
sudo apt update && sudo apt upgrade -y sudo apt install python3-venv python3-pip nginx -y
Put the project somewhere like /srv/myproject, create a virtual environment inside it so its packages don't mix with the system's, and install your requirements plus Gunicorn:
cd /srv/myproject python3 -m venv venv source venv/bin/activate pip install -r requirements.txt gunicorn python manage.py migrate python manage.py collectstatic
Before configuring anything else, check that Gunicorn can serve the site on its own:
gunicorn --bind 0.0.0.0:8000 myproject.wsgi
If the pages load on port 8000 (without styling, since nothing serves static files yet), the Django side works, and any later problem is in the Nginx or systemd configuration. Stop it with Ctrl+C.
3. Run Gunicorn under systemd
A Gunicorn started by hand dies when you close the terminal. A systemd service runs it in the background, restarts it if it crashes, and starts it at boot. Create /etc/systemd/system/gunicorn.service:
[Unit] Description=Gunicorn for myproject After=network.target [Service] User=deploy Group=www-data WorkingDirectory=/srv/myproject EnvironmentFile=/srv/myproject/.env ExecStart=/srv/myproject/venv/bin/gunicorn --workers 3 --bind unix:/run/gunicorn/myproject.sock myproject.wsgi:application RuntimeDirectory=gunicorn Restart=on-failure [Install] WantedBy=multi-user.target
Gunicorn listens on a Unix socket in /run/gunicorn, which systemd creates because of the RuntimeDirectory line. The group is www-data so that Nginx, which runs as that user on Ubuntu, can reach the socket. The .env file holds the secret key and database password; keep it readable only by the deploy user. Gunicorn's documentation suggests starting with (2 × number of CPU cores) + 1 workers and adjusting from there; three suits a small one- or two-core server.
sudo systemctl daemon-reload sudo systemctl enable --now gunicorn sudo systemctl status gunicorn
enable is the part people forget. Without it the service runs today but doesn't come back after the next reboot.
4. Put Nginx in front
Create /etc/nginx/sites-available/myproject:
server {
listen 80;
server_name example.com www.example.com;
location /static/ {
alias /srv/myproject/staticfiles/;
}
location / {
include proxy_params;
proxy_pass http://unix:/run/gunicorn/myproject.sock;
}
}The /static/ block makes Nginx send CSS, JavaScript and images straight from disk, without involving Django; the path must match your STATIC_ROOT. Everything else goes to Gunicorn. Nginx also buffers slow clients, so a visitor on a poor mobile connection doesn't tie up one of your few Gunicorn workers for the whole download. Enable the site and test the configuration before reloading:
sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx
nginx -t catches syntax errors. Reloading with a broken file can take down every site on the server, not just the new one.
5. Add HTTPS
sudo apt install certbot python3-certbot-nginx -y sudo certbot --nginx -d example.com -d www.example.com
Certbot gets a free certificate from Let's Encrypt and edits the Nginx file to use it, including a redirect from HTTP. Let's Encrypt certificates last 90 days. The Ubuntu package installs a systemd timer that renews them automatically, so there's no need to add a cron job; sudo certbot renew --dry-run confirms renewal works. Once HTTPS is in place, set SECURE_SSL_REDIRECT, SESSION_COOKIE_SECURE and CSRF_COOKIE_SECURE to True and run check --deploy again.
6. When something goes wrong
The two logs tell you which half failed. A "502 Bad Gateway" page comes from Nginx and means it couldn't reach Gunicorn: look at sudo journalctl -u gunicorn for a crash on start-up, a wrong path, or a permission problem on the socket. Nginx's own errors are in /var/log/nginx/error.log. A page with no styling almost always means a missed collectstatic or a /static/ path that doesn't match STATIC_ROOT.
One habit is worth building early. When you deploy new code, Gunicorn keeps serving the old version from memory until it restarts. Management commands run the new code straight away, so it's easy to be confused when a fix appears to work from the command line but not on the site. Make sudo systemctl restart gunicorn the last step of every deployment.
Sources
- Django documentation, "Deployment checklist". https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/
- Django documentation, "How to deploy static files". https://docs.djangoproject.com/en/5.2/howto/static-files/deployment/
- Gunicorn documentation, "Deploy" and "Design" (worker count). https://gunicorn.org/deploy/
- Nginx documentation, "Module ngx_http_proxy_module". https://nginx.org/en/docs/http/ngx_http_proxy_module.html
- systemd manual, "systemd.service". https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
- Electronic Frontier Foundation, "Certbot instructions"; Let's Encrypt, "FAQ" (certificate lifetime). https://certbot.eff.org/instructions
Comments (0)
Leave a Reply
Comments are moderated. Please read our Comment Policy before posting.
Log in to post a comment.