Deployment guide

Forgejo

Videos

Overview: Forgejo on Ubuntu 24.04 on Azure: overview (watch on YouTube)

Launch and log in: Forgejo on Ubuntu 24.04 on Azure: launch and log in (watch on YouTube)

Deep Dive: Forgejo on Ubuntu 24.04 on Azure: deep dive (watch on YouTube)

Overview

Forgejo is an open-source, self-hosted Git service and a lightweight, fast alternative to GitHub and GitLab. It provides repositories, pull requests, issues, built-in CI (Forgejo Actions), packages, wikis and code review, and you can deploy it in your own virtual network.

This image runs Forgejo as a single Go binary that serves both the REST API and the bundled web app. The server runs behind nginx as a reverse proxy, with PostgreSQL as 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 unique to that VM: the SECRET_KEY, the INTERNAL_TOKEN, and the OAuth2 and LFS JWT secrets. It also 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 you get:

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 and git repositories at /var/lib/forgejo (LUN 1). Each disk is separate from the OS disk and can be resized independently
Per-VM administrator and database passwords plus fresh server secrets, generated at first boot and stored in a root-only file
forgejo.service, postgresql.service and nginx.service as systemd units, enabled and active
24/7 SecureAnyCloud support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet and 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 rules: 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 and search the Marketplace for Forgejo by SecureAnyCloud. Select Create.

On the Basics tab, 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 select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:forgejo-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name forgejo \
  --image sac1647283583153:forgejo-ubuntu-24-04:default:latest \
  --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 initialization finishes in 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. Together these confirm that the full stack (nginx, the Forgejo server and PostgreSQL) is serving.

The output shows the 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 is written to a root-only file. Read the file:

sudo cat /root/forgejo-credentials.txt

The file contains the Forgejo URL, the administrator username (administrator) and the password, plus the per-VM PostgreSQL login.

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

Step 6 - First sign-in

Open a web browser and go 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 page, served on first boot with a per-VM administrator login.

After you sign in, you land on the dashboard, which shows your activity feed, your repositories and the contribution graph. The top bar links to Issues, Pull Requests, Milestones and Explore. The + menu creates new repositories, migrations and organizations.

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

Step 7 - Create a repository and push code

Select + then New Repository, give the repository 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, with code, README, issues, pull requests, actions and packages.

Push an existing local repository to Forgejo over HTTPS, replacing the values in angle brackets:

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. The VM's OpenSSH daemon serves git over SSH on port 22.

Step 8 - Confirm the runtime

/usr/local/bin/forgejo --version

The output shows 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 (in the avatar menu) to add users and organizations. Open registration is disabled by default, so 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

Serve Forgejo over HTTPS in any production deployment, so that logins and Git operations cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following steps assume that a DNS record points 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. The git repositories themselves are under /var/lib/forgejo/repositories on the LUN 1 data disk. Back up both 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. The database and the repositories are each on their own Azure data disk, so you can also take coordinated disk snapshots in Azure.

The PostgreSQL and git repository data tiers sit 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.

The official Forgejo documentation at https://forgejo.org/docs/ covers each of these.

Support

SecureAnyCloud provides 24/7/365 expert technical support for this image, with a guaranteed response within 24 hours and a one-hour average for critical issues. Contact sales@secureanycloud.com.

For general Forgejo questions, consult the documentation at https://forgejo.org/docs/. Forgejo is a trademark of its respective owner, and its 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.

Deploy on Azure

Launch Forgejo on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

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

Prerequisites

Before you deploy this image, you need:

An Amazon Web Services account where you can launch EC2 instances.
IAM permissions to launch instances, create security groups and subscribe to AWS Marketplace products.
An EC2 key pair in the target Region for SSH access to the instance.
A VPC and subnet in the target Region, with a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users reach Forgejo on.
The AWS CLI (version 2) installed locally if you plan to deploy from the command line.

Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Forgejo. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First-boot initialization finishes in under a minute after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud Forgejo Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80 and 443 as described in Prerequisites.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=forgejo-01}]'

On success, the command prints a JSON document. Note the instance ID, then retrieve the instance's public address once it is running withaws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect and retrieve the administrator login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user for Forgejo 15.0 on Ubuntu 24.04 is ubuntu.

The first-boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time. Read the file:

ssh <login-user>@<public-ip>
sudo cat /root/forgejo-credentials.txt

The file contains the Forgejo URL, the administrator username (administrator) and the password. From the same SSH session, you can confirm that the deployment is healthy. The health endpoint is open:

curl -fsS http://127.0.0.1/api/healthz

{"status":"pass","description":"Forgejo",...}

A "pass" status confirms that the full stack (nginx, the Forgejo server and PostgreSQL) is serving.

First sign-in

Open a web browser and go to http://<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 page, served on first boot with a per-instance administrator login.

The dashboard

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

Create a repository and push code

Select + then New Repository, give the repository 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, with code, README, issues, pull requests, actions and packages.

Push an existing local repository to Forgejo over HTTPS:

git remote add origin http://<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@<public-ip>:administrator/<repo-name>.git.

Invite your team and use the API

Every action in the web app is also available through the REST API at http://<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://<public-ip>/api/swagger.

Enable HTTPS with Let's Encrypt

Serve Forgejo over HTTPS in any production deployment, so that logins and Git operations cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following steps assume that a DNS record points your fully qualified domain name at the instance's public IP address.

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

Backups and maintenance

Forgejo keeps its metadata (users, repositories, issues and settings) in PostgreSQL. The git repositories themselves are under /var/lib/forgejo/repositories. Back up both regularly:

sudo -u postgres pg_dump forgejo > <backup-dir>/forgejo-db-$(date +%F).sql
sudo tar czf <backup-dir>/forgejo-repos-$(date +%F).tgz -C /var/lib/forgejo repositories data

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. Ship the archives to an Amazon S3 bucket or another object store. The database and the repositories are each on their own EBS volume, so you can also take coordinated EBS snapshots.

To upgrade Forgejo, replace /usr/local/bin/forgejo with a newer release and restart. Migrations run automatically on start. See https://forgejo.org/docs/.