Skip to content
Greffon
Tutorial

Self-Host Forgejo with Greffon

Your code history is the one asset you cannot regenerate. Here is the honest setup for Forgejo, a lightweight Git forge, on a greffer you own.

GLGreffon Labs6 min read
~/blog/self-host-forgejo

A Git forge holds the full history of everything you build: branches, issues, reviews, the long tail of decisions that never made it into a commit message. It is worth asking whose servers that lives on. Forgejo is a lightweight, self-hostable forge (Git hosting, issues, and pull requests) that you can run on hardware you own. Greffon takes the fiddly parts (TLS, routing) off your plate so you can graft it and get to work.

Why own the forge

Forgejo is a community-run fork of Gitea: a single small Go binary that serves the Git protocol, a web UI, issues, and pull requests. It is light enough to run comfortably on a modest greffer, and the workflow will feel familiar to anyone who has used GitHub or Gitea. Grafting it onto your greffer means the repositories, the issue history, and the user accounts all sit on a machine you control rather than an account you rent.

Graft it from the catalog

On a greffer you do not hand-write a compose file or wire a reverse proxy. Pick Forgejo from the catalog and graft it onto your greffer. Greffon issues the certificate and routes the app, so the web UI comes up reachable over HTTPS without you assembling that plumbing by hand. On first start Forgejo walks you through creating the initial administrator account.

Create the admin account before anyone else can
Forgejo's first-run installer lets the first visitor register and, if you leave registration open, claim the admin account. Open the web UI yourself right after grafting it, create your admin user, then turn off open registration in the admin settings so the forge is not left wide open on the internet.

Reach it, and Git over SSH

On the same network as your greffer the web UI works the moment it starts. To reach it from anywhere else you have two honest options. The simplest is tunnel mode: a greffer connects outbound to the manager's tunnel and serves its apps without opening a single inbound port, which is the answer for a box behind NAT or CGNAT with no public IP. If you would rather expose the greffer directly, port forwarding plus dynamic DNS still works. Either way the web UI and HTTPS Git remotes stay reachable.

The real wrinkle with a forge is Git over SSH. Cloning and pushing overhttps:// works the moment the web UI is reachable, since it rides the same HTTPS that Greffon already routes. SSH remotes (git@your-forge:org/repo.git) are a separate TCP channel on their own port, and you have to make that port reachable yourself: directly on a greffer with a public IP, or over the tunnel, which carries TCP as well as HTTP. If SSH remotes are not set up, HTTPS clone and push still cover the everyday workflow.

UDP is the one thing the tunnel will not carry
The Stem tunnel carries HTTP and TCP, which is everything Forgejo needs (web UI, HTTPS Git, and SSH Git are all TCP). It does not carry UDP yet, but Forgejo has no UDP data plane, so this does not affect the forge. It is only worth knowing if you later add a UDP app to the same greffer.

Storage and memory grow with you

Forgejo itself is small, but a forge is only as light as the repositories in it. Large binaries, long histories, and CI artifacts accumulate, and the disk is what fills up over time, not the application. Before you migrate a big monorepo or years of history, check that the greffer has the headroom, and keep an eye on disk use as the forge gets real traffic. Memory stays modest for normal browsing and Git operations.

Mirroring is a low-risk way to start
If you are unsure about committing fully, set up a few repositories as pull mirrors of an existing host first. You get a real copy on your own greffer, see how much disk it actually uses, and keep the original as a fallback while you decide.

Back it up first

Your code history is the asset you cannot regenerate from anywhere else, so decide how you back it up before it holds anything you care about. Greffon handles TLS and routing today, and native one-click backups are coming in M2. Until then, bring your own backup tool (restic or borgbackup are the usual choices), back up the Forgejo data on a schedule, and store a copy off the greffer.

A backup you have not restored is not a backup
Forgejo's state is the repository data on disk plus its database. Back up both together so a restore is consistent, and actually run a test restore once before you trust it. A forge you have never restored is a single point of failure for every project on it.

Keep it always-on

A forge that your team, your CI, or your other machines push to has to be up when they reach for it. Run it on an always-on greffer, a small VPS, a mini-PC, or a free Oracle Cloud box, rather than a laptop that sleeps at night. The Oracle walkthrough is a good place to get a greffer running before you graft the forge onto it.

FAQ

Is Forgejo the same as Gitea?
They share a common ancestor. Forgejo is a community-governed fork of Gitea, so the day-to-day experience is very close: Git hosting, issues, and pull requests in a single lightweight Go binary. The clients and Git workflow you already use work unchanged.
Can I clone and push without setting up SSH?
Yes. HTTPS remotes work as soon as the web UI is reachable, since they ride the same HTTPS that Greffon routes. SSH remotes are a separate TCP port you make reachable yourself; until then, HTTPS clone and push cover the everyday workflow.
Will the built-in tunnel work for Git over SSH?
The tunnel carries TCP as well as HTTP, so it can carry SSH Git on its own port. The only thing it does not carry yet is UDP, and Forgejo has no UDP data plane, so the forge is fully covered.
Can I send notification emails?
Yes. The Forgejo greffon exposes SMTP configuration, so you can point it at a mail provider to send issue and pull request notifications. It is optional; the forge runs fine without mail configured.
What happens if my greffer goes down?
Pushes and the web UI are unavailable until it is back, and any CI that pulls from it stalls. Local clones keep your code, but the shared history and issues live on the greffer, which is why you keep it on an always-on machine with backups you have tested.
GL
Greffon Labs
We build Greffon, the simplest way to turn any machine into a server you own.
Forgejo is in the catalog.Graft it onto a greffer you own in one click. No YAML, no reverse-proxy config.

Keep reading

~/blog/self-host-activepieces
Tutorial

Self-Host Activepieces with Greffon

A no-code automation builder is glue between every account you have. Running it on a greffer you own keeps those connection secrets off a vendor's servers.

~/blog/self-host-excalidraw
Tutorial

Self-Host Excalidraw with Greffon

A whiteboard for sketching diagrams, on a box you own. Grafts onto a greffer in minutes. The honest catch: drawings live in your browser, not the server.

Ready to turn on your greffer?

Install in minutes. Deploy each app in seconds. Your server, your apps.

Read the docs