SOP-006 — Forgejo Deployment (Desktop POC & VPS)

1. Purpose

This Standard Operating Procedure documents the deployment, configuration, and operational management of Forgejo — the self-hosted Git platform that serves as Atlantis ITS's central repository and AI memory hub.

Forgejo replaced GitHub for internal/private repos as of April 18, 2026. GitHub is retained for public/open-source visibility.

2. Scope

In scope:

• Forgejo binary installation (no Docker)
• SQLite database configuration
• PM2 lifecycle management
• Initial repository creation
• Web installer walkthrough
• Git smoke test and credential caching
• Upgrade procedures
• Troubleshooting

Out of scope:

• VPS-specific networking (Cloudflare tunnel, reverse proxy) — see future SOP when VPS is live
• Docker-based Forgejo deployment
• PostgreSQL/MySQL backend migration
• CI/CD with Woodpecker (future phase)

3. Architecture

Client (browser / git CLI)
        ↓
http://localhost:3010 (Desktop POC)
  or https://forgejo.atlantisits.ai (future VPS)
        ↓
Forgejo v15.0.0 LTS (binary at ~/nova/services/forgejo)
        ↓
SQLite DB (~/nova/forgejo-data/forgejo.db)
        ↓
Repos (~/nova/forgejo-data/repos/)

Why Forgejo:

• Fully open source (Gitea fork, community-governed)
• Lightweight (~512MB RAM, SQLite backend)
• No corporate dependency (Microsoft owns GitHub)
• Central memory repo for AI squad
• Self-hosted = full data sovereignty

Why v15.0.0 LTS:

• v9.x reached end-of-life January 2025
• v15.0.0 is current LTS, supported through July 2027
• Override available: FORGEJO_VERSION=9.0.3 ./setup-forgejo.sh

4. File Locations

This respects the dual-workspace architecture from HT-012: ~/nova/ for runtime infrastructure, ~/atlantis/ for working project repos.

5. Prerequisites

• WSL2 Ubuntu running on Nova-Alpha (Trunks)
• PM2 installed globally (npm i -g pm2)
• wget installed (sudo apt-get install -y wget)
• Git installed (sudo apt-get install -y git)
• Port 3010 available

6. Installation

Step 0 — Place Bootstrap Files

mkdir -p ~/nova/bootstrap
# Copy setup-forgejo.sh and app.ini into ~/nova/bootstrap/
chmod +x ~/nova/bootstrap/setup-forgejo.sh

Step 1-3 — Run the Installer

cd ~/nova/bootstrap
./setup-forgejo.sh

The script is idempotent — safe to re-run. It will:

• Skip the download if the binary already exists
• Skip copying app.ini if one is already in place
• pm2 restart instead of duplicating the process

Expected output (tail):

==> Forgejo is responding on port 3010.

  Open in Windows browser:  http://localhost:3010

If it does not respond: pm2 logs forgejo --lines 80

Step 4 — Web Installer

Open http://localhost:3010/ in your Windows browser.

On the install screen, confirm these values (most are pre-filled from app.ini):

Expand Administrator Account Settings and create:

Click Install Forgejo. The process writes secrets back into app.ini and sets INSTALL_LOCK = true. Forgejo restarts itself; PM2 brings it back automatically.

Step 5 — Create Initial Repos

Sign in at http://localhost:3010/ as shane, then create repos via "+" → "New Repository":

1. atlantis-memory — private, initialized with README, default branch main
2. atlantis-ops — use "New Migration" → Git Source to mirror from GitHub
3. atlantis-job-engine — same migration flow

For GitHub mirrors of private repos: generate a GitHub Personal Access Token with repo scope, paste as auth password during migration.

Step 6 — Git Smoke Test

mkdir -p ~/atlantis && cd ~/atlantis
git clone http://localhost:3010/shane/atlantis-memory.git
cd atlantis-memory
echo "# Atlantis AI Memory" > ATLANTIS_AI_MEMORY.md
git add ATLANTIS_AI_MEMORY.md
git commit -m "Initial memory file"
git push origin main

To avoid password prompts:

git config --global credential.helper "cache --timeout=28800"

7. Configuration Reference (app.ini)

Key settings in the live config at ~/nova/forgejo-data/app.ini:

Do not open port 3010 on Windows firewall or router until VPS Phase 2. The Desktop POC is for local use only.

8. PM2 Operations

pm2 status                          # see forgejo alongside other services
pm2 logs forgejo --lines 100        # tail logs
pm2 restart forgejo                 # restart on config change
pm2 stop forgejo                    # stop without removing
pm2 delete forgejo                  # remove from PM2
pm2 save                            # persist process list for WSL boot

Existing pm2 startup configuration (from SOP-004) brings Forgejo back when WSL starts.

Current PM2 process list (expected):

9. Upgrade Procedure

cd ~/nova/services/
FORGEJO_VERSION=15.0.1   # new version number
wget "https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}/forgejo-${FORGEJO_VERSION}-linux-amd64" \
  -O "forgejo-${FORGEJO_VERSION}"
chmod +x "forgejo-${FORGEJO_VERSION}"
ln -sfn "forgejo-${FORGEJO_VERSION}" forgejo
pm2 restart forgejo

Before any major upgrade (v15 → v16, etc.):

1. Back up the database: cp ~/nova/forgejo-data/forgejo.db ~/nova/forgejo-data/forgejo.db.bak
2. Back up repos: tar czf ~/atlantis/backups/forgejo-repos-$(date +%Y%m%d).tar.gz ~/nova/forgejo-data/repos/
3. Read the release notes for breaking changes
4. Upgrade, test, then pm2 save

10. Troubleshooting

11. Security Considerations

The Desktop POC is hardened for local use:

• OFFLINE_MODE = true — no external network calls
• DISABLE_REGISTRATION = true — only admin can create accounts
• REQUIRE_SIGNIN_VIEW = true — anonymous users see nothing
• Port 3010 is NOT exposed to Windows firewall or router

Before VPS deployment (Phase 2):

• Add HTTPS via Cloudflare tunnel or reverse proxy (nginx/caddy)
• Generate proper SSH keys for agent access (see HT-012)
• Consider token-based API access for automated agent pulls
• Run Red/Blue Team scan against Forgejo instance (see SOP for Red/Blue Team when available)

12. VPS Migration Plan

When the VPS goes live (target: first week of May 2026):

1. Install Forgejo on VPS using same setup-forgejo.sh (adjust paths)
2. Export repos from Desktop POC: git clone --mirror each repo
3. Import to VPS Forgejo instance
4. Update DNS: forgejo.atlantisits.ai → VPS IP via Cloudflare
5. Update all agent configs to point to VPS Forgejo URL
6. Desktop POC becomes fallback/development instance

13. Related Documents

• HT-012 — Nova Workspace Structure (~/nova/ vs ~/atlantis/ split)
• HT-013 — PM2 Process Manager
• SOP-005 — Nova-Alpha Desktop Build & Recovery
• HT-014 — Windows Service Management (pending)
• HT-015 — WSL ↔ Windows Bridge (pending)

14. Revision History

15. Approval

End of SOP-006 — Forgejo Deployment (Desktop POC & VPS)