Justinaquino: Added Forgejo Pages setup guide

2026-04-28T13:24:36Z

Added Forgejo Pages setup guide

New page

= Forgejo Pages — Complete Setup Guide =

<blockquote>**Wiki:** wiki.gi7b.org | **Last updated:** 2026-04-28</blockquote>
<blockquote>**Status:** Production — `pages.gi7b.org` live on PC03</blockquote>

----

== Overview ==

Forgejo does '''not''' have a built-in static site server. To serve Pages, you run a
separate <code>ronmi/forgejo-pages</code> container alongside Forgejo. It reads files from a
special branch in each repo via the Forgejo API and serves them over HTTP.

<syntaxhighlight>
Browser → Cloudflare DNS → NPM (SSL) → forgejo-pages:8080 → Forgejo API → repo branch
</syntaxhighlight>

* **Forgejo:** `https://git.gi7b.org` (container: `forgejo`, internal port 3000)
* **Pages server:** `https://pages.gi7b.org` (container: `forgejo-pages`, internal port 8080)
* **Routing:** path-based — `https://pages.gi7b.org/{owner}/{repo}/`
* **Branch name:** `static-pages` (exact, hardcoded default in this image)

----

== Gotchas — Read This First ==

=== 1. There is no built-in Pages in Forgejo ===
<code>ENABLE_FORGEJO_PAGES = true</code> in <code>app.ini</code> does nothing. It is not a real setting.
You need the external <code>ronmi/forgejo-pages</code> container.

=== 2. Branch must be named exactly `static-pages` ===
Not <code>gh-pages</code>, not <code>pages</code>, not <code>static_pages</code>. The image default is <code>static-pages</code>.
If the branch doesn't exist in the repo, the server returns 404.

=== 3. Use two separate tokens ===
{| class="wikitable"
! Token !! Scope !! Used by
|-
| `forgejo-pages` service token | `repository: read` | Docker container reads repo files via API
|-
| `git-push` personal token | `repository: read+write` + `user: read` | You/AI push code via git CLI
|}

Never use your account password for git CLI over HTTPS — it will be rejected.

=== 4. NPM forward port is the internal container port ===
When NPM uses the container DNS name (<code>forgejo-pages</code>), forward to port <code>8080</code> (internal).
If using the host IP (<code>192.168.196.76</code>), forward to port <code>8585</code> (exposed host port).
Mixing these up causes 502 Bad Gateway.

=== 5. Remove NPM Access List from git.gi7b.org ===
HTTP Basic Auth at the NPM layer blocks git CLI, API calls, and webhooks.
Forgejo's own auth (tokens, SSH keys, 2FA) is the correct security layer for a git host.

=== 6. SSH is more reliable than HTTPS for git push ===
HTTPS git auth has multiple failure modes (token scopes, credential helpers, NPM layers).
SSH just works. Set it up once per machine and never deal with tokens for pushing again.

----

== Docker Compose Setup ==

'''File:''' <code>/home/user/forgejo/compose.yml</code>

<syntaxhighlight lang="yaml">
services:
server:
image: codeberg.org/forgejo/forgejo:13
container_name: forgejo
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
volumes:
- ./data:/data
- /etc/localtime:/etc/localtime:ro
ports:
- "3001:3000"
- "223:22"
networks:
- internal
- proxy

pages:
image: ronmi/forgejo-pages
container_name: forgejo-pages
restart: unless-stopped
command: serve --server http://forgejo:3000 --token ${FORGEJO_PAGES_TOKEN} --bind :8080
ports:
- "8585:8080"
networks:
- internal
- proxy
depends_on:
- server

networks:
internal:
driver: bridge
proxy:
external: true
name: npm_proxy
</syntaxhighlight>

'''File:''' <code>/home/user/forgejo/.env</code>

<syntaxhighlight>
FORGEJO_PAGES_TOKEN=your_read_only_repository_token_here
</syntaxhighlight>

----

== Tokens ==

=== Service Token (for forgejo-pages container) ===
Generated in Forgejo → Settings → Applications:
* **Name:** `forgejo-pages-service`
* **Repository and Organization Access:** All
* **Permissions:** `repository: Read` only, everything else No access
* Goes in `/home/user/forgejo/.env` as `FORGEJO_PAGES_TOKEN`

=== Personal Push Token (for git CLI / AI agents) ===
Generated in Forgejo → Settings → Applications:
* **Name:** `git-push-{machinename}`
* **Repository and Organization Access:** All
* **Permissions:** `repository: Read and Write`, `user: Read`, everything else No access
* Used as the **password** when git prompts, or embedded in SSH-less workflows

----

== NPM Proxy Host — pages.gi7b.org ==

'''Details tab:'''
{| class="wikitable"
! Field !! Value
|-
| Domain Names | `pages.gi7b.org`
|-
| Scheme | `http`
|-
| Forward Hostname / IP | `forgejo-pages` (container name) OR `192.168.196.76` (host IP)
|-
| Forward Port | `8080` if using container name / `8585` if using host IP
|-
| Cache Assets | ✅ On
|-
| Block Common Exploits | ✅ On
|-
| Websockets Support | Off
|-
| Access List | **Publicly Accessible** (no HTTP Basic Auth)
|}

'''SSL tab:'''
{| class="wikitable"
! Field !! Value
|-
| SSL Certificate | `pages.gi7b.org` (Let's Encrypt)
|-
| Force SSL | ✅ On
|-
| HTTP/2 Support | ✅ On
|}

----

== SSH Setup for Git Push (per machine) ==

Run once on each machine that needs to push to Forgejo:

<syntaxhighlight lang="bash">
# Generate key
ssh-keygen -t ed25519 -C "{machinename}-git" -f ~/.ssh/id_ed25519 -N ""

# Show public key to add to Forgejo
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>

Add the public key in Forgejo → Settings → SSH / GPG Keys → Add Key.

Set remote URL to SSH (note custom port 223):

<syntaxhighlight lang="bash">
git remote set-url origin ssh://git@192.168.196.76:223/{owner}/{repo}.git
</syntaxhighlight>

<blockquote>Use the ZeroTier IP `192.168.196.76` directly — port 223 is not forwarded through</blockquote>
<blockquote>the public relay (PC06). SSH over ZeroTier is reliable for internal machines.</blockquote>
<blockquote>For external machines, either forward port 223 through PC06 or use HTTPS with a token.</blockquote>

----

== Publishing a Page (Repeatable Workflow) ==

=== New repo — first time ===

<syntaxhighlight lang="bash">
git clone ssh://git@192.168.196.76:223/{owner}/{repo}.git
cd {repo}

# Create orphan branch (no shared history with main)
git checkout --orphan static-pages
git rm -rf . 2>/dev/null || true

# Create your site
mkdir -p .
cat > index.html <<'EOF'
<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>My Page</title></head>
<body>
<h1>Hello from Forgejo Pages</h1>
</body>
</html>
EOF

git add .
git commit -m "Initial pages content"
git push -u origin static-pages
</syntaxhighlight>

Live immediately at: <code>https://pages.gi7b.org/{owner}/{repo}/</code>

=== Update existing pages ===

<syntaxhighlight lang="bash">
git checkout static-pages
# edit files
git add .
git commit -m "Update pages"
git push
</syntaxhighlight>

=== Via Forgejo Web UI (no git needed) ===

1. Open repo → click '''New File'''
2. Filename: <code>index.html</code>, add content
3. In commit section: select '''"Create a new branch"'''
4. Branch name: <code>static-pages</code>
5. Commit

----

== Verification ==

<syntaxhighlight lang="bash">
# Local test (on PC03)
curl -i http://localhost:8585/{owner}/{repo}/

# Expected: HTTP/1.1 200 OK + your HTML

# Check pages server logs
docker logs forgejo-pages --tail 20
</syntaxhighlight>

Browser: <code>https://pages.gi7b.org/{owner}/{repo}/</code> (trailing slash matters)

----

== Troubleshooting ==

{| class="wikitable"
! Symptom !! Cause !! Fix
|-
| 400 Bad Request | No valid owner/repo path in URL | URL must be `/{owner}/{repo}/`
|-
| 404 Not Found | `static-pages` branch missing or no `index.html` at root | Create branch, push `index.html` to root
|-
| 502 Bad Gateway | NPM port mismatch or container not on `npm_proxy` network | Check forward port (8080 internal / 8585 host). Verify: `docker network inspect npm_proxy \ | grep forgejo`
|-
| Auth failed (git push) | Wrong token scope or using account password | Use personal push token with `repository: write`. Use SSH instead.
|-
| SSH connection refused | Port 223 not reachable from external machine | Use ZeroTier IP for internal machines. Forward port via PC06 for external.
|-
| Pages container crash-looping | Missing `serve` command or bad token | Check `docker logs forgejo-pages`. Verify `.env` token is correct.
|-
| Stale content | Browser cache | Hard refresh (Ctrl+Shift+R) or test with `curl`
|}

Forgejo Pages - Revision history

Justinaquino: Added Forgejo Pages setup guide