How to Install Forgejo on Debian: A Self-Hosted Lightweight Git Forge

Forgejo is a self-hosted, lightweight software forge: Git hosting, issues, pull requests, a wiki, releases, a package registry and Forgejo Actions for CI, all from a single Go binary. It is a community-governed fork of Gitea, maintained by the people at Codeberg, and it is designed to run comfortably on hardware as modest as a small VPS or a home server.

If you want the workflow of a hosted Git service without handing your code to a third party, Forgejo is one of the most approachable options. It has no heavyweight dependency stack, works with SQLite out of the box for small instances, and scales up to PostgreSQL or MySQL when you need it.

Forgejo is not part of the official Debian repositories, and its releases move faster than a stable distribution can follow. The unofficial deb.griffo.io repository provides an up-to-date, prebuilt forgejo package, so you install and update the forge with plain apt instead of downloading binaries by hand.

Install the Latest Forgejo on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest Forgejo .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install forgejo

The rest of this guide explains what each command does, how to verify the install, how to keep Forgejo up to date, and what to check when something goes wrong.

What Makes Forgejo Special?

• 🔧 Single binary - The entire forge ships as one self-contained Go executable
• 🪶 Lightweight - Runs happily on a Raspberry Pi or a 1 GB VPS
• 🔀 Pull requests and code review - Full merge workflow with reviews and protected branches
• 🎬 Forgejo Actions - Built-in CI/CD that is compatible with the GitHub Actions ecosystem
• 📦 Package registry - Host Docker, npm, PyPI, Cargo, Maven and more alongside your code
• 🗄️ Flexible databases - SQLite for small setups, PostgreSQL or MySQL for larger ones
• 🌐 Federation-minded - A community-run project actively working on forge federation
• 🛡️ Self-hosted and private - Your repositories, issues and users stay on your infrastructure

Why Use the deb.griffo.io Repository?

• Easy installation and updates through the APT package manager
• Automatic dependency management handled by Debian packaging
• Always tracks upstream releases so security fixes reach you promptly
• No compiling from source and no manual binary placement
• Works across supported Debian releases (Bookworm, Trixie and Sid)

Prerequisites

Before you begin, make sure you have:

• A Debian-based system (Bookworm 12, Trixie 13, or Sid)
• sudo privileges
• curl installed (sudo apt install curl if needed)
• Git installed (sudo apt install git)
• Optionally, PostgreSQL if you intend to use it instead of SQLite

Step 1: Add the deb.griffo.io Repository

Add the signing key and the repository to APT:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

Step by step:

1. Keyrings directory - Creates /etc/apt/keyrings with correct permissions for third-party keys.
2. GPG key - Downloads the key and stores it de-armoured for signature verification.
3. Repository entry - Adds the source pinned to that key, with your Debian codename filled in by lsb_release -sc.
4. Update - Refreshes the index so the package is visible.

Step 2: Update the Package List

If you skipped the last command above, run:

sudo apt update

Step 3: Install Forgejo

Install the package:

sudo apt install forgejo

The package installs the forgejo binary, creates a dedicated forgejo system user, lays down the working directory under /var/lib/forgejo, and installs a systemd service unit.

Step 4: Verify the Installation

Confirm the binary and check the version:

forgejo --version

You should see output similar to:

Forgejo version 11.0.1+gitea-1.22.0 (built with go1.23.4)

Getting Started with Forgejo

Installing the package gives you the software; you still need to start the service and walk through the one-time web configuration.

Start and Enable the Service

Enable Forgejo so it starts at boot, and start it now:

sudo systemctl enable --now forgejo
sudo systemctl status forgejo

By default Forgejo listens on port 3000. Check the logs if it does not come up:

sudo journalctl -u forgejo -f

Run the Initial Web Setup

Open http://your-server-ip:3000/ in a browser. On first launch Forgejo shows the installation page where you configure the essentials:

• Database - Choose SQLite for a simple single-user or small-team instance, or point at PostgreSQL/MySQL for larger deployments.
• Site title and base URL - Set the public URL you will access the forge on.
• Data paths - The package defaults (repositories under /var/lib/forgejo) are sensible; leave them unless you have a reason to change them.
• Administrator account - Create the first admin user in the optional settings section.

Submitting the form writes the configuration to /etc/forgejo/app.ini. From then on that file is the source of truth for your instance.

Configure app.ini

For anything beyond the basics you edit /etc/forgejo/app.ini directly, then restart the service:

sudo -e /etc/forgejo/app.ini
sudo systemctl restart forgejo

Common early tweaks include setting [server] DOMAIN and ROOT_URL correctly, disabling open registration with [service] DISABLE_REGISTRATION = true, and configuring an SMTP block under [mailer] so Forgejo can send notifications.

Create an Admin User from the CLI

You can also create an administrator without the web form. Run the command as the forgejo user so file permissions stay correct:

sudo -u forgejo forgejo admin user create \
  --admin \
  --username root \
  --email admin@example.com \
  --random-password \
  --config /etc/forgejo/app.ini

Put It Behind a Reverse Proxy

For anything public, front Forgejo with a reverse proxy such as nginx or Caddy to terminate TLS. A minimal nginx location simply proxies to the local port:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Remember to set ROOT_URL in app.ini to your public HTTPS address so generated links and clone URLs are correct.

Keeping Forgejo Updated

Upgrades come through the normal package workflow:

sudo apt update && sudo apt upgrade

After a Forgejo upgrade, restart the service so the new binary takes over. Forgejo runs any needed database migrations automatically on start, but take a backup of your data directory and database before major version jumps.

Other Tools from deb.griffo.io

The repository packages other self-hosting and developer tooling that pairs well with a Forgejo instance:

• Forgejo Runner - The CI/CD runner that executes your Forgejo Actions
• Lazygit - A fast terminal UI for everyday Git operations
• Lazydocker - A terminal UI for Docker and docker-compose
• k9s - A terminal UI for managing Kubernetes clusters

Troubleshooting

GPG or Key Errors

If APT cannot verify the repository, re-add the signing key:

sudo rm -f /etc/apt/keyrings/deb.griffo.io.gpg
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot find the forgejo package:

1. Run sudo apt update again to refresh the index.
2. Confirm your release is supported (Bookworm, Trixie, or Sid).
3. Check the source entry: cat /etc/apt/sources.list.d/deb.griffo.io.list

Service Fails to Start

If systemctl status forgejo shows the service failing, check the journal:

sudo journalctl -u forgejo -n 50 --no-pager

The most common causes are a database it cannot reach, a ROOT_URL mismatch, or permission problems on /var/lib/forgejo. Make sure the data directory is owned by the forgejo user:

sudo chown -R forgejo:forgejo /var/lib/forgejo

Uninstalling

To remove Forgejo:

sudo systemctl disable --now forgejo
sudo apt remove forgejo

Your repositories and database under /var/lib/forgejo and the config in /etc/forgejo are left in place unless you delete them manually. To remove the repository:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

Forgejo gives you a full-featured Git forge that you control end to end, without the operational weight of a large platform. Installing it from deb.griffo.io means the binary, the system user and the systemd unit are all set up for you, and future upgrades ride along with your normal apt upgrade.

Start the service, run the web setup, put it behind TLS, and add a runner for CI. From there you have a private home for your code that is genuinely yours.

Frequently Asked Questions

How do I install the latest Forgejo on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install forgejo. The repository tracks upstream Forgejo releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for Forgejo?

Yes. deb.griffo.io publishes Forgejo as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update Forgejo to the latest version?

Run sudo apt update && sudo apt upgrade. Once Forgejo is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install Forgejo on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install Forgejo on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

• Forgejo Official Website
• Forgejo Documentation
• Forgejo Source Repository
• deb.griffo.io Repository

---

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Forgejo project.