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

Add Phase 0.5 Service 1 (Gitea) session summary and changelog

Browse Source
This commit is contained in:
Michael Krause
2026-02-08 02:19:51 -06:00
parent e9745bbea7
commit a541cafe77
1 changed files with 777 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

777
docs/session-summary-gitea.md Normal file
View File

@@ -0,0 +1,777 @@
# FIREFROST GAMING: Phase 0.5 Session Summary
## Service 1 Deployment - Gitea Version Control System
**Session Date:** February 8, 2026
**Session Duration:** ~3 hours
**Lead Engineer:** Michael
**System Architect:** Claude "The Wizard"
**Status:** ✅ COMPLETE
**Document Version:** 1.0
---
## Executive Summary
Successfully deployed the first of five management layer services for Firefrost Gaming's Phase 0.5 infrastructure expansion. Gitea (Git version control system) is now operational on dedicated IP 74.63.218.202 with SSL encryption, firewall protection, and complete documentation.
**Key Achievement:** Established the "Master Archive" - a Git repository containing all infrastructure configurations with version control and change tracking.
---
## Services Deployed
### Gitea - Version Control System
| Parameter | Value |
|-----------|-------|
| **Service** | Gitea v1.21.5 |
| **IP Address** | 74.63.218.202 (dedicated) |
| **Subdomain** | git.firefrostgaming.com |
| **Internal Port** | 3000 (localhost only) |
| **External Access** | HTTPS (443) via Nginx reverse proxy |
| **Database** | SQLite3 (/var/lib/gitea/data/gitea.db) |
| **SSL Provider** | Let's Encrypt (expires May 9, 2026) |
| **Auto-Renewal** | Enabled via Certbot systemd timer |
| **Status** | ✅ OPERATIONAL |
---
## Technical Changelog
### 1. System Preparation
**Packages Installed:**
- git, curl, wget, gnupg2 (dependencies)
- nginx 1.24.0 (reverse proxy)
- ufw 0.36.2-6 (firewall)
- certbot + python3-certbot-nginx (SSL certificates)
**System User Created:**
- Username: `gitea`
- Type: System user (--system)
- Home directory: `/var/lib/gitea`
- Shell: Disabled (--disabled-password)
- Purpose: Run Gitea service with least privilege
**Directory Structure:**
```
/var/lib/gitea/
├── custom/ (customizations)
├── data/ (SQLite database + LFS)
│ ├── gitea.db
│ └── lfs/
├── log/ (application logs)
└── repositories/ (Git repositories)
/etc/gitea/
└── app.ini (configuration file)
/etc/systemd/system/
└── gitea.service (systemd unit)
/etc/nginx/sites-available/
└── git.firefrostgaming.com (reverse proxy config)
```
**Permissions Set:**
- `/var/lib/gitea`: 750 (gitea:gitea)
- `/etc/gitea`: 750 (root:gitea) - locked after install
- `/etc/gitea/app.ini`: 640 (gitea:gitea) - locked after install
---
### 2. Gitea Installation
**Binary Deployment:**
- Downloaded: Gitea 1.21.5 (linux-amd64)
- Location: `/usr/local/bin/gitea`
- Permissions: 755 (executable)
- SHA verification: Passed
**Database Initialization:**
- Type: SQLite3 (embedded, zero-maintenance)
- Location: `/var/lib/gitea/data/gitea.db`
- Rationale: Lightweight, appropriate for single-server deployment
**Configuration Created:**
- File: `/etc/gitea/app.ini`
- Mode: Production (`RUN_MODE = prod`)
- Features enabled: Git LFS, SSH (port 2222), Local Mode
- Features disabled: Public registration, external avatars, update checker
---
### 3. Systemd Service Configuration
**Service File:** `/etc/systemd/system/gitea.service`
**Key Settings:**
- Type: Simple
- User/Group: gitea:gitea
- WorkingDirectory: `/var/lib/gitea`
- ExecStart: `/usr/local/bin/gitea web -c /etc/gitea/app.ini`
- Restart: Always
- WantedBy: multi-user.target (auto-start on boot)
**Service Management:**
```bash
systemctl daemon-reload # Loaded service
systemctl enable gitea # Enabled auto-start
systemctl start gitea # Started service
systemctl status gitea # Verified running
```
---
### 4. Nginx Reverse Proxy Setup
**Issue Encountered:** Default Nginx site was binding to `0.0.0.0:80`, preventing IP-specific binding.
**Resolution:** Removed `/etc/nginx/sites-enabled/default`
**Configuration:** `/etc/nginx/sites-available/git.firefrostgaming.com`
**Binding Strategy:**
- HTTP (80): `listen 74.63.218.202:80` → 301 redirect to HTTPS
- HTTPS (443): `listen 74.63.218.202:443 ssl http2`
- Proxy target: `http://127.0.0.1:3000`
- Max upload: 512M (for large repository pushes)
**Initial SSL:** Self-signed certificate (temporary for testing)
- Generated via OpenSSL
- Replaced by Let's Encrypt in Step 7
**Service Restart Required:**
- Issue: Port 80 still showing `0.0.0.0` binding after reload
- Cause: Nginx inherited sockets from previous config
- Fix: `systemctl restart nginx` (full restart cleared inherited sockets)
- Result: Ports 80 and 443 correctly bound to 74.63.218.202
---
### 5. DNS Configuration
**Provider:** Cloudflare
**Zone:** firefrostgaming.com
**Record Added:**
- Type: A
- Name: git
- Value: 74.63.218.202
- Proxy Status: **DNS Only (Gray Cloud)** - Required for Let's Encrypt
- TTL: Auto
**Propagation Verification:**
```bash
nslookup git.firefrostgaming.com
# Result: 74.63.218.202 ✓
```
**Propagation Time:** ~2 minutes
---
### 6. Frostwall (UFW) Configuration
**Initial State:** No firewall active (Phase 0 cleanup removed iptables)
**Issue:** UFW installation removed conflicting packages:
- iptables-persistent (removed)
- netfilter-persistent (removed)
**Firewall Rules Applied:**
```bash
# Global SSH protection (prevent lockout)
ufw allow 22/tcp
# Primary gateway protection (existing services)
ufw allow in on ens3 to 63.143.34.217
# Gitea HTTP (Let's Encrypt validation + redirect)
ufw allow in on ens3 to 74.63.218.202 port 80 proto tcp
# Gitea HTTPS (web interface)
ufw allow in on ens3 to 74.63.218.202 port 443 proto tcp
# Enable firewall
ufw --force enable
```
**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)
```
**Security Model:** IP-specific rules (not blanket 0.0.0.0 rules)
---
### 7. SSL Certificate Deployment
**Tool:** Certbot with Nginx plugin
**Certificate Obtained:**
- Domain: git.firefrostgaming.com
- Provider: Let's Encrypt
- Certificate: `/etc/letsencrypt/live/git.firefrostgaming.com/fullchain.pem`
- Private Key: `/etc/letsencrypt/live/git.firefrostgaming.com/privkey.pem`
- Expires: May 9, 2026
- Auto-renewal: Enabled (certbot.timer systemd unit)
**Certbot Actions:**
- Validated domain ownership via HTTP-01 challenge
- Generated certificate
- Automatically updated Nginx configuration
- Replaced self-signed cert with production certificate
- Configured HTTP→HTTPS redirect
**Email Registered:** mkrause612@gmail.com (renewal notifications)
---
### 8. Gitea Web Installation
**Installer Access:** https://git.firefrostgaming.com
**Permissions Issue:** Installer needed write access to `/etc/gitea/app.ini`
**Temporary Fix:**
```bash
chown gitea:gitea /etc/gitea
chown gitea:gitea /etc/gitea/app.ini
chmod 660 /etc/gitea/app.ini
```
**Configuration via Web UI:**
**Database:**
- Type: SQLite3
- Path: /var/lib/gitea/data/gitea.db
**General Settings:**
- Site Title: Firefrost Gaming - Git Repository
- Repository Root: /var/lib/gitea/repositories
- Git LFS Root: /var/lib/gitea/lfs
- Run As User: gitea
- Server Domain: git.firefrostgaming.com
- SSH Port: 2222
- HTTP Port: 3000
- Base URL: https://git.firefrostgaming.com/
**Security Settings:**
- Enable Local Mode: ✓ (no external CDN)
- Disable Gravatar: ✓ (privacy)
- Disable Self-Registration: ✓ (admin-only accounts)
- Require Sign-In to View Pages: ✓ (private repository)
- Enable OpenID Sign-In: ✓
- Password Hash Algorithm: pbkdf2
**Administrator Account:**
- Username: mkrause612
- Email: mkrause612@gmail.com
- Password: [Set during installation]
**Post-Install Lockdown:**
```bash
chmod 750 /etc/gitea
chmod 640 /etc/gitea/app.ini
systemctl restart gitea
```
---
### 9. Master Archive Creation
**Purpose:** Version-controlled storage of all infrastructure configurations
**Repository Location:** `/root/firefrost-master-configs`
**Folder Structure:**
```
firefrost-master-configs/
├── .gitignore # Protects sensitive files
├── README.md # Repository overview
├── docs/ # Documentation
│ ├── gitea-deployment.md
│ ├── gitea-technical-dossier.md
│ ├── gitea-user-guide.md
│ ├── workflow-guide.md
│ └── TECHNICAL_README.md
├── management/ # Management service configs
│ ├── app.ini.template # Sanitized Gitea config
│ └── gitea.service # Systemd service
├── nodes/ # Node configurations
│ └── 50-cloud-init.yaml # Netplan network config
├── security/ # Security configs (empty - future)
└── web/ # Web service configs
├── default # Nginx default (reference)
└── git.firefrostgaming.com # Gitea Nginx config
```
**Security Measures:**
**Sensitive File Protection (.gitignore):**
```gitignore
# Sensitive configuration files
management/app.ini
# Backup files
*.backup
*.bak
```
**Sanitized Template Created:**
- Original: `/etc/gitea/app.ini` (contains secrets)
- Template: `management/app.ini.template` (secrets replaced with placeholders)
- Placeholders: `REPLACE_WITH_GENERATED_*` for all secret keys
**Git Configuration:**
```bash
git config user.name "Michael Krause"
git config user.email "mkrause612@gmail.com"
git config pull.rebase false # Use merge strategy
git config credential.helper store # Cache credentials
```
**Commits Made:**
1. `655f6de` - Initial commit (configs)
2. `b01b9e0` - Gitea deployment documentation
3. `0511650` - TECHNICAL_README.md (via web)
4. `4f9d922` - Workflow guide
5. `e9745bb` - Merge commit (sync)
**Remote Repository:**
- URL: https://git.firefrostgaming.com/mkrause612/firefrost-phase0-configs
- Branch: master
- Status: Fully synced
**First Repository Created in Gitea:**
- Name: firefrost-phase0-configs
- Visibility: Private
- Purpose: Infrastructure configuration archive
- Status: Active with 5 commits
---
### 10. Documentation Created
**Technical Documentation (382 lines):**
- Service specifications
- Deployment changelog
- Frostwall rules
- Service management commands
- Backup procedures
- Troubleshooting guide
- Revision history
**User Guide for Beginners:**
- Git concepts explained (time machine analogy)
- Step-by-step instructions for non-technical users
- How to view files in Gitea
- How to download backups
- Understanding commits and history
- Common questions answered
**Workflow Guide (653 lines):**
- Roles and responsibilities (Michael vs Claude)
- Standard deployment workflow
- Micro-block command format
- Checkpoint protocol
- Error handling procedures
- Service-specific templates
- Emergency procedures
- Lessons learned from Gitea deployment
---
## Issues Encountered & Resolutions
### Issue 1: Nginx Port Binding Conflict
**Problem:** Nginx was listening on `0.0.0.0:80` instead of `74.63.218.202:80`
**Root Cause:** Default Nginx site (`/etc/nginx/sites-enabled/default`) was binding to all interfaces
**Resolution:**
```bash
rm /etc/nginx/sites-enabled/default
nginx -t # Test config
systemctl restart nginx # Full restart (reload wasn't enough)
```
**Lesson Learned:** Always check for default configs that bind to 0.0.0.0
---
### Issue 2: Inherited Socket Bindings
**Problem:** After reload, port 80 still showed `0.0.0.0` binding
**Root Cause:** Nginx error log showed "using inherited sockets from 5;6"
**Resolution:** Full `systemctl restart nginx` instead of `reload`
**Lesson Learned:** Major configuration changes (IP binding changes) require restart, not just reload
---
### Issue 3: Gitea Installer Permissions
**Problem:** Web installer failed with "permission denied" writing to `/etc/gitea/app.ini`
**Root Cause:** Configuration directory/file owned by root, installer runs as gitea user
**Resolution:**
```bash
# Temporary permissions for installation
chown gitea:gitea /etc/gitea
chown gitea:gitea /etc/gitea/app.ini
# Lock down after installation
chmod 750 /etc/gitea
chmod 640 /etc/gitea/app.ini
```
**Lesson Learned:** Web installers need temporary write access, must be locked down post-install
---
### Issue 4: Self-Signed Certificate Missing
**Problem:** Nginx failed to start - self-signed certificate didn't exist
**Root Cause:** Ubuntu 22.04 doesn't include default self-signed cert
**Resolution:**
```bash
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/ssl-cert-snakeoil.key \
-out /etc/ssl/certs/ssl-cert-snakeoil.pem \
-subj "/CN=git.firefrostgaming.com"
```
**Lesson Learned:** Generate temporary self-signed cert before Let's Encrypt
---
### Issue 5: Git Push Rejected (Divergent Branches)
**Problem:** `git push` failed - "remote contains work that you do not have locally"
**Root Cause:** Changes made via Gitea web interface not present in local repository
**Resolution:**
```bash
git config pull.rebase false # Configure merge strategy
git pull origin master # Download and merge remote changes
git push # Push merged result
```
**Lesson Learned:** Always pull before push if working from multiple locations
---
### Issue 6: Repeated Password Prompts
**Problem:** Git asking for username/password on every push/pull
**Root Cause:** Credential caching not configured
**Resolution:**
```bash
git config credential.helper store
git pull # Enter password one last time - Git saves it
# Future operations use cached credentials
```
**Lesson Learned:** Configure credential helper early in workflow
---
## Verification & Testing Results
### Service Health Checks
**Gitea Service:**
```bash
systemctl status gitea
# Result: active (running) ✓
```
**Nginx Service:**
```bash
systemctl status nginx
# Result: active (running) ✓
```
**Port Bindings:**
```bash
ss -tlnp | grep 74.63.218.202
# Result:
# 74.63.218.202:80 (nginx) ✓
# 74.63.218.202:443 (nginx) ✓
```
**Internal Gitea:**
```bash
ss -tlnp | grep :3000
# Result: 127.0.0.1:3000 (gitea) ✓
```
### Network Connectivity
**DNS Resolution:**
```bash
nslookup git.firefrostgaming.com
# Result: 74.63.218.202 ✓
```
**HTTPS Access:**
```bash
curl -I https://git.firefrostgaming.com
# Result: HTTP/2 200 ✓
```
**SSL Certificate:**
```bash
openssl s_client -connect git.firefrostgaming.com:443 -servername git.firefrostgaming.com
# Result: CN=git.firefrostgaming.com ✓
# Expiration: May 9, 2026 ✓
```
### Firewall Verification
**Rules Active:**
```bash
ufw status numbered | grep 74.63.218.202
# Result:
# [3] 74.63.218.202 80/tcp on ens3 ALLOW IN ✓
# [4] 74.63.218.202 443/tcp on ens3 ALLOW IN ✓
```
### Functional Testing
**Repository Creation:** ✅ Created `firefrost-phase0-configs`
**File Upload:** ✅ Uploaded configs via Git push
**Web Access:** ✅ Accessible at https://git.firefrostgaming.com
**Authentication:** ✅ Login working with mkrause612 account
**Git Operations:** ✅ Clone, push, pull all working
**SSL Encryption:** ✅ HTTPS active with valid certificate
---
## Security Posture
### Application Layer
- ✅ Public registration disabled (admin-only account creation)
- ✅ Sign-in required to view (no public browsing)
- ✅ Gravatar disabled (no external service calls)
- ✅ Local mode enabled (all assets served locally)
- ✅ Strong password hashing (pbkdf2)
- ✅ Hidden email domain configured (noreply.git.firefrostgaming.com)
### Network Layer
- ✅ Gitea bound to localhost only (127.0.0.1:3000)
- ✅ All external access via Nginx reverse proxy
- ✅ IP-specific firewall rules (not blanket 0.0.0.0)
- ✅ Primary gateway unchanged (63.143.34.217 protected)
- ✅ SSL/TLS encryption on all external connections
### File System
- ✅ Service runs as non-root user (gitea:gitea)
- ✅ Configuration locked down (640 permissions)
- ✅ Sensitive files excluded from Git (.gitignore)
- ✅ Sanitized templates created for sharing
### Secrets Management
**Protected Secrets (NOT in Git):**
- `SECRET_KEY` - Application secret
- `INTERNAL_TOKEN` - API authentication
- `LFS_JWT_SECRET` - LFS authentication
- `JWT_SECRET` - OAuth2 token signing
**Public Template (IN Git):**
- `app.ini.template` with placeholders
- Safe to share/reference
---
## Phase 0.5 Progress
### IP Allocation Status
| IP Address | Service | Status | Subdomain |
|------------|---------|--------|-----------|
| 74.63.218.202 | Gitea | ✅ DEPLOYED | git.firefrostgaming.com |
| 74.63.218.203 | Uptime Kuma | ⏳ PLANNED | status.firefrostgaming.com |
| 74.63.218.204 | BookStack | ⏳ PLANNED | docs.firefrostgaming.com |
| 74.63.218.205 | Netdata | ⏳ PLANNED | metrics.firefrostgaming.com |
| 74.63.218.206 | Vaultwarden | ⏳ PLANNED | vault.firefrostgaming.com |
### Service Deployment Progress
**Completed: 1/5 (20%)**
- ✅ Gitea (Version Control)
**Remaining: 4/5 (80%)**
- ⏳ Uptime Kuma (Monitoring)
- ⏳ BookStack (Documentation)
- ⏳ Netdata (Metrics)
- ⏳ Vaultwarden (Secrets)
---
## Files Modified/Created
### System Configuration Files
**Created:**
- `/usr/local/bin/gitea` (binary)
- `/etc/systemd/system/gitea.service`
- `/etc/gitea/app.ini`
- `/etc/nginx/sites-available/git.firefrostgaming.com`
- `/etc/letsencrypt/live/git.firefrostgaming.com/*` (SSL certs)
**Modified:**
- `/etc/nginx/sites-enabled/` (removed default)
- UFW rules database
**Directories Created:**
- `/var/lib/gitea/{custom,data,log,repositories,lfs}`
- `/etc/gitea/`
- `/root/firefrost-master-configs/{docs,management,nodes,security,web}`
### Git Repository Files
**In firefrost-phase0-configs repository:**
- `.gitignore`
- `README.md`
- `docs/gitea-deployment.md`
- `docs/gitea-technical-dossier.md`
- `docs/gitea-user-guide.md`
- `docs/workflow-guide.md`
- `docs/TECHNICAL_README.md`
- `management/app.ini.template`
- `management/gitea.service`
- `nodes/50-cloud-init.yaml`
- `web/default`
- `web/git.firefrostgaming.com`
---
## Lessons Learned
### What Worked Well
1. **Micro-block command format** - Small, focused command blocks made execution easier for accessibility needs
2. **Complete file paste** - Pasting entire config files vs line-by-line edits reduced errors
3. **IP isolation strategy** - Dedicated IP per service simplifies troubleshooting and security
4. **Checkpoint system** - Pausing for verification prevented cascading issues
5. **Sanitized templates** - Creating .gitignore and templates protected sensitive data
6. **Documentation-first approach** - Writing guides during deployment captured context
### Process Improvements for Next Service
1. **Check for default configs early** - Look for 0.0.0.0 bindings before configuring new services
2. **Use restart instead of reload** - For major config changes (IP bindings, site additions)
3. **Generate self-signed cert first** - Before attempting Let's Encrypt
4. **Configure Git credentials early** - Set up credential.helper at start of session
5. **Document as you go** - Don't wait until end to write documentation
### Carry Forward to Service 2
- ✅ Micro-block format confirmed effective
- ✅ IP isolation model validated
- ✅ UFW is now standard (replaced iptables from Phase 0)
- ✅ Full restart philosophy for major changes
- ✅ Git workflow established
- ✅ Security-first mindset maintained
---
## Next Steps
### Immediate (Next Session)
1. **Deploy Service 2: Uptime Kuma** on 74.63.218.203
- Service monitoring dashboard
- Will monitor Gitea + other infrastructure
- Similar deployment pattern to Gitea
2. **Update workflow guide** with any new lessons from Uptime Kuma deployment
3. **Establish monitoring baselines** for existing services
### Short-Term (This Week)
4. **Deploy Service 3: BookStack** on 74.63.218.204
- Internal documentation wiki
- Store operational procedures
- Reference architecture diagrams
5. **Deploy Service 4: Netdata** on 74.63.218.205
- Real-time performance monitoring
- Resource usage tracking
- Alert configuration
6. **Deploy Service 5: Vaultwarden** on 74.63.218.206
- Password/secret management
- Team credential sharing
- Emergency access procedures
### Long-Term (Post Phase 0.5)
7. **Phase 1: Frostwall Protocol** - Rebuild secure tunnel architecture on vanilla baseline
8. **Automated backups** - Schedule regular config/database backups
9. **Monitoring integration** - Connect all services to Uptime Kuma
10. **Documentation consolidation** - Migrate docs to BookStack
---
## Acknowledgments
**Collaboration Model:**
- Michael (The Operator) - Execution and decision authority
- Claude "The Wizard" (The Architect) - Design and guidance
**Workflow Success Factors:**
- Clear role separation (execute vs design)
- Micro-block accessibility format
- Checkpoint-driven verification
- Security-first mindset
- Comprehensive documentation
**Special Notes:**
- Hand surgery accommodations successfully integrated
- Git credential caching resolved repeated password prompts
- Master Archive establishes foundation for all future work
---
## Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| **1.0** | 2026-02-08 | Michael & Claude | Session summary for Gitea deployment (Service 1/5). Complete technical changelog, issue resolutions, and lessons learned. |
---
**END OF SESSION SUMMARY**
**Status:** Phase 0.5 Service 1 (Gitea) - ✅ 100% COMPLETE
**Next Service:** Uptime Kuma (74.63.218.203) - status.firefrostgaming.com
**Progress:** 20% (1/5 services deployed)
**The Wizard & Michael: Building Firefrost Infrastructure, One Service at a Time** 🧙‍♂️⚡