firefrost-operations-manual/docs/gitea-deployment.md

# FIREFROST GAMING: Gitea Deployment Documentation

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

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

### 1.3 Database

| Parameter | Value |
|-----------|-------|
| **Type** | SQLite3 |
| **Path** | /var/lib/gitea/data/gitea.db |
| **Rationale** | Lightweight, embedded, zero-maintenance for single-server deployment |

### 1.4 SSL/TLS Configuration

| Parameter | Value |
|-----------|-------|
| **Certificate Provider** | Let's Encrypt |
| **Certificate Path** | /etc/letsencrypt/live/git.firefrostgaming.com/fullchain.pem |
| **Private Key Path** | /etc/letsencrypt/live/git.firefrostgaming.com/privkey.pem |
| **Expiration** | May 9, 2026 |
| **Auto-Renewal** | Enabled (Certbot systemd timer) |

### 1.5 Reverse Proxy

| Parameter | Value |
|-----------|-------|
| **Proxy Software** | Nginx 1.24.0 |
| **Configuration File** | /etc/nginx/sites-available/git.firefrostgaming.com |
| **Enabled Symlink** | /etc/nginx/sites-enabled/git.firefrostgaming.com |
| **Proxy Target** | http://127.0.0.1:3000 |
| **Max Upload Size** | 512M |

---

## 2. Changelog v1.0 - Initial Deployment

### 2.1 System Preparation
- **Updated system packages:** `apt update && apt upgrade`
- **Installed dependencies:** git, curl, wget, gnupg2
- **Created system user:** `gitea` (system user, disabled password, home: /var/lib/gitea)
- **Created directory structure:** /var/lib/gitea/{custom,data,log}
- **Set ownership:** gitea:gitea on all application directories
- **Set permissions:** 750 on /var/lib/gitea

### 2.2 Gitea Installation
- **Downloaded Gitea binary:** v1.21.5 (linux-amd64) to /usr/local/bin/gitea
- **Set executable permissions:** 755 on binary
- **Initialized SQLite database:** /var/lib/gitea/data/gitea.db
- **Created configuration file:** /etc/gitea/app.ini with base settings

### 2.3 Systemd Service Configuration
- **Created service file:** /etc/systemd/system/gitea.service
- **Service type:** Simple
- **Run as:** gitea user/group
- **Working directory:** /var/lib/gitea
- **ExecStart:** /usr/local/bin/gitea web -c /etc/gitea/app.ini
- **Auto-restart:** Enabled
- **Boot enabled:** systemctl enable gitea

### 2.4 Nginx Reverse Proxy Setup
- **Installed Nginx:** v1.24.0 (Ubuntu)
- **Disabled default site:** Removed /etc/nginx/sites-enabled/default to prevent 0.0.0.0:80 binding conflict
- **Created Gitea site config:** /etc/nginx/sites-available/git.firefrostgaming.com
- **IP binding:** Nginx listens ONLY on 74.63.218.202:80 and :443
- **HTTP redirect:** Port 80 → 301 redirect to HTTPS
- **HTTPS proxy:** Port 443 → proxy_pass to localhost:3000
- **Generated temporary self-signed certificate:** For initial testing
- **Enabled site:** Symlinked to /etc/nginx/sites-enabled/
- **Restarted Nginx:** Full restart to clear inherited socket bindings

### 2.5 DNS Configuration
- **Provider:** Cloudflare
- **Record added:** git.firefrostgaming.com A 74.63.218.202
- **Proxy status:** DNS only (gray cloud) - required for Let's Encrypt validation
- **TTL:** Auto
- **Propagation verified:** nslookup confirmed 74.63.218.202 resolution

### 2.6 Frostwall (UFW) Configuration
- **Installed UFW:** v0.36.2-6
- **Removed packages:** iptables-persistent, netfilter-persistent (conflicting)
- **Added SSH rule:** Port 22 allowed (prevent lockout)
- **Added primary gateway rule:** Full access to 63.143.34.217 on ens3
- **Added Gitea HTTP rule:** Port 80 on 74.63.218.202 via ens3
- **Added Gitea HTTPS rule:** Port 443 on 74.63.218.202 via ens3
- **Enabled firewall:** ufw --force enable

### 2.7 SSL Certificate Deployment
- **Installed Certbot:** certbot + python3-certbot-nginx
- **Obtained Let's Encrypt certificate:** For git.firefrostgaming.com
- **Email registered:** mkrause612@gmail.com (renewal notifications)
- **Certificate deployed:** Certbot automatically updated Nginx config
- **Auto-renewal configured:** Certbot systemd timer active

### 2.8 Gitea Web Installation
- **Accessed installer:** https://git.firefrostgaming.com
- **Fixed permissions temporarily:** chown gitea:gitea /etc/gitea and app.ini for web installer write access
- **Configured via web UI:**
  - Database: SQLite3 at /var/lib/gitea/data/gitea.db
  - Site title: Firefrost Gaming - Git Repository
  - Server domain: git.firefrostgaming.com
  - SSH port: 2222
  - Base URL: https://git.firefrostgaming.com/
  - Server settings: Enable Local Mode, Disable Gravatar, Disable Self-Registration, Require Sign-In to View Pages
  - Administrator account: mkrause612 created
- **Locked down permissions post-install:**
  - chmod 750 /etc/gitea
  - chmod 640 /etc/gitea/app.ini
- **Restarted Gitea service:** Applied final configuration

### 2.9 Verification & Testing
- **HTTPS access verified:** curl -I returned HTTP/2 200
- **SSL certificate verified:** openssl s_client confirmed CN=git.firefrostgaming.com
- **Port bindings verified:** ss -tlnp confirmed Nginx on 74.63.218.202:80 and :443
- **Created test repository:** firefrost-phase0-configs (private)
- **Repository accessibility confirmed:** HTTPS clone URL working

---

## 3. Security Posture

### 3.1 Application Security
- **User registration:** Disabled (admin-only account creation)
- **Public browsing:** Disabled (requires sign-in to view)
- **Gravatar:** Disabled (no external avatar service calls)
- **Local mode:** Enabled (all assets served locally, no CDN)
- **Password hashing:** pbkdf2 algorithm
- **Hidden email domain:** noreply.git.firefrostgaming.com

### 3.2 Network Security
- **Internal service binding:** Gitea bound to 127.0.0.1:3000 only (not externally accessible)
- **Reverse proxy isolation:** All external access via Nginx on dedicated IP
- **IP-specific firewall rules:** UFW rules target 74.63.218.202 only
- **Primary gateway protection:** 63.143.34.217 unchanged, zero new services

### 3.3 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)
- **Binary:** /usr/local/bin/gitea (755, root:root)

---

## 4. Frostwall (UFW) Rules Summary

### 4.1 Active Rules for 74.63.218.202
```bash
# HTTP (Port 80) - Let's Encrypt validation & HTTPS redirect
ufw allow in on ens3 to 74.63.218.202 port 80 proto tcp

# HTTPS (Port 443) - Gitea web interface
ufw allow in on ens3 to 74.63.218.202 port 443 proto tcp
```

### 4.2 Complete Firewall Status
```
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.3 Port Allocation

| Port | Protocol | Purpose | Scope |
|------|----------|---------|-------|
| 22 | TCP | SSH Management | Global (inherited) |
| 80 | TCP | HTTP (redirect) | 74.63.218.202 only |
| 443 | TCP | HTTPS (Gitea web) | 74.63.218.202 only |
| 2222 | TCP | Git SSH (future) | Not yet exposed via firewall |
| 3000 | TCP | Gitea internal | localhost only (not firewalled) |

---

## 5. Operational Notes

### 5.1 Service Management

**Start Gitea:**
```bash
systemctl start gitea
```

**Stop Gitea:**
```bash
systemctl stop gitea
```

**Restart Gitea:**
```bash
systemctl restart gitea
```

**Check status:**
```bash
systemctl status gitea
```

**View logs:**
```bash
journalctl -u gitea -f
```

### 5.2 Nginx Management

**Test configuration:**
```bash
nginx -t
```

**Reload configuration:**
```bash
systemctl reload nginx
```

**Restart Nginx:**
```bash
systemctl restart nginx
```

### 5.3 SSL Certificate Renewal

**Manual renewal (testing):**
```bash
certbot renew --dry-run
```

**Force renewal:**
```bash
certbot renew --force-renewal
```

**Auto-renewal status:**
```bash
systemctl status certbot.timer
```

### 5.4 Configuration Backup

**Backup configuration:**
```bash
cp /etc/gitea/app.ini /etc/gitea/app.ini.backup.$(date +%Y%m%d)
```

**Backup repositories:**
```bash
tar -czf /root/gitea-repos-backup-$(date +%Y%m%d).tar.gz /var/lib/gitea/repositories
```

---

## 6. Troubleshooting

### 6.1 Common Issues

**Issue:** Gitea not accessible via HTTPS
- **Check Nginx binding:** `ss -tlnp | grep 74.63.218.202`
- **Check Gitea service:** `systemctl status gitea`
- **Check firewall:** `ufw status | grep 74.63.218.202`
- **Check DNS:** `nslookup git.firefrostgaming.com`

**Issue:** 502 Bad Gateway
- **Cause:** Gitea service not running
- **Fix:** `systemctl start gitea`

**Issue:** Permission denied errors
- **Cause:** Incorrect file ownership or permissions
- **Fix:** `chown -R gitea:gitea /var/lib/gitea`

**Issue:** SSL certificate expired
- **Check expiration:** `certbot certificates`
- **Renew manually:** `certbot renew`

### 6.2 Port Binding Conflicts

**Check what's using a port:**
```bash
ss -tlnp | grep :PORT_NUMBER
```

**Check Nginx configuration:**
```bash
nginx -T | grep listen
```

---

## 7. Phase 0.5 Integration

### 7.1 Management Layer Position

**Gitea Role:** Source of truth for all Firefrost Gaming infrastructure configurations, scripts, and documentation.

**Integration Points:**
- **Uptime Kuma (Planned):** Will monitor Gitea health endpoint
- **BookStack (Planned):** Will reference Gitea repos in documentation
- **Netdata (Planned):** Will track Gitea resource usage
- **Vaultwarden (Planned):** Will store Gitea admin credentials

### 7.2 Repository Structure (Recommended)
```
firefrost-phase0-configs/
├── docs/
│   ├── phase0-technical-changelog.md
│   ├── phase0-addendum-service-audit.md
│   └── gitea-deployment.md (this document)
├── configs/
│   ├── nginx/
│   │   └── git.firefrostgaming.com.conf
│   ├── systemd/
│   │   └── gitea.service
│   └── gitea/
│       └── app.ini.template
└── scripts/
    ├── backup-gitea.sh
    └── restore-gitea.sh
```

---

## 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, and UFW firewall. First repository created. |

---

## 9. Related Documentation

- `FIREFROST_GAMING__Phase_0_Technical_Change_Log.md` - Vanilla Reset baseline
- `FIREFROST_GAMING__Phase_0_Addendum.md` - Service reallocation audit
- `Firefrost_Vanilla_Manifest.md` v1.3 - Infrastructure inventory
- Phase 0.5 Master Plan - Management layer architecture

---

**END OF DOCUMENT**

**Document Generated:** 2026-02-08 01:15 CST  
**Service Status:** ✅ OPERATIONAL  
**Next Service:** Uptime Kuma (74.63.218.203) - status.firefrostgaming.com  
**Phase 0.5 Progress:** 1/5 Services Deployed (20%)