How to Deploy a Django App with Claude Code on Linux

If you want a step-by-step guide to deploy a Django app with Claude Code on Linux, the good news is that the workflow is much closer to a real ops setup than a toy deployment. You can let the agent help with the boring parts—packages, services, config files, and repeatable commands—while you keep control of the architecture and the final checks.

This guide assumes you already have a Django project and want to run it on a Linux server with Gunicorn and Nginx. I’ll walk through the deployment path I’d recommend for a small production site, plus the places where people usually get stuck: environment variables, database migrations, static assets, permissions, and service startup.

What you need before you deploy

Before touching the server, make sure your Django project is ready for production. Claude Code can help audit this, but you still want to verify the basics yourself.

• Django project runs locally without errors.
• Dependencies are pinned in requirements.txt or a lockfile.
• Production settings are separate from development settings.
• Secret values are not hardcoded in the repo.
• Database migrations are clean on your current branch.
• Static files are collected correctly with collectstatic.

If you’re using Vibesies or another hosted Linux environment, the same rules apply: the agent can make changes in the container, but your app still needs the usual production hygiene.

How to deploy a Django app with Claude Code on Linux

The deployment process is straightforward once you break it into phases. Ask Claude Code to handle one phase at a time instead of saying “deploy my app” and hoping for the best.

1) Set up the server

Start by installing the system packages Django typically needs. On Ubuntu or Debian, that usually means Python tooling, a virtual environment package, and a web server.

sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx git

If your app needs PostgreSQL or Redis, install those too. For a production deployment, it’s usually best to use the system package manager rather than mixing everything into Python packages.

2) Create a dedicated app user and directory

Use a non-root user for the app. Claude Code can create the directory structure and permissions for you.

sudo adduser --disabled-password --gecos "" djangoapp
sudo mkdir -p /var/www/myproject
sudo chown -R djangoapp:djangoapp /var/www/myproject

This matters because service files, static asset ownership, and process isolation all become easier when the app has a predictable home.

3) Clone the repo and create a virtual environment

From the app directory, clone your repository and install dependencies into a virtual environment.

git clone https://github.com/yourname/yourrepo.git /var/www/myproject
cd /var/www/myproject
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

If Claude Code is managing the server, have it confirm the exact Python version your project expects. A mismatch here causes a lot of avoidable breakage.

4) Configure environment variables

Django production settings usually depend on values like SECRET_KEY, DEBUG, ALLOWED_HOSTS, database credentials, and third-party API keys. Keep them out of Git.

A simple pattern is to store them in an .env file or, better, set them in a service file or secret manager. For a small deployment, a root-owned env file can work if permissions are tight.

DEBUG=False
SECRET_KEY=your-secret-key
ALLOWED_HOSTS=example.com,www.example.com
DATABASE_URL=postgres://user:password@localhost:5432/dbname

If you’re using Claude Code, have it inspect your settings module and list every required environment variable before you restart the app. That one step prevents a lot of “works locally, fails on server” frustration.

5) Run migrations and collect static files

Once dependencies and environment values are in place, run your database migrations and static asset build steps.

source .venv/bin/activate
python manage.py migrate
python manage.py collectstatic --noinput

If the project uses custom storage, WhiteNoise, S3, or a CDN, confirm that static files are accessible before moving on to Nginx. A production site with broken CSS often looks like the deployment failed, even when the backend is fine.

6) Start Gunicorn

Gunicorn is a common application server for Django. The goal is to run your project as a service, not as a shell process you manually restart.

gunicorn myproject.wsgi:application --bind 127.0.0.1:8000

That command should work before you create the systemd unit. If it doesn’t, fix the import path, virtualenv, or settings issue first.

7) Create a systemd service

A systemd service keeps Django running after you log out and restarts it on boot. This is one of the most important parts of a real Linux deployment.

[Unit]
Description=Gunicorn for myproject
After=network.target

[Service]
User=djangoapp
Group=www-data
WorkingDirectory=/var/www/myproject
Environment="PATH=/var/www/myproject/.venv/bin"
ExecStart=/var/www/myproject/.venv/bin/gunicorn myproject.wsgi:application --bind 127.0.0.1:8000
Restart=always

[Install]
WantedBy=multi-user.target

Then reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now gunicorn
sudo systemctl status gunicorn

If the service fails, check the journal before guessing:

journalctl -u gunicorn -n 50 --no-pager

8) Put Nginx in front of Gunicorn

Nginx handles the public-facing HTTP traffic, TLS, and static files. Gunicorn stays behind it.

server {
    server_name example.com www.example.com;

    location /static/ {
        alias /var/www/myproject/static/;
    }

    location /media/ {
        alias /var/www/myproject/media/;
    }

    location / {
        proxy_pass http://127.0.0.1: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;
    }
}

Enable the site, test the config, and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

If you’re adding HTTPS, use Let’s Encrypt and confirm that Django trusts the proxy headers correctly.

Common mistakes when deploying Django on Linux

Most deployment problems are not exotic. They’re usually one of a handful of repeat offenders.

• Forgetting to set ALLOWED_HOSTS, which causes a 400 error.
• Leaving DEBUG=True in production.
• Using the wrong Python executable in the service file.
• Not collecting static files or pointing Nginx at the wrong directory.
• Missing database credentials in the environment.
• Permission mismatches on the project directory, static folder, or log files.
• Proxy header issues that break HTTPS redirects or admin logins.

A good habit is to ask Claude Code to generate a deployment checklist from your repository. Then you can compare that checklist against the live server and mark each item complete one by one.

A practical pre-launch checklist

Before you call the site live, run through this short checklist.

• Can you open the site in a browser without a traceback?
• Does the homepage load with styling intact?
• Do admin login, forms, and API endpoints work?
• Did python manage.py migrate succeed on the server?
• Did collectstatic place files where Nginx expects them?
• Are logs clean after a restart?
• Is HTTPS enabled and redirecting correctly?
• Do you have backups for the database and uploaded media?

If you want a more structured environment for this kind of work, Vibesies is one of the places where a tenant can build and maintain a real Linux deployment with an AI agent in the loop. The useful part is not the novelty; it’s being able to inspect logs, edit config, and restart services without bouncing between a bunch of tools.

When Claude Code helps most

Claude Code is especially useful in three places:

• Reading existing code and spotting missing production settings.
• Editing config files like systemd units and Nginx sites without syntax mistakes.
• Iterating on failures by reading logs and making targeted fixes.

That doesn’t mean you should hand over the keys and walk away. Treat the agent like a capable teammate: it can make the changes, but you still review the output, verify the service status, and test the site end to end.

Conclusion: deploy Django with Claude Code on Linux the right way

The best way to deploy a Django app with Claude Code on Linux is to use the same production workflow you’d use without an agent: virtualenv, environment variables, migrations, Gunicorn, Nginx, and service management. Claude Code just makes it faster to inspect, edit, and troubleshoot the moving parts.

If you keep the deployment process small and methodical, you’ll end up with a Django app that boots reliably, serves static files correctly, and survives restarts. And if your stack lives in a sandboxed Linux environment like Vibesies, that workflow maps cleanly onto how a serious site should be run: real services, real logs, and real control.