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.