firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

Add Gitea deployment documentation

Browse Source
This commit is contained in:
Michael Krause
2026-02-08 01:35:35 -06:00
parent 655f6de7cc
commit b01b9e006c
1 changed files with 382 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

382
docs/gitea-deployment.md Normal file
View File

@@ -0,0 +1,382 @@
# 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%)