firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity
Files
475b4e2bb704eca06ff838da299a7aea418d7fdb
firefrost-operations-manual/docs/session-summary-gitea.md

21 KiB
Raw Blame History

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:

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:

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:

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

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:

Post-Install Lockdown:

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):

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

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:

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:

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:

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

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:

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:

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:

systemctl status gitea
# Result: active (running) ✓

Nginx Service:

systemctl status nginx
# Result: active (running) ✓

Port Bindings:

ss -tlnp | grep 74.63.218.202
# Result:
# 74.63.218.202:80  (nginx) ✓
# 74.63.218.202:443 (nginx) ✓

Internal Gitea:

ss -tlnp | grep :3000
# Result: 127.0.0.1:3000 (gitea) ✓

Network Connectivity

DNS Resolution:

nslookup git.firefrostgaming.com
# Result: 74.63.218.202 ✓

HTTPS Access:

curl -I https://git.firefrostgaming.com
# Result: HTTP/2 200 ✓

SSL Certificate:

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:

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)

  1. Deploy Service 3: BookStack on 74.63.218.204

    • Internal documentation wiki
    • Store operational procedures
    • Reference architecture diagrams

  2. Deploy Service 4: Netdata on 74.63.218.205

    • Real-time performance monitoring
    • Resource usage tracking
    • Alert configuration

  3. Deploy Service 5: Vaultwarden on 74.63.218.206

    • Password/secret management
    • Team credential sharing
    • Emergency access procedures

Long-Term (Post Phase 0.5)

  1. Phase 1: Frostwall Protocol - Rebuild secure tunnel architecture on vanilla baseline
  2. Automated backups - Schedule regular config/database backups
  3. Monitoring integration - Connect all services to Uptime Kuma
  4. 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 🧙‍♂️⚡

Reference in New Issue View Git Blame Copy Permalink