From 1a0bc3dee4c2e961af3ea29d3b986f0e8eb4ac19 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Tue, 3 Feb 2026 16:12:41 -0600 Subject: [PATCH] Add Gitea self-hosted Git server (LXC 225) Deploy Gitea 1.22.6 on LXC 225 to enable self-hosted Git repositories with CI/CD capabilities via Gitea Actions, reducing dependency on GitHub and associated costs while maintaining GitHub Actions workflow compatibility. - LXC 225 (10.10.0.225) running Ubuntu 20.04 with PostgreSQL 12 - Public access via git.manticorum.com through NPM reverse proxy - Comprehensive documentation including setup, backup, and CI/CD guides - Gitea Actions enabled for GitHub Actions-compatible workflows - Git LFS, SSH access, and webhooks configured Co-Authored-By: Claude Sonnet 4.5 --- server-configs/README.md | 1 + server-configs/gitea/.env.example | 25 +++ server-configs/gitea/README.md | 298 ++++++++++++++++++++++++++++ server-configs/hosts.yml | 20 ++ server-configs/proxmox/lxc/225.conf | 12 ++ 5 files changed, 356 insertions(+) create mode 100644 server-configs/gitea/.env.example create mode 100644 server-configs/gitea/README.md create mode 100644 server-configs/proxmox/lxc/225.conf diff --git a/server-configs/README.md b/server-configs/README.md index ec9a06e..fd50855 100644 --- a/server-configs/README.md +++ b/server-configs/README.md @@ -84,6 +84,7 @@ server-configs/ | strat-database | Docker | 10.10.0.42 | Database services | | arr-stack | Docker | 10.10.0.221 | Sonarr/Radarr/etc. | | n8n | Docker | 10.10.0.210 | Workflow automation | +| gitea | LXC | 10.10.0.225 | Self-hosted Git server + CI/CD | | akamai | Docker | 172.237.147.99 | Public-facing services | | nobara-desktop | Local | - | Development workstation | diff --git a/server-configs/gitea/.env.example b/server-configs/gitea/.env.example new file mode 100644 index 0000000..d3dce6c --- /dev/null +++ b/server-configs/gitea/.env.example @@ -0,0 +1,25 @@ +# Gitea Database Configuration +# Copy this to .env and fill in actual values + +# PostgreSQL Database +DB_TYPE=postgres +DB_HOST=127.0.0.1:5432 +DB_NAME=gitea +DB_USER=gitea +DB_PASSWORD=your_database_password_here + +# Gitea Admin Account (initial setup) +ADMIN_USERNAME=cal +ADMIN_EMAIL=cal@manticorum.com +ADMIN_PASSWORD=your_admin_password_here + +# Server Configuration +GITEA_DOMAIN=git.manticorum.com +GITEA_ROOT_URL=https://git.manticorum.com/ +GITEA_SSH_DOMAIN=git.manticorum.com +GITEA_SSH_PORT=22 + +# Security (auto-generated during setup, stored in /etc/gitea/app.ini) +# SECRET_KEY= +# INTERNAL_TOKEN= +# JWT_SECRET= diff --git a/server-configs/gitea/README.md b/server-configs/gitea/README.md new file mode 100644 index 0000000..6147044 --- /dev/null +++ b/server-configs/gitea/README.md @@ -0,0 +1,298 @@ +# Gitea - Self-Hosted Git Server + +**LXC 225** | **10.10.0.225** | **git.manticorum.com** + +Self-hosted Git server with web UI, Git LFS support, and Gitea Actions for CI/CD pipelines. + +## Quick Info + +| Property | Value | +|----------|-------| +| **Type** | LXC Container (Proxmox) | +| **OS** | Ubuntu 20.04 LTS | +| **IP** | 10.10.0.225 | +| **Public URL** | https://git.manticorum.com | +| **Gitea Version** | 1.22.6 | +| **Database** | PostgreSQL 12 | +| **Reverse Proxy** | Nginx Proxy Manager (10.10.0.16) | + +## Container Specs + +- **VMID**: 225 +- **CPU**: 2 cores +- **RAM**: 2GB +- **Disk**: 20GB +- **Features**: Nesting enabled (for future Docker runner support) + +## Services + +### Gitea Web +- **Port**: 3000 (internal) +- **Service**: `gitea.service` +- **User**: `git` +- **Work Dir**: `/var/lib/gitea` +- **Config**: `/etc/gitea/app.ini` +- **Data**: `/var/lib/gitea/data` +- **Logs**: `/var/lib/gitea/log` + +### PostgreSQL +- **Version**: 12 +- **Port**: 5432 (localhost only) +- **Database**: `gitea` +- **User**: `gitea` +- **Service**: `postgresql` + +## Management + +### Access Container +```bash +ssh root@10.10.0.225 +# or via Proxmox +pct enter 225 +``` + +### Service Management +```bash +# Status +systemctl status gitea +systemctl status postgresql + +# Restart +systemctl restart gitea + +# Logs +journalctl -u gitea -f +``` + +### Database Access +```bash +# As postgres user +sudo -u postgres psql -d gitea + +# As gitea user (from container) +PGPASSWORD=gitea123 psql -U gitea -d gitea -h 127.0.0.1 +``` + +## Configuration + +### Main Config File +`/etc/gitea/app.ini` contains all Gitea settings: +- Database connection +- Server domain and URLs +- SSH settings +- LFS configuration +- OAuth2/JWT secrets +- Actions enabled + +**Permissions**: +- Owner: `root:git` +- Mode: `640` +- Directory: `750` on `/etc/gitea` + +### Admin Account +- **Username**: `cal` +- **Password**: Set during initial setup (change immediately!) +- **Email**: `cal@manticorum.com` + +### Features Enabled +- ✅ **Gitea Actions** - Built-in CI/CD (GitHub Actions compatible) +- ✅ **Git LFS** - Large file storage support +- ✅ **SSH Access** - Git over SSH on port 22 +- ✅ **Web UI** - Repository browser and management +- ✅ **Organizations** - Multi-user repository groups +- ✅ **Webhooks** - Integration with external services + +## Backup + +### What to Backup +1. **PostgreSQL database**: `gitea` database +2. **Repository data**: `/var/lib/gitea/data/gitea-repositories` +3. **Configuration**: `/etc/gitea/app.ini` +4. **Custom files**: `/var/lib/gitea/custom` (if any) + +### Backup Commands +```bash +# Database dump +sudo -u postgres pg_dump gitea > gitea-backup-$(date +%Y%m%d).sql + +# Full data directory +tar -czf gitea-data-$(date +%Y%m%d).tar.gz /var/lib/gitea + +# Config only +cp /etc/gitea/app.ini gitea-app-$(date +%Y%m%d).ini +``` + +### Restore +```bash +# Restore database +sudo -u postgres psql -d gitea < gitea-backup.sql + +# Restore data +tar -xzf gitea-data.tar.gz -C / +chown -R git:git /var/lib/gitea +``` + +## Upgrades + +### Upgrade Gitea +```bash +# Stop service +systemctl stop gitea + +# Backup current binary +cp /usr/local/bin/gitea /usr/local/bin/gitea.backup + +# Download new version +wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/VERSION/gitea-VERSION-linux-amd64 + +# Set permissions +chmod +x /usr/local/bin/gitea + +# Start service (will auto-migrate database) +systemctl start gitea + +# Check logs +journalctl -u gitea -f +``` + +### Check Version +```bash +/usr/local/bin/gitea --version +``` + +## Setting Up CI/CD with Gitea Actions + +Gitea Actions are enabled and ready to use. To set up a runner: + +### Option 1: Docker Runner (Recommended) +Since the LXC has nesting enabled, you can run a Docker-based Actions runner: + +```bash +# Install Docker in the LXC +curl -fsSL https://get.docker.com | sh + +# Run Gitea Actions runner +docker run -d \ + --name gitea-runner \ + --restart unless-stopped \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -e GITEA_INSTANCE_URL=https://git.manticorum.com \ + -e GITEA_RUNNER_REGISTRATION_TOKEN= \ + gitea/act_runner:latest +``` + +### Option 2: Separate Runner LXC +Create a dedicated LXC for running Actions with more isolation. + +### Using Actions +Create `.gitea/workflows/main.yml` in your repository: + +```yaml +name: CI +on: [push, pull_request] +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Run tests + run: | + npm install + npm test +``` + +## Adding Repositories + +### Via Web UI +1. Go to https://git.manticorum.com +2. Click "+" → "New Repository" +3. Fill in details and create + +### Via Command Line +```bash +# Add remote +git remote add homelab git@git.manticorum.com:cal/repo-name.git + +# Or HTTPS +git remote add homelab https://git.manticorum.com/cal/repo-name.git + +# Push +git push homelab main +``` + +### Migrate from GitHub +Gitea has built-in migration: +1. New Repository → "Migrate from GitHub" +2. Enter GitHub URL and token +3. Gitea will clone all commits, branches, tags + +## Integration with NPM + +Reverse proxy is configured on NPM (10.10.0.16): +- **Domain**: git.manticorum.com +- **Forward to**: 10.10.0.225:3000 +- **SSL**: Let's Encrypt +- **Websockets**: Enabled + +## Troubleshooting + +### Gitea won't start +```bash +# Check logs +journalctl -u gitea -n 50 + +# Common issues: +# - Permission on /etc/gitea/app.ini (should be 640, root:git) +# - PostgreSQL not running +# - Port 3000 already in use +``` + +### Can't connect to database +```bash +# Check PostgreSQL is running +systemctl status postgresql + +# Test connection +PGPASSWORD=gitea123 psql -U gitea -d gitea -h 127.0.0.1 -c "SELECT 1;" + +# Check pg_hba.conf allows md5 auth +cat /etc/postgresql/12/main/pg_hba.conf | grep md5 +``` + +### 502 Bad Gateway on web +```bash +# Check Gitea is listening +ss -tlnp | grep 3000 + +# Check NPM can reach container +curl http://10.10.0.225:3000 + +# Verify firewall rules (should allow from 10.10.0.0/24) +``` + +### Actions runner not working +- Ensure runner is registered in Gitea Admin → Actions → Runners +- Check runner logs: `docker logs gitea-runner` +- Verify GITEA_INSTANCE_URL is correct +- Ensure runner has network access to Gitea + +## Security Notes + +- Database password is stored in `/etc/gitea/app.ini` (secured with 640 permissions) +- SSH keys for Git access are stored per-user in Gitea database +- JWT secrets are auto-generated and stored in config +- LXC is unprivileged for better isolation +- PostgreSQL only listens on localhost + +## Related Documentation + +- [Official Gitea Docs](https://docs.gitea.io/) +- [Gitea Actions](https://docs.gitea.io/en-us/usage/actions/overview/) +- [Proxmox LXC Config](../proxmox/lxc/225.conf) +- [Networking Setup](../../networking/CONTEXT.md) + +## Deployment Date + +**Created**: 2026-02-03 +**By**: Claude Code (Proxmox Skill) +**Initial Version**: Gitea 1.22.6 on Ubuntu 20.04 diff --git a/server-configs/hosts.yml b/server-configs/hosts.yml index 9548ce0..0dec70c 100644 --- a/server-configs/hosts.yml +++ b/server-configs/hosts.yml @@ -134,6 +134,26 @@ hosts: services: - openclaw + # Gitea LXC (Proxmox) + gitea: + type: lxc + ssh_alias: gitea + ip: 10.10.0.225 + user: root + vmid: 225 + description: "Gitea self-hosted Git server with CI/CD" + url: https://git.manticorum.com + config_paths: + gitea: /etc/gitea + data: /var/lib/gitea + services: + - gitea + database: + type: postgresql + version: "12" + name: gitea + user: gitea + # Home Assistant VM (Proxmox) home-assistant: type: homeassistant diff --git a/server-configs/proxmox/lxc/225.conf b/server-configs/proxmox/lxc/225.conf new file mode 100644 index 0000000..7b92d71 --- /dev/null +++ b/server-configs/proxmox/lxc/225.conf @@ -0,0 +1,12 @@ +arch: amd64 +cores: 2 +features: nesting=1 +hostname: gitea +memory: 2048 +nameserver: 10.10.0.1 +net0: name=eth0,bridge=vmbr0,gw=10.10.0.1,hwaddr=96:85:25:C9:39:EA,ip=10.10.0.225/24,type=veth +onboot: 1 +ostype: ubuntu +rootfs: local-lvm:vm-225-disk-1,size=20G +swap: 512 +unprivileged: 1