Forgejo on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Forgejo, the open source, self-hosted Git service - a lightweight, fast alternative to GitHub and GitLab: repositories, pull requests, issues, a built-in CI (Forgejo Actions), packages, wikis and code review, deployable in your own virtual network.

The Forgejo server is a single Go binary that serves both the REST API and the bundled web app. It runs behind nginx as a reverse proxy. PostgreSQL is the datastore; the server listens on 127.0.0.1:3000 and is reached through nginx on port 80 (and 443 once you add TLS). The server and the database bind to the loopback interface only.

On the first boot of every deployed VM, a one-shot service generates fresh server secrets (the SECRET_KEY, the INTERNAL_TOKEN, and the OAuth2 and LFS JWT secrets) unique to that VM, rotates the PostgreSQL password, runs the database migrations, and creates a single administrator account with a per-VM password. Open registration is disabled and the web installer is locked. The login is written to /root/forgejo-credentials.txt with mode 0600.

What is included:

• Forgejo 15.0 as a single Go binary at /usr/local/bin/forgejo, behind nginx on :80
• PostgreSQL as the datastore, bound to loopback only
• Two dedicated Azure data disks captured into the image: the PostgreSQL datadir at /var/lib/postgresql (LUN 0) and the Forgejo data + git repositories at /var/lib/forgejo (LUN 1) - each independently resizable and separate from the OS disk
• Per-VM administrator and database passwords plus fresh server secrets generated at first boot, in a root-only file
• forgejo.service, postgresql.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point; scale up for larger teams or heavier CI workloads. NSG inbound: allow 22/tcp from your management network (SSH admin access and git over SSH) and 80/tcp (plus 443/tcp once you enable TLS) from the networks your users reach Forgejo on.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Forgejo by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the two dedicated data disks on the Disks tab, then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name forgejo \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name forgejo --port 80 --priority 1010

First boot initialisation takes under a minute after the VM reaches the Running state.

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active forgejo.service postgresql.service nginx.service
curl -fsS http://127.0.0.1/api/healthz

All three units report active and the health endpoint returns a "pass" status, confirming the full stack - nginx, the Forgejo server and PostgreSQL - is serving.

Service status, the open health endpoint and the two dedicated data disks.

Step 5 - Retrieve the administrator login

The administrator account is created uniquely on the first boot of your VM and its login written to a root-only file:

sudo cat /root/forgejo-credentials.txt

You will see a plain text file containing the Forgejo URL, the administrator username (administrator) and the password, plus the per-VM PostgreSQL login.

The per-VM administrator login and the API rejecting unauthenticated requests.

Step 6 - First sign-in

Open a web browser and navigate to http://<vm-public-ip>/. Forgejo presents its sign-in page. Enter the username administrator and the password from /root/forgejo-credentials.txt, then select Sign In.

The Forgejo sign-in, served on first boot with a per-VM administrator login.

After signing in you land on the dashboard - your activity feed, your repositories, and the contribution graph. The top bar gives you Issues, Pull Requests, Milestones and Explore, and the + menu creates new repositories, migrations and organisations.

The Forgejo dashboard - activity feed, repositories and the contribution graph.

Step 7 - Create a repository and push code

Select + then New Repository, give it a name, and create it. A repository gives you code browsing, issues, pull requests, releases, packages, a wiki and Actions (built-in CI).

A Forgejo repository - code, README, issues, pull requests, actions and packages.

Push an existing local repository to Forgejo over HTTPS (replace the placeholders):

git remote add origin http://<vm-public-ip>/administrator/<repo-name>.git
git push -u origin main

To push over SSH, add your public key under Settings -> SSH / GPG Keys in the web UI, then use the SSH remote git@<vm-public-ip>:administrator/<repo-name>.git. Git over SSH is served by the VM's OpenSSH daemon on port 22.

Step 8 - Confirm the runtime

/usr/local/bin/forgejo --version

The pinned Forgejo release and the install layout across the OS and data disks.

Step 9 - Invite your team and use the API

Open the Site Administration area (the avatar menu) to add users and organisations - open registration is disabled by default, so you create accounts here or re-enable registration in the configuration. Every action in the web app is also available through the REST API at http://<vm-public-ip>/api/v1/ - generate a token under Settings -> Applications, then call the API with an Authorization: token <token> header. The interactive API docs (Swagger) are served at http://<vm-public-ip>/api/swagger.

Enabling HTTPS

For any production deployment serve Forgejo over HTTPS so logins and Git operations cannot be intercepted. The image ships with nginx, which certbot can configure automatically. The following assumes you have a DNS record pointing your fully qualified domain name at the VM's public IP address, and that port 443 is open in the NSG:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d git.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the root URL so generated links and clone URLs are correct, then restart Forgejo:

sudo sed -i 's|^ROOT_URL = .*|ROOT_URL = https://git.your-domain.example/|' /etc/forgejo/app.ini
sudo systemctl restart forgejo

Backup and maintenance

Forgejo keeps its metadata - users, repositories, issues and settings - in PostgreSQL on the LUN 0 data disk, and the git repositories themselves under /var/lib/forgejo/repositories on the LUN 1 data disk. Back both up regularly:

cd /tmp
sudo -u postgres pg_dump forgejo > /tmp/forgejo-db-$(date +%F).sql
sudo tar czf /tmp/forgejo-repos-$(date +%F).tgz -C /var/lib/forgejo repositories data
ls -lh /tmp/forgejo-db-$(date +%F).sql /tmp/forgejo-repos-$(date +%F).tgz

Move the archives off the VM (for example to an Azure storage account). Forgejo also has a built-in dump command that bundles everything into one archive: sudo -u git GITEA_WORK_DIR=/var/lib/forgejo /usr/local/bin/forgejo dump -c /etc/forgejo/app.ini. Because the database and the repositories are each on their own Azure data disk, you can also take coordinated disk snapshots in Azure.

The PostgreSQL and git repository data tiers on their dedicated Azure data disks.

To upgrade Forgejo, replace /usr/local/bin/forgejo with a newer release and restart - migrations run automatically on start. Keep the OS patched with sudo apt update && sudo apt upgrade. See https://forgejo.org/docs/.

Scaling and operations

• Move PostgreSQL to Azure Database for PostgreSQL and update the [database] section of /etc/forgejo/app.ini
• Put the web tier behind Azure Application Gateway or a load balancer if you need high availability
• Enable Forgejo Actions for built-in CI/CD and register runners for your build workloads

Each of these is documented in the official Forgejo documentation at https://forgejo.org/docs/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Forgejo questions consult the documentation at https://forgejo.org/docs/. Forgejo is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement. All product and company names are trademarks or registered trademarks of their respective holders.