Revise HestiaCP + Django + Gunicorn deployment guide

Updated the README.md to enhance the deployment guide for HestiaCP and Django with Gunicorn, including formatting improvements and additional sections.

README.md

@@ -1,117 +1,78 @@
-================================================================================
+# HestiaCP + Django + Gunicorn Deployment Guide
-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)
+**Simple, fast and reliable way** to run Django applications on HestiaCP using Gunicorn (unix socket) and NGINX reverse proxy — without manual nginx.conf editing every time.
-────────────────────────────────────────────
-□ 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
+Prepared by: **MohammadAmin Baranzehi**  
-────────────────────────────────────────────
+Website/Contact: [hacktube.ir](https://hacktube.ir)  
-□ Copy template files directly (no subfolder!) to:
+Last updated: February 2026
-   /usr/local/hestia/data/templates/web/nginx/django.tpl
-   /usr/local/hestia/data/templates/web/nginx/django.stpl
 
-□ Set correct permissions:
+## Features
-   sudo chown root:root /usr/local/hestia/data/templates/web/nginx/django.*
+- Unix socket for secure & fast communication
-   sudo chmod 644 /usr/local/hestia/data/templates/web/nginx/django.*
+- Custom NGINX templates (no subfolder needed)
+- One-command systemd service creation
+- Static/media files served directly by NGINX
+- Tested on Ubuntu 22.04 + HestiaCP 1.6.x+
 
-Stage 2 – Apply Template in HestiaCP Panel
+## Requirements
-────────────────────────────────────────────
+- HestiaCP with NGINX proxy mode
-□ Log in to HestiaCP panel
+- Django project in `/home/user/web/yourdomain.com/public_html/`
-□ Go to: Web → Edit domain (example.com)
+- Python 3.10+ and virtualenv
-□ In NGINX Template or Proxy Template section → select django
+- Gunicorn installed in venv
-□ Click Save
+
-□ (Strongly recommended) Force rebuild domain:
+## Step-by-Step Deployment Checklist
-   sudo v-rebuild-web-domain amin example.com yes
+
+### 1. Place Custom NGINX Templates
+Copy files **directly** (no subfolder) to:
+/usr/local/hestia/data/templates/web/nginx/django-gunicorn.tpl
+/usr/local/hestia/data/templates/web/nginx/django-gunicorn.stpl
+textSet permissions:
+```bash
+sudo chown root:root /usr/local/hestia/data/templates/web/nginx/django-gunicorn.*
+sudo chmod 644 /usr/local/hestia/data/templates/web/nginx/django-gunicorn.*
+2. Apply Template in HestiaCP Panel
+
+Go to: Web → Edit domain (e.g. example.com)
+Select django-gunicorn in NGINX Template (or Proxy Template)
+Click Save
+Force rebuild (recommended):Bashsudo v-rebuild-web-domain amin example.com yes
 sudo systemctl restart nginx
 
-Stage 3 – Create and Start Gunicorn Service
+3. Create & Start Gunicorn Service
-────────────────────────────────────────────
+Run:
-□ Run the helper script:
+Bashadd-gunicorn-service example.com amin yourprojectname
-   add-gunicorn-service example.com user yourprojectname
+# Example: add-gunicorn-service panel.example.com amin zamzam
-   (or sudo /path/to/add-gunicorn-service.sh ... if not in PATH)
+Restart:
+Bashsudo systemctl restart gunicorn-example.com
+4. Verify Everything
 
-□ Restart service to apply:
+Service status:Bashsudo systemctl status gunicorn-example.com
-   sudo systemctl restart gunicorn-example.com
+Socket check:Bashls -l /home/amin/web/example.com/public_html/gunicorn.sock
-
+# Expected: srw-rw---- 1 amin www-data ...
-Stage 4 – Verify Service, Socket and Permissions
+Fix socket permissions if needed:Bashsudo chown amin:www-data gunicorn.sock
-────────────────────────────────────────────
-□ 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
+sudo systemctl restart gunicorn-example.com
-
+Fix db.sqlite3 permissions:Bashsudo chown amin:www-data db.sqlite3
-□ 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
+5. Test & Monitor
-────────────────────────────────────────────
-□ Open site in browser: https://example.com
-□ Try login and basic functionality
 
-□ Monitor Gunicorn logs in real-time:
+Open: https://example.com
-   journalctl -u gunicorn.example.com -f
+Real-time Gunicorn logs:Bashjournalctl -u gunicorn-example.com -f
+NGINX logs:Bashtail -f /var/log/nginx/error.log
 
-□ Monitor NGINX logs if issue occurs:
+Quick Fixes
-   tail -f /var/log/nginx/error.log
-   tail -f /home/amin/web/example.com/logs/nginx.error.log   # if exists
 
-□ Optional direct socket test:
+502 Bad Gateway → Check socket permissions + rebuild domain
-   curl --unix-socket gunicorn.sock http://localhost/
+Readonly database → chown/chmod db.sqlite3
+Default page shows → mv index.html index.html.bak
+Template not in list → Force rebuild + logout/login panel
 
-Quick Fixes for Common Issues
+Important Notes
-────────────────────────────────────────────
-□ 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)
+Set DEBUG = False in production
-   → chown user:www-data db.sqlite3 && chmod 664 db.sqlite3
+After code changes: git pull → collectstatic → migrate → restart gunicorn
+For new domains: Repeat steps 2–5 only (templates stay forever)
 
-□ Default Hestia page still showing
+Enjoy your stable Django setup! 🚀
-   → mv index.html index.html.bak
+Prepared with ❤️ by MohammadAmin Baranzehi
-   → sudo systemctl restart nginx
+https://hacktube.ir
-
-□ 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)
-
-Enjoy your stable Django setup on HestiaCP!
-Prepared by: MohammadAmin Baranzehi
-Website / Contact: hacktube.ir
-================================================================================