Documentation Standardisation & Unit Test Stabilization

- Overhauled README.md to serve as a unified system index and WIP tracker. - Standardized documentation filenames (ARCH__, GUIDE__, PLAN__) for better discoverability. - Archived completed project plans and scopes. - Fixed regressions in unit tests (errors, models, email) caused by V3 architectural updates. - Ensured unit tests remain non-destructive and environment-independent via mocking.
2026-01-28 12:15:01 -05:00
parent 3eaf176b05
commit 860cf80a4e
17 changed files with 118 additions and 28 deletions
--- a/documentation/GUIDE__DEPLOYMENT_MANUAL.md
+++ b/documentation/GUIDE__DEPLOYMENT_MANUAL.md
@@ -0,0 +1,153 @@
+# Manual Server Deployment Guide (Non-Docker)
+
+This guide describes the manual process for deploying the Aether API on a Linux server using Nginx, Gunicorn, and Systemd.
+
+## 1. Initial Server Setup
+
+### Clone the Repository
+```bash
+sudo git clone https://scott_idem@bitbucket.org/oneskyit/one-sky-it-api-fastapi.git /srv/http/dev_fastapi.oneskyit.com
+```
+
+### Configure Permissions
+```bash
+sudo mkdir admin/log
+sudo chown http:http -R /srv/http/dev_fastapi.oneskyit.com/
+sudo chmod 775 -R /srv/http/dev_fastapi.oneskyit.com/
+```
+
+### Environment Preparation
+```bash
+cd /srv/http/dev_fastapi.oneskyit.com/
+git switch development
+
+virtualenv environment
+source environment/bin/activate
+pip install -U -r admin/requirements.txt
+```
+
+## 2. Gunicorn Configuration (Systemd)
+
+### Socket Configuration (`/etc/systemd/system/gunicorn.socket`)
+```ini
+[Unit]
+Description=gunicorn socket
+
+[Socket]
+ListenStream=/run/gunicorn.sock
+User=http
+
+[Install]
+WantedBy=sockets.target
+```
+
+### Service Configuration (`/etc/systemd/system/gunicorn.service`)
+```ini
+[Unit]
+Description=gunicorn daemon
+Requires=gunicorn.socket
+After=network.target
+
+[Service]
+Type=notify
+User=root
+Group=root
+RuntimeDirectory=gunicorn
+WorkingDirectory=/srv/http/dev_fastapi.oneskyit.com
+Environment="PATH=/srv/http/dev_fastapi.oneskyit.com/environment/bin"
+ExecStart=/srv/http/dev_fastapi.oneskyit.com/environment/bin/gunicorn \
+    --bind unix:/srv/http/dev_fastapi.oneskyit.com/gunicorn.sock \
+    -m 007 app.main:app \
+    --workers 4 \
+    -k uvicorn.workers.UvicornWorker \
+    --access-logfile admin/log/access.log \
+    --error-logfile admin/log/error.log \
+    --capture-output --keep-alive 5
+
+ExecReload=/bin/kill -s HUP $MAINPID
+KillMode=mixed
+TimeoutStopSec=5
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Activation
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable gunicorn.socket
+sudo systemctl start gunicorn.socket
+```
+
+## 3. Nginx Configuration
+
+Create a site configuration file at `/etc/nginx/sites-available/dev_fastapi.oneskyit.com`:
+
+```nginx
+server {
+  access_log  /var/log/nginx/access_dev_fastapi.oneskyit.com.log;
+
+  listen 443 ssl;
+  listen [::]:443 ssl http2;
+  server_name dev-fastapi.oneskyit.com;
+
+  ssl_certificate /etc/letsencrypt/live/oneskyit.com-0001/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/oneskyit.com-0001/privkey.pem;
+
+  client_max_body_size 4096M;
+
+  location / {
+        proxy_set_header Host $http_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;
+
+        proxy_redirect off;
+        proxy_buffering off;
+
+        proxy_pass http://unix:/run/gunicorn.sock;
+  }
+
+  # WebSocket Support
+  location ~ ^/(ws|ws_redis) {
+        proxy_set_header Host $http_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;
+
+        proxy_http_version 1.1;
+        proxy_redirect off;
+        proxy_buffering off;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        proxy_pass http://unix:/run/gunicorn.sock;
+  }
+}
+
+server {
+  listen 80;
+  listen [::]:80;
+  server_name dev-fastapi.oneskyit.com;
+  return 301 https://$host$request_uri;
+}
+```
+
+Enable and restart Nginx:
+```bash
+sudo ln -s /etc/nginx/sites-available/dev_fastapi.oneskyit.com /etc/nginx/sites-enabled/
+sudo systemctl restart nginx.service
+```
+
+## 4. Troubleshooting
+```bash
+# Check status
+sudo systemctl status gunicorn.socket
+sudo systemctl status gunicorn.service
+sudo systemctl status nginx.service
+
+# List active units
+systemctl list-units --type=service --state=running
+```