5.1 KiB
================================================================================ HestiaCP + Django + Gunicorn Setup - Complete Checklist Prepared by: MohammadAmin Baranzehi Website / Contact: hacktube.ir Last updated: February 09, 2026
Prerequisites (Must be done before starting) ──────────────────────────────────────────── □ Domain already created in HestiaCP (e.g. example.com) □ Django project copied to: /home/amin/web/example.com/public_html/ □ Virtualenv created and packages installed: python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # gunicorn must be included □ Run collectstatic and migrate: python manage.py collectstatic --noinput python manage.py migrate □ In settings.py:
- DEBUG = False (or True for initial debugging)
- ALLOWED_HOSTS includes domain (e.g. ['pexample.com', '*'])
- STATIC_URL = '/static/'
- STATIC_ROOT = BASE_DIR / 'staticfiles'
Stage 1 – Place Custom NGINX Templates ──────────────────────────────────────────── □ Copy template files directly (no subfolder!) to: /usr/local/hestia/data/templates/web/nginx/django.tpl /usr/local/hestia/data/templates/web/nginx/django.stpl
□ Set correct permissions: sudo chown root:root /usr/local/hestia/data/templates/web/nginx/django.* sudo chmod 644 /usr/local/hestia/data/templates/web/nginx/django.*
Stage 2 – Apply Template in HestiaCP Panel ──────────────────────────────────────────── □ Log in to HestiaCP panel □ Go to: Web → Edit domain (example.com) □ In NGINX Template or Proxy Template section → select django □ Click Save □ (Strongly recommended) Force rebuild domain: sudo v-rebuild-web-domain amin example.com yes sudo systemctl restart nginx
Stage 3 – Create and Start Gunicorn Service ──────────────────────────────────────────── □ Run the helper script: add-gunicorn-service example.com user yourprojectname (or sudo /path/to/add-gunicorn-service.sh ... if not in PATH)
□ Restart service to apply: sudo systemctl restart gunicorn-example.com
Stage 4 – Verify Service, Socket and Permissions ──────────────────────────────────────────── □ Check service status (must be active (running)): sudo systemctl status gunicorn.example.com
□ Check socket existence and permissions: ls -l /home/amin/web/example.com/public_html/gunicorn.sock
Expected output: srw-rw---- 1 amin www-data ...
□ Fix socket permissions if wrong: sudo chown user:www-data gunicorn.sock sudo chmod 660 gunicorn.sock sudo systemctl restart gunicorn.example.com
□ Fix db.sqlite3 permissions (prevents readonly database error): ls -l db.sqlite3
Should be: -rw-rw-r-- 1 user www-data ...
sudo chown user:www-data db.sqlite3 sudo chmod 664 db.sqlite3
Stage 5 – Final Testing & Monitoring ──────────────────────────────────────────── □ Open site in browser: https://example.com □ Try login and basic functionality
□ Monitor Gunicorn logs in real-time: journalctl -u gunicorn.example.com -f
□ Monitor NGINX logs if issue occurs: tail -f /var/log/nginx/error.log tail -f /home/amin/web/example.com/logs/nginx.error.log # if exists
□ Optional direct socket test: curl --unix-socket gunicorn.sock http://localhost/
Quick Fixes for Common Issues ──────────────────────────────────────────── □ 502 Bad Gateway → Check NGINX log: tail -f /var/log/nginx/error.log → Fix socket permissions (chmod 660 + chown) → Rebuild domain and restart NGINX
□ Readonly database (db.sqlite3) → chown user:www-data db.sqlite3 && chmod 664 db.sqlite3
□ Default Hestia page still showing → mv index.html index.html.bak → sudo systemctl restart nginx
□ Template not showing in panel → Force rebuild: sudo v-rebuild-web-domain user yourdomain.com yes → Logout/login panel or clear browser cache
Important Post-Setup Notes ──────────────────────────────────────────── □ Set DEBUG = False in production □ Rename or remove index.html if default page appears □ After code update: git pull → collectstatic → migrate → restart gunicorn □ For new domains: repeat stages 2–5 only (templates are already there)