Forgejo is an open-source GitHub clone written in Go. I wanted to run Forgejo on an old Mac mini at home and make it remotely accessible through Tailscale. So, I built Forgejo Appliance: an opinionated blueprint based on an OrbStack VM running on macOS with Ubuntu Server, PostgreSQL and the tsbridge reverse proxy.

I think of Forgejo Appliance as an open-source black box. It makes the Forgejo service available through a web interface, but beyond that, it’s pretty opaque. The VM is designed to be ephemeral (torn down and rebuilt for updates). Internally, it’s a group of three server apps tied together with UNIX sockets. This avoids the DNS and security headaches of exposing local TCP/IP ports. Like a managed cloud app, you can’t even connect to it with SSH.

It wasn’t all fun and games. Navigating through the host and guest restrictions felt like threading a needle:

  - The macOS Security Framework restricts Keychain access to local shell sessions.
  - Let’s Encrypt has a strict rate limit for certificate requests, which makes tearing down and rebuilding ephemeral VMs difficult.
  - TLS certificates are usually managed as small directories of files. To persist them across ephemeral boots, I tar-ed, compressed, and base64-encoded the whole directory into a small string and stuffed it directly into Apple Keychain.
  - When testing isn’t going well, you can easily stack up ghost Tailscale nodes and trigger MagicDNS collisions.

Forgejo Appliance stores its secrets in Apple Keychain, uses Google Workspace SMTP for notifications, and uses BorgBackup with rsync.net for remote backups. The end result is secure (thank you, Tailscale) and reliable.