ulises-c · ulises-c · May 20, 2026 · May 20, 2026 · May 20, 2026 · May 20, 2026
diff --git a/linux-server/README.md b/linux-server/README.md
@@ -263,18 +263,34 @@ In NPM admin (`http://<server-ip>:81`):
    6. Point your router's DNS (or individual devices) to `<server-ip>` to start filtering
    7. Add credentials to `linux-server/homepage/.env` to enable the stats widget on Homepage
 
-15. pi-hole | [GitHub](https://github.com/pi-hole/pi-hole) | [Docs](https://docs.pi-hole.net)
+15. forgejo | [Codeberg](https://codeberg.org/forgejo/forgejo) | [Docs](https://forgejo.org/docs/)
+    1. Lightweight self-hosted git service — GitHub-like web UI, SSH push/pull, repo mirroring; LAN/Tailscale only, no public exposure
+    2. Deploy:
+       ```sh
+       cd linux-server/forgejo
+       cp .env.example .env   # set FORGEJO_DOMAIN to your Tailscale hostname; optionally set FORGEJO_DATA_PATH for external drive
+       docker compose up -d
+       ```
+    3. Web UI at `http://<server-ip>:3300` — complete the setup wizard on first visit, create admin account
+    4. Git over SSH on port `2222`:
+       ```sh
+       git clone ssh://git@<tailscale-hostname>:2222/<username>/<repo>.git
+       ```
+    5. Add your SSH public key in **Settings → SSH / GPG Keys** after creating your account
+    6. To migrate from GitHub: use Forgejo's built-in migration (**+ → New Migration → GitHub**), then optionally configure a push mirror back to GitHub under repo **Settings → Push Mirrors** while validating the setup
+
+16. pi-hole | [GitHub](https://github.com/pi-hole/pi-hole) | [Docs](https://docs.pi-hole.net)
     1. Network-wide DNS ad blocker — alternative to AdGuard Home
     2. Not yet configured
 
-16. Immich | [GitHub](https://github.com/immich-app/immich) | [Docs](https://immich.app/docs)
+17. Immich | [GitHub](https://github.com/immich-app/immich) | [Docs](https://immich.app/docs)
     1. Self-hosted photo and video backup — Google Photos alternative with mobile apps, face recognition, and timeline view
     2. Not yet configured
 
-17. Jellyfin | [GitHub](https://github.com/jellyfin/jellyfin) | [Docs](https://jellyfin.org/docs/)
+18. Jellyfin | [GitHub](https://github.com/jellyfin/jellyfin) | [Docs](https://jellyfin.org/docs/)
     1. Self-hosted media server — stream your own movies, TV shows, and music to any device
     2. Not yet configured
 
-18. Home Assistant | [GitHub](https://github.com/home-assistant/core) | [Docs](https://www.home-assistant.io/docs/)
+19. Home Assistant | [GitHub](https://github.com/home-assistant/core) | [Docs](https://www.home-assistant.io/docs/)
     1. Open source smart home hub — integrates with thousands of devices and services
     2. Not yet configured
diff --git a/linux-server/forgejo/.env.example b/linux-server/forgejo/.env.example
@@ -0,0 +1,12 @@
+# Copy this file to .env and update the values.
+
+# Tailscale hostname — shown in clone URLs in the Forgejo web UI
+# Run: tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'
+FORGEJO_DOMAIN=<hostname>.<tailnet>.ts.net
+
+# Where to store repositories and Forgejo config.
+# Default: ./data (same directory as docker-compose.yml)
+# External drive example: FORGEJO_DATA_PATH=/mnt/external/forgejo
+FORGEJO_DATA_PATH=./data
+
+TZ=America/Los_Angeles
diff --git a/linux-server/forgejo/docker-compose.yml b/linux-server/forgejo/docker-compose.yml
@@ -0,0 +1,25 @@
+services:
+  forgejo:
+    # Pin to a major version tag to avoid surprise upgrades — check latest at:
+    # https://codeberg.org/forgejo/forgejo/releases
+    image: codeberg.org/forgejo/forgejo:15
+    container_name: forgejo
+    restart: unless-stopped
+    environment:
+      - USER_UID=1000
+      - USER_GID=1000
+      - TZ=${TZ:-America/Los_Angeles}
+      - FORGEJO__database__DB_TYPE=sqlite3
+      - FORGEJO__server__ROOT_URL=http://${FORGEJO_DOMAIN}:3300
+      - FORGEJO__server__SSH_DOMAIN=${FORGEJO_DOMAIN}
+      - FORGEJO__server__SSH_PORT=2222
+    ports:
+      - "3300:3000"   # web UI
+      - "2222:22"     # git over SSH
+    volumes:
+      - ${FORGEJO_DATA_PATH:-./data}:/data
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
diff --git a/linux-server/homepage/.env.example b/linux-server/homepage/.env.example
@@ -18,6 +18,10 @@ HOMEPAGE_VAR_ADGUARD_PASS=
 # Syncthing — API key from web UI → Actions → Settings → API Key
 HOMEPAGE_VAR_SYNCTHING_KEY=
 
+# Forgejo — same Tailscale hostname as TAILSCALE_HOSTNAME; API token from Forgejo → Settings → Applications
+HOMEPAGE_VAR_FORGEJO_DOMAIN=
+HOMEPAGE_VAR_FORGEJO_TOKEN=
+
 # Server hostname — used to build HOMEPAGE_ALLOWED_HOSTS in docker-compose.yml
 HOSTNAME=ollie-server
 # Server LAN IP — used in HOMEPAGE_ALLOWED_HOSTS to allow direct IP access

diff --git a/linux-server/homepage/config/services.yaml b/linux-server/homepage/config/services.yaml
@@ -94,6 +94,18 @@
         server: my-docker
         container: ntfy
 
+- Dev:
+    - forgejo:
+        icon: si-forgejo
+        href: http://{{HOMEPAGE_VAR_FORGEJO_DOMAIN}}:3300
+        description: Self-hosted git
+        server: my-docker
+        container: forgejo
+        widget:
+          type: gitea
+          url: http://localhost:3300
+          key: "{{HOMEPAGE_VAR_FORGEJO_TOKEN}}"
+
 - Storage:
     - syncthing:
         icon: si-syncthing

diff --git a/linux-server/post-install.md b/linux-server/post-install.md
@@ -127,6 +127,68 @@ The Homepage Tailscale widget uses a local OAuth proxy to avoid 90-day key rotat
   - Create admin credentials — then add them to `homepage/.env`
 - [ ] Point your router's DNS to `<server-ip>` for network-wide filtering
 
+### Forgejo — http://\<server-ip\>:3300
+
+- [ ] Copy and edit the env file:
+  ```sh
+  cd linux-server/forgejo && cp .env.example .env
+  # Set FORGEJO_DOMAIN to your Tailscale hostname
+  # Optionally set FORGEJO_DATA_PATH to an external drive path
+  ```
+- [ ] Start Forgejo:
+  ```sh
+  docker compose up -d
+  ```
+- [ ] Open `http://<server-ip>:3300` and complete the setup wizard:
+  - Database: SQLite (pre-set)
+  - SSH server domain and port: pre-filled from `.env` — verify they look correct
+  - Application URL: should match `http://<tailscale-hostname>:3300`
+  - Create the admin account at the bottom of the wizard page
+- [ ] Generate a personal access token for the Homepage widget:
+  - Top-right avatar → **Settings → Applications → Generate Token** — scope: all (or read-only is enough for the widget)
+  - Add to `homepage/.env`:
+    - `HOMEPAGE_VAR_FORGEJO_TOKEN=<token>`
+    - `HOMEPAGE_VAR_FORGEJO_DOMAIN=<tailscale-hostname>`
+  - Restart Homepage: `cd linux-server/homepage && docker compose restart`
+- [ ] Add your SSH public key to Forgejo:
+  - **Settings → SSH / GPG Keys → Add Key** — paste `~/.ssh/id_ed25519.pub` (or your key from `create_ssh_key.sh`)
+
+#### Backup
+
+Everything Forgejo needs to restore from scratch lives in `FORGEJO_DATA_PATH` (default: `linux-server/forgejo/data/`). Back up this directory to recover repos, config, SSH host keys, and the SQLite database.
+
+| What | Path inside data dir | Notes |
+|---|---|---|
+| Git repositories | `gitea/repositories/` | The actual repo data |
+| SQLite database | `gitea/forgejo.db` | Users, issues, settings |
+| Config | `gitea/conf/app.ini` | Generated by setup wizard |
+| SSH host keys | `gitea/conf/` (`*.rsa`, `*.ed25519`, etc.) | **Critical** — if lost, all clients get MITM warnings |
+
+> Hot backups of the SQLite database are safe with Forgejo — it uses WAL mode. A simple `cp` or `rsync` of the data directory while Forgejo is running is sufficient.
+
+#### Cloning / remotes from Mac
+
+```sh
+# SSH clone (use this for all git operations on Mac)
+git clone ssh://git@<tailscale-hostname>:2222/<username>/<repo>.git
+
+# Set as remote on an existing repo
+git remote set-url origin ssh://git@<tailscale-hostname>:2222/<username>/<repo>.git
+```
+
+#### Migrating an existing repo (e.g. Obsidian vault) from GitHub
+
+1. In Forgejo web UI: **+ → New Migration → GitHub** — imports history, branches, and tags
+2. On Mac, point the local repo at Forgejo:
+   ```sh
+   git remote set-url origin ssh://git@<tailscale-hostname>:2222/<username>/<repo>.git
+   ```
+3. Add GitHub as a push mirror for validation while you transition:
+   - In Forgejo: repo **Settings → Git Hooks → Push Mirrors → Add Push Mirror**
+   - Mirror URL: `https://<github-username>:<github-pat>@github.com/<username>/<repo>.git`
+   - Interval: `24h` (or `0` to push only on demand)
+   - When you're satisfied with Forgejo, delete the mirror and archive the GitHub repo
+
 ### Syncthing — http://\<server-ip\>:8384
 - [ ] Add volume mounts to `linux-server/syncthing/docker-compose.yml` for each folder to sync, then restart:
   ```sh
@@ -154,3 +216,4 @@ The Homepage Tailscale widget uses a local OAuth proxy to avoid 90-day key rotat
 | Cockpit | https://\<server-ip\>:9090 | |
 | Tailscale Web UI | http://localhost:8088 | After `tailscale up` |
 | Tailscale proxy | http://localhost:8089 | Internal — used by Homepage widget |
+| Forgejo | http://\<server-ip\>:3300 | Git over SSH on port 2222 |