FaridLU/deploy-django-production-ubuntu.md

## deploy-django-production-ubuntu.md

      
    Raw
  

              deploy-django-production-ubuntu.md
            
          
    🚀 Deploy Django on Ubuntu with Gunicorn, Nginx, Celery & SSL


The Complete Production Deployment Guide for Django Applications


📖 Overview

This comprehensive guide walks you through deploying a production-ready Django application on Ubuntu. You'll learn to configure Gunicorn as the application server, Nginx as a reverse proxy, Celery for background tasks, Redis as a message broker, PostgreSQL as the database, and secure everything with a free SSL certificate from Let's Encrypt.
🏗️ What You'll Build

                    ┌───────────────────────────┐
                    │      INTERNET (WWW)       │
                    └─────────────┬─────────────┘
                                  │ HTTPS (443)
                                  ▼
                    ┌───────────────────────────┐
                    │    NGINX (Reverse Proxy)  │
                    │  SSL + Static Files       │
                    └─────────────┬─────────────┘
                                  │ Unix Socket
                                  ▼
                    ┌───────────────────────────┐
                    │  GUNICORN (WSGI Server)   │
                    │    Django Application     │
                    └──────┬─────────────┬──────┘
                           │             │
              ┌────────────┘             └────────────┐
              ▼                                       ▼
┌───────────────────────────┐         ┌───────────────────────────┐
│        POSTGRESQL         │         │      CELERY + REDIS       │
│         Database          │         │     Background Tasks      │
└───────────────────────────┘         └───────────────────────────┘


📑 Table of Contents


📋 Prerequisites
🖥️ Part 1: Initial Server Setup
🔑 Part 2: SSH Keys & Environment Configuration
⚡ Part 3: Gunicorn & Nginx Setup
📦 Part 4: Celery, Redis & Supervisor
🌐 Part 5: Domain & SSL Certificate
🔧 Troubleshooting
📚 Quick Reference


📋 Prerequisites

Before starting, ensure you have:

 🖥️ A Ubuntu server (18.04, 20.04, 22.04, or 24.04 LTS)
 🔐 Root or sudo access to the server
 🐍 A Django project ready for deployment
 💻 Basic familiarity with Linux command line
 🌐 A domain name (for SSL setup - optional for initial deployment)


⏱️ Estimated Time: 45-60 minutes for complete setup


🖥️ Part 1: Initial Server Setup

1.1 Create Your Server

Create a new Ubuntu server on your preferred cloud provider:

☁️ DigitalOcean
☁️ AWS EC2
☁️ Linode
☁️ Vultr

Choose a location closest to your target users for optimal latency.
1.2 Connect to Your Server

ssh root@your-server-ip-address
1.3 Create a Non-Root User


🛡️ Security Best Practice: Never run applications as root. Create a dedicated user for deployment.

# Create new user
adduser ubuntu

# Grant sudo privileges
usermod -aG sudo ubuntu
1.4 Configure Firewall

# Allow SSH connections
ufw allow OpenSSH

# Enable firewall
ufw enable

# Verify status
ufw status
1.5 Switch to New User

# From now on, connect as the new user
ssh ubuntu@your-server-ip-address

# Run commands with sudo when needed
sudo your-command
✅ Checkpoint: You should now be able to SSH into your server as the new user.

🔑 Part 2: SSH Keys & Environment Configuration

2.1 Generate SSH Key for Git

# Generate SSH key
ssh-keygen -t ed25519 -C "your-email@example.com"

# Display public key (copy this)
cat ~/.ssh/id_ed25519.pub

💡 Note: If your system doesn't support Ed25519, use RSA instead:
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

2.2 Add SSH Key to GitHub/GitLab


📋 Copy the public key from the terminal
🔗 Navigate to your Git provider's SSH settings:

GitHub: github.com/settings/keys
GitLab: gitlab.com/-/profile/keys


➕ Click "New SSH Key" and paste your key

2.3 Clone Your Project

# Clone repository
git clone git@github.com:username/your-project.git

# Navigate to project directory
cd your-project
2.4 Install System Dependencies

# Update package list
sudo apt update

# Install required packages
sudo apt install -y \
    python3-venv \
    python3-dev \
    libpq-dev \
    postgresql \
    postgresql-contrib \
    nginx \
    curl \
    build-essential \
    libssl-dev \
    libffi-dev
2.5 Set Up Python Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install Gunicorn and PostgreSQL adapter
pip install gunicorn psycopg2-binary wheel

# Install project dependencies
pip install -r requirements.txt
2.6 Configure PostgreSQL Database 🐘

# Access PostgreSQL
sudo -u postgres psql
Run the following SQL commands:
-- Create database
CREATE DATABASE your_db_name;

-- Create user with secure password
CREATE USER your_db_user WITH PASSWORD 'your_secure_password';

-- Configure user settings
ALTER ROLE your_db_user SET client_encoding TO 'utf8';
ALTER ROLE your_db_user SET default_transaction_isolation TO 'read committed';
ALTER ROLE your_db_user SET timezone TO 'UTC';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE your_db_name TO your_db_user;

-- Exit PostgreSQL
\q
2.7 Configure Django Settings

Update your settings.py (or use environment variables):
# Database configuration
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_db_name',
        'USER': 'your_db_user',
        'PASSWORD': 'your_secure_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

# Allowed hosts
ALLOWED_HOSTS = ['your-server-ip', 'yourdomain.com', 'www.yourdomain.com']

# Static files
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'static'

# Media files
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

🔐 Security Tip: Use environment variables for sensitive data:
import os
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')

2.8 Initialize Django Application

# Apply migrations
python manage.py migrate

# Collect static files
python manage.py collectstatic --noinput

# Create superuser (optional)
python manage.py createsuperuser
2.9 Test Development Server

# Allow port 8000 temporarily
sudo ufw allow 8000

# Run development server
python manage.py runserver 0.0.0.0:8000
🌐 Visit http://your-server-ip:8000 to verify the application works.
2.10 Test Gunicorn

# Test Gunicorn (replace 'yourproject' with your project name)
gunicorn --bind 0.0.0.0:8000 yourproject.wsgi:application
Press Ctrl+C to stop, then deactivate the virtual environment:
deactivate
✅ Checkpoint: Django app runs successfully with Gunicorn.

⚡ Part 3: Gunicorn & Nginx Setup

3.1 Create Gunicorn Socket File

sudo nano /etc/systemd/system/gunicorn.socket
Add the following content:
[Unit]
Description=Gunicorn socket for Django

[Socket]
ListenStream=/run/gunicorn.sock

[Install]
WantedBy=sockets.target
3.2 Create Gunicorn Service File

sudo nano /etc/systemd/system/gunicorn.service
Add the following content (update paths as needed):
[Unit]
Description=Gunicorn daemon for Django
Requires=gunicorn.socket
After=network.target

[Service]
User=ubuntu
Group=www-data
WorkingDirectory=/home/ubuntu/your-project
ExecStart=/home/ubuntu/your-project/venv/bin/gunicorn \
          --access-logfile - \
          --error-logfile - \
          --workers 3 \
          --bind unix:/run/gunicorn.sock \
          yourproject.wsgi:application

[Install]
WantedBy=multi-user.target

💡 Performance Tip: Set workers to (2 × CPU cores) + 1 for optimal performance.

3.3 Start and Enable Gunicorn

# Start Gunicorn socket
sudo systemctl start gunicorn.socket
sudo systemctl enable gunicorn.socket

# Verify socket is running
sudo systemctl status gunicorn.socket

# Check socket file exists
file /run/gunicorn.sock
3.4 Configure Nginx 🔧

Create a new Nginx configuration:
sudo nano /etc/nginx/sites-available/yourproject
Add the following configuration:
server {
    listen 80;
    server_name your-server-ip yourdomain.com www.yourdomain.com;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Favicon
    location = /favicon.ico {
        access_log off;
        log_not_found off;
    }

    # Static files
    location /static/ {
        alias /home/ubuntu/your-project/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Media files
    location /media/ {
        alias /home/ubuntu/your-project/media/;
        expires 7d;
    }

    # Proxy to Gunicorn
    location / {
        include proxy_params;
        proxy_pass http://unix:/run/gunicorn.sock;
        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }

    # Max upload size
    client_max_body_size 10M;
}
3.5 Enable the Site

# Create symbolic link
sudo ln -s /etc/nginx/sites-available/yourproject /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx
3.6 Update Firewall Rules

# Remove temporary port 8000 rule
sudo ufw delete allow 8000

# Allow Nginx
sudo ufw allow 'Nginx Full'
3.7 Verify Deployment

🎉 Visit http://your-server-ip in your browser. Your Django application should be running!
✅ Checkpoint: Django app is accessible via Nginx.

📦 Part 4: Celery, Redis & Supervisor


⏭️ Skip this section if your application doesn't use background tasks.

4.1 Install Redis and Supervisor

# Install Redis
sudo apt install -y redis-server

# Install Supervisor
sudo apt install -y supervisor

# Verify Redis is running
sudo systemctl status redis
4.2 Create Celery Worker Configuration 🥬

sudo nano /etc/supervisor/conf.d/celery_worker.conf
Add the following content:
[program:celeryworker]
command=/home/ubuntu/your-project/venv/bin/celery -A yourproject worker --loglevel=INFO
directory=/home/ubuntu/your-project
user=ubuntu
numprocs=1
stdout_logfile=/var/log/celery/worker.log
stderr_logfile=/var/log/celery/worker.log
autostart=true
autorestart=true
startsecs=10
stopwaitsecs=600
killasgroup=true
priority=998
4.3 Create Celery Beat Configuration (Optional) ⏰

For scheduled tasks:
sudo nano /etc/supervisor/conf.d/celery_beat.conf
Add the following content:
[program:celerybeat]
command=/home/ubuntu/your-project/venv/bin/celery -A yourproject beat --loglevel=INFO
directory=/home/ubuntu/your-project
user=ubuntu
numprocs=1
stdout_logfile=/var/log/celery/beat.log
stderr_logfile=/var/log/celery/beat.log
autostart=true
autorestart=true
startsecs=10
priority=999
4.4 Create Log Directory and Start Services

# Create log directory
sudo mkdir -p /var/log/celery
sudo chown ubuntu:ubuntu /var/log/celery

# Update Supervisor
sudo supervisorctl reread
sudo supervisorctl update

# Start services
sudo supervisorctl start all

# Check status
sudo supervisorctl status
4.5 Useful Supervisor Commands 📝

# Restart all services
sudo supervisorctl restart all

# View worker logs
sudo tail -f /var/log/celery/worker.log

# View beat logs
sudo tail -f /var/log/celery/beat.log
✅ Checkpoint: Celery workers are running in the background.

🌐 Part 5: Domain & SSL Certificate

5.1 Point Domain to Server 🔗

Configure your domain's DNS settings:

A Record: @ → your-server-ip
A Record: www → your-server-ip


⏳ Note: DNS propagation can take up to 48 hours, but usually completes within minutes.

5.2 Update Nginx Configuration

sudo nano /etc/nginx/sites-available/yourproject
Update the server_name directive:
server_name yourdomain.com www.yourdomain.com;
5.3 Update Django Settings

ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']
5.4 Reload Nginx

sudo nginx -t
sudo systemctl reload nginx
5.5 Install Certbot 🔒

# Install Certbot
sudo snap install --classic certbot

# Create symbolic link
sudo ln -s /snap/bin/certbot /usr/bin/certbot
5.6 Obtain SSL Certificate

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
Follow the prompts:

📧 Enter your email address
✅ Agree to terms of service (Y)
📰 Choose whether to share email with EFF

5.7 Verify Auto-Renewal

# Test renewal process
sudo certbot renew --dry-run

# Check renewal timer
sudo systemctl status snap.certbot.renew.timer
🎉 Your site is now accessible via https://yourdomain.com!
✅ Checkpoint: SSL certificate installed and auto-renewal configured.

🔧 Troubleshooting

Common Issues and Solutions


❌ 502 Bad Gateway


Check if Gunicorn is running:
sudo systemctl status gunicorn


Check Gunicorn logs:
sudo journalctl -u gunicorn


Verify socket file exists:
file /run/gunicorn.sock


Restart services:
sudo systemctl daemon-reload
sudo systemctl restart gunicorn
sudo systemctl restart nginx


🖼️ Static Files Not Loading

Verify STATIC_ROOT in settings.py
Run python manage.py collectstatic
Check Nginx configuration paths
Verify file permissions:
sudo chown -R ubuntu:www-data /home/ubuntu/your-project/static


🚫 Permission Denied Errors


Check file ownership:
ls -la /home/ubuntu/your-project


Fix permissions:
sudo chown -R ubuntu:www-data /home/ubuntu/your-project
sudo chmod -R 755 /home/ubuntu/your-project


🐘 Database Connection Failed


Verify PostgreSQL is running:
sudo systemctl status postgresql


Test database connection:
sudo -u postgres psql -c "\l"


Check credentials in settings.py


🥬 Celery Tasks Not Running


Check Supervisor status:
sudo supervisorctl status


View Celery logs:
sudo tail -f /var/log/celery/worker.log


Restart Celery:
sudo supervisorctl restart celeryworker


📚 Quick Reference

🔄 Service Management


Action
Command


🔄 Restart Gunicorn
sudo systemctl restart gunicorn


🔄 Restart Nginx
sudo systemctl restart nginx


🔄 Restart Celery
sudo supervisorctl restart all


📋 View Gunicorn logs
sudo journalctl -u gunicorn -f


📋 View Nginx error log
sudo tail -f /var/log/nginx/error.log


📋 View Celery logs
sudo tail -f /var/log/celery/worker.log


✅ Deployment Checklist


 🖥️ Server created and SSH access configured
 👤 Non-root user created with sudo privileges
 🔥 Firewall configured (UFW)
 🔑 Git SSH key added to repository
 📦 Project cloned and dependencies installed
 🐘 PostgreSQL database configured
 ⚙️ Django settings updated for production
 📁 Static files collected
 🦄 Gunicorn socket and service configured
 🔀 Nginx configured as reverse proxy
 🥬 Celery and Supervisor configured (if needed)
 🌐 Domain pointed to server
 🔒 SSL certificate installed
 🔄 Auto-renewal verified

🚀 Update Deployment

When you push new code:
cd ~/your-project
git pull origin main
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput
sudo systemctl restart gunicorn
sudo supervisorctl restart all  # If using Celery
deactivate

🤝 Contributing

Found an issue or have a suggestion? Open an issue or submit a pull request.

📄 License

This guide is released under the MIT License.


  ⭐ If this guide helped you, please give it a star! ⭐


  Made with ❤️ for the Django community
Action	Command
🔄 Restart Gunicorn	`sudo systemctl restart gunicorn`
🔄 Restart Nginx	`sudo systemctl restart nginx`
🔄 Restart Celery	`sudo supervisorctl restart all`
📋 View Gunicorn logs	`sudo journalctl -u gunicorn -f`
📋 View Nginx error log	`sudo tail -f /var/log/nginx/error.log`
📋 View Celery logs	`sudo tail -f /var/log/celery/worker.log`
No results found