firefrost-operations-manual/docs/reference/technical-readme.md

# 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**