From 051165077d3a27e9869f941090010194e6da2d3a Mon Sep 17 00:00:00 2001 From: mkrause612 Date: Sun, 8 Feb 2026 01:49:18 -0600 Subject: [PATCH] Add docs/TECHNICAL_README.md --- docs/TECHNICAL_README.md | 289 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/TECHNICAL_README.md diff --git a/docs/TECHNICAL_README.md b/docs/TECHNICAL_README.md new file mode 100644 index 0000000..468e93f --- /dev/null +++ b/docs/TECHNICAL_README.md @@ -0,0 +1,289 @@ +# FIREFROST GAMING: Gitea Technical Dossier + +**Project:** Frostwall Protocol - Phase 0.5 Management Layer +**Service:** Gitea (Version Control System) +**Deployment Date:** February 8, 2026 +**Lead Engineer:** Michael +**Status:** ✅ OPERATIONAL +**Document Version:** 1.0 + +--- + +## 1. Service Specifications + +### 1.1 Network Configuration + +| Parameter | Value | +|-----------|-------| +| **Service Name** | Gitea | +| **Purpose** | Git Version Control & Repository Management | +| **Dedicated IP** | 74.63.218.202 | +| **Subnet** | 74.63.218.200/29 (Command Center /29 Block) | +| **Subdomain** | git.firefrostgaming.com | +| **Internal Port** | 3000 (localhost only) | +| **External Ports** | 80 (HTTP → HTTPS redirect), 443 (HTTPS) | +| **SSH Port** | 2222 (Git SSH access) | + +### 1.2 Application Paths + +| Component | Path | +|-----------|------| +| **Binary** | /usr/local/bin/gitea | +| **Home Directory** | /var/lib/gitea | +| **Data Directory** | /var/lib/gitea/data | +| **Repository Root** | /var/lib/gitea/repositories | +| **Git LFS Root** | /var/lib/gitea/lfs | +| **Log Directory** | /var/lib/gitea/log | +| **Configuration** | /etc/gitea/app.ini | +| **Systemd Service** | /etc/systemd/system/gitea.service | +| **Database** | /var/lib/gitea/data/gitea.db (SQLite3) | + +### 1.3 Reverse Proxy & SSL + +| Parameter | Value | +|-----------|-------| +| **Proxy Software** | Nginx 1.24.0 | +| **Configuration** | /etc/nginx/sites-available/git.firefrostgaming.com | +| **SSL Provider** | Let's Encrypt | +| **Certificate Path** | /etc/letsencrypt/live/git.firefrostgaming.com/ | +| **Expiration** | May 9, 2026 (Auto-renewal enabled) | + +--- + +## 2. Deployment Changelog v1.0 + +### 2.1 System Preparation +- Created system user `gitea` with home directory /var/lib/gitea +- Created directory structure: /var/lib/gitea/{custom,data,log} +- Set ownership: gitea:gitea on all application directories +- Set permissions: 750 on application directories + +### 2.2 Gitea Installation +- Downloaded Gitea binary v1.21.5 to /usr/local/bin/gitea +- Initialized SQLite database at /var/lib/gitea/data/gitea.db +- Created base configuration at /etc/gitea/app.ini + +### 2.3 Systemd Service +- Created service file: /etc/systemd/system/gitea.service +- Configured to run as gitea user +- Enabled auto-start on boot + +### 2.4 Nginx Reverse Proxy +- Installed Nginx 1.24.0 +- Removed default site to prevent 0.0.0.0:80 binding conflict +- Created site config: /etc/nginx/sites-available/git.firefrostgaming.com +- Configured IP-specific binding: 74.63.218.202:80 and :443 +- HTTP→HTTPS redirect enabled +- Proxy pass to localhost:3000 + +### 2.5 DNS Configuration +- Added Cloudflare A record: git.firefrostgaming.com → 74.63.218.202 +- Proxy status: DNS only (gray cloud) +- Propagation verified via nslookup + +### 2.6 Frostwall (UFW) Configuration +- Installed UFW v0.36.2-6 +- Added SSH protection rule (port 22) +- Protected primary gateway IP (63.143.34.217) +- Opened HTTP (80) on 74.63.218.202 +- Opened HTTPS (443) on 74.63.218.202 +- Enabled firewall + +### 2.7 SSL Certificate +- Installed Certbot with Nginx plugin +- Obtained Let's Encrypt certificate for git.firefrostgaming.com +- Auto-renewal configured via systemd timer + +### 2.8 Gitea Web Installation +- Configured via web installer at https://git.firefrostgaming.com +- Database: SQLite3 +- Security: Disabled public registration, require sign-in to view +- Created administrator account: mkrause612 +- Locked configuration permissions post-install + +### 2.9 Master Archive Creation +- Initialized local Git repository: /root/firefrost-master-configs +- Created folder structure: management/, nodes/, security/, web/, docs/ +- Copied configuration files to repository +- Created .gitignore to protect sensitive files (app.ini) +- Created sanitized template: app.ini.template +- Committed and pushed to Gitea repository + +--- + +## 3. Frostwall (UFW) Rules + +### 3.1 Commands Used +```bash +# Install UFW +apt install -y ufw + +# Prevent SSH lockout +ufw allow 22/tcp + +# Protect primary gateway +ufw allow in on ens3 to 63.143.34.217 + +# Open Gitea HTTP (Let's Encrypt validation & redirect) +ufw allow in on ens3 to 74.63.218.202 port 80 proto tcp + +# Open Gitea HTTPS (Web interface) +ufw allow in on ens3 to 74.63.218.202 port 443 proto tcp + +# Enable firewall +ufw --force enable +``` + +### 3.2 Active Rules +``` +Status: active + +To Action From +-- ------ ---- +22/tcp ALLOW IN Anywhere +63.143.34.217 on ens3 ALLOW IN Anywhere +74.63.218.202 80/tcp on ens3 ALLOW IN Anywhere +74.63.218.202 443/tcp on ens3 ALLOW IN Anywhere +22/tcp (v6) ALLOW IN Anywhere (v6) +``` + +--- + +## 4. Service Management Commands + +### 4.1 Gitea Service +```bash +# Start Gitea +systemctl start gitea + +# Stop Gitea +systemctl stop gitea + +# Restart Gitea +systemctl restart gitea + +# Check status +systemctl status gitea + +# View logs +journalctl -u gitea -f +``` + +### 4.2 Nginx +```bash +# Test configuration +nginx -t + +# Reload configuration +systemctl reload nginx + +# Restart Nginx +systemctl restart nginx +``` + +### 4.3 SSL Certificate +```bash +# Test renewal +certbot renew --dry-run + +# Force renewal +certbot renew --force-renewal + +# Check certificate status +certbot certificates + +# Check auto-renewal timer +systemctl status certbot.timer +``` + +--- + +## 5. Security Configuration + +### 5.1 Application Security +- User registration: Disabled (admin-only) +- Public browsing: Disabled (requires sign-in) +- Gravatar: Disabled (privacy) +- Local mode: Enabled (no external CDN) +- Password hashing: pbkdf2 + +### 5.2 File Permissions +- Configuration directory: /etc/gitea (750, root:gitea) +- Configuration file: /etc/gitea/app.ini (640, gitea:gitea) +- Application directories: /var/lib/gitea/* (750, gitea:gitea) + +### 5.3 Network Security +- Internal binding: 127.0.0.1:3000 only +- External access: Via Nginx reverse proxy only +- Dedicated IP: 74.63.218.202 (isolated from primary gateway) + +--- + +## 6. Backup Procedures + +### 6.1 Configuration Backup +```bash +# Backup Gitea config +cp /etc/gitea/app.ini /root/backups/gitea-app.ini.$(date +%Y%m%d) + +# Backup Nginx config +cp /etc/nginx/sites-available/git.firefrostgaming.com \ + /root/backups/nginx-gitea.$(date +%Y%m%d) +``` + +### 6.2 Repository Backup +```bash +# Backup all repositories +tar -czf /root/backups/gitea-repos-$(date +%Y%m%d).tar.gz \ + /var/lib/gitea/repositories + +# Backup database +cp /var/lib/gitea/data/gitea.db \ + /root/backups/gitea.db.$(date +%Y%m%d) +``` + +--- + +## 7. Troubleshooting + +### 7.1 Service Not Accessible + +**Check Gitea service:** +```bash +systemctl status gitea +``` + +**Check Nginx binding:** +```bash +ss -tlnp | grep 74.63.218.202 +``` + +**Check firewall:** +```bash +ufw status | grep 74.63.218.202 +``` + +**Check DNS:** +```bash +nslookup git.firefrostgaming.com +``` + +### 7.2 502 Bad Gateway +- **Cause:** Gitea service not running +- **Fix:** `systemctl start gitea` + +### 7.3 Permission Denied Errors +- **Cause:** Incorrect file ownership +- **Fix:** `chown -R gitea:gitea /var/lib/gitea` + +--- + +## 8. Revision History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| **1.0** | 2026-02-08 | Michael | Initial deployment. Gitea 1.21.5 installed on 74.63.218.202 with Nginx reverse proxy, Let's Encrypt SSL, UFW firewall, and Master Archive repository created. | + +--- + +**END OF TECHNICAL DOSSIER** \ No newline at end of file