keepcalculator

06 Numbers and Powers

Stop Gunicorn & Nginx Serving the Default Django Project

Card No. 06·83078 · Updated · Standard formula, shown below

This guide walks you through stopping Gunicorn and Nginx from serving the default Django project—the one you get right after running django-admin startproject. You’ll learn how to shut down the development server, disable or reconfigure the Nginx site, and stop the Gunicorn process so that your custom app can take over. Before starting, make sure you have SSH access to your server and know the basics of the command line.

What You’ll Need

  • SSH access to your Linux server (Ubuntu/Debian assumed).
  • sudo privileges to manage system services.
  • Basic familiarity with the terminal and file editing (nano or vim).

Step-by-Step

  1. Identify the running processes. First, see what’s currently serving your site. Run ps aux | grep -E 'gunicorn|nginx' to list the relevant processes. Note the PID (process ID) and the command lines—this tells you which Gunicorn workers are active and where Nginx is configured.
  2. Stop the Django development server (if running). If you’re still using python manage.py runserver (often on port 8000), press Ctrl+C in that terminal. If it’s running in the background, find its PID with lsof -i :8000 and kill it with kill <PID>. This is not Gunicorn, but it’s a common source of confusion.
  3. Stop Gunicorn. If Gunicorn was started manually (e.g., gunicorn myproject.wsgi), find its master PID with pgrep -f gunicorn and terminate it gracefully: sudo kill -TERM <master_pid>. If Gunicorn is managed by systemd (common in production), use sudo systemctl stop gunicorn. To prevent it from restarting on boot, run sudo systemctl disable gunicorn.
  4. Disable the default Nginx site. Nginx usually has a default site enabled at /etc/nginx/sites-enabled/default. Disable it by removing the symlink: sudo rm /etc/nginx/sites-enabled/default. If you want to keep the file for reference, rename it instead: sudo mv /etc/nginx/sites-enabled/default /etc/nginx/sites-enabled/default.bak.
  5. Remove or comment out the default server block. If the default site is defined in /etc/nginx/nginx.conf (some setups), open that file with sudo nano /etc/nginx/nginx.conf and comment out the entire server { ... } block that listens on port 80 by adding # at the start of each line. Save and exit.
  6. Disable Nginx entirely (optional). If you don’t need Nginx for anything else, you can stop it completely: sudo systemctl stop nginx and sudo systemctl disable nginx. This will free port 80 and 443. Be aware this stops all websites served by Nginx on that server.
  7. Test the Nginx configuration. Before reloading, check for syntax errors: sudo nginx -t. If it reports no errors, reload Nginx to apply changes: sudo systemctl reload nginx (or sudo nginx -s reload). If you disabled Nginx, skip this step.
  8. Verify that the default page is gone. Visit your server’s IP or domain in a browser. You should see a connection refused error (if Nginx is stopped) or a 404/502 error (if Nginx is running but no site is configured). If you still see the default Django page, something is still running—recheck the processes.
  9. Clean up the default project files (optional). If you’re done with the default project, you can delete or move the project directory. Be careful: this is irreversible. Consider renaming it instead: mv /path/to/myproject /path/to/myproject_backup.

Common Mistakes

  • Forgetting to disable Gunicorn in systemd. Even after stopping it, if it’s enabled, it will restart on reboot. Always run sudo systemctl disable gunicorn.
  • Editing the wrong Nginx config file. Many tutorials mention /etc/nginx/sites-available/default, but the active file is in sites-enabled. Changes in sites-available only take effect if a symlink exists in sites-enabled.
  • Not testing Nginx config before reloading. A syntax error will cause Nginx to fail to reload, potentially taking down other sites. Always run sudo nginx -t first.
  • Killing the wrong Gunicorn process. Gunicorn has a master process and worker processes. Killing a worker is fine—the master will spawn a new one. You need to kill the master (the one with the lowest PID, usually). Use pkill -f gunicorn to kill all Gunicorn processes at once.
  • Assuming the default page is served by Nginx. If you see the default Django “It worked!” page, it could be served by Gunicorn directly on port 8000, not through Nginx. Check which port is being hit.

Tips

  • Use sudo systemctl status gunicorn and sudo systemctl status nginx to see if they are active or inactive.
  • If you want to keep Nginx but serve a different app, create a new server block in /etc/nginx/sites-available/ and symlink it to sites-enabled.
  • For Gunicorn, consider using a Unix socket instead of a TCP port—it’s more secure and faster. Update your Nginx config to proxy to the socket.
  • Always back up config files before editing. A simple cp command can save you from a broken setup.

Troubleshooting

Nginx still shows the default page after disabling the site. This usually means the default site is still enabled elsewhere. Check /etc/nginx/conf.d/ for any .conf files that define a server block. Also, clear your browser cache—the page might be cached.

Gunicorn won’t stop. If systemctl stop gunicorn doesn’t work, try sudo systemctl kill gunicorn. If it’s a manual process, use sudo pkill -9 gunicorn (force kill). Then check with ps aux | grep gunicorn.

Port 80 is still in use. Run sudo lsof -i :80 to see what’s listening. If it’s not Nginx, another web server (Apache, Caddy) might be running. Stop it similarly.

Nginx fails to reload after changes. Run sudo nginx -t to see the exact error. Common issues: missing semicolons, unmatched braces, or invalid directives. Fix the error and test again.

You see a 502 Bad Gateway. This means Nginx is running but can’t reach Gunicorn. This is expected if you stopped Gunicorn. If you want a different app, you need to configure Gunicorn to run that app and Nginx to proxy to it.

Frequently Asked Questions

Do I need to stop Nginx to stop serving the default Django project?

No, you only need to disable the default site. You can keep Nginx running for other sites or for a future custom configuration.

What’s the difference between stopping and disabling a systemd service?

Stopping (systemctl stop) halts the process immediately. Disabling (systemctl disable) prevents it from starting on boot. You usually want to do both.

How do I know if Gunicorn is running as a systemd service or manually?

Run systemctl status gunicorn. If it says “Unit gunicorn.service could not be found,” it’s likely running manually or under a different service name (like gunicorn@myproject). Use ps aux | grep gunicorn to see the command line.

Will stopping Nginx affect other websites on the same server?

Yes, if you stop Nginx entirely, all sites it serves will go down. If you only disable the default site, other sites remain unaffected.

Can I just delete the default project files?

Yes, but be careful. If the project is still referenced by Gunicorn or Nginx, you’ll get errors. It’s safer to rename the directory first and test, then delete later.

What if I want to serve a different Django project later?

You’ll need to configure Gunicorn to point to the new project’s WSGI file and update Nginx’s proxy_pass to match. This is beyond the scope of this guide, but the steps above free up the system for that.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →