Gitea on AWS User Guide

Overview

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

The Gitea 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 instance, a one-shot service generates fresh server secrets (the SECRET_KEY, the INTERNAL_TOKEN, and the OAuth2 and LFS JWT secrets) unique to that instance, 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/gitea-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 allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach Gitea on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: 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 Gitea. Select the cloudimg 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, and either 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 initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Gitea 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 above.

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=gitea-01}]'

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

Step 3: 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 depends on the operating system of the AMI variant you launched:

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.

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

You will see a plain text file containing the Gitea URL, the administrator username (admin) and the password. From the same SSH session you can confirm the deployment is healthy - the health endpoint is open:

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

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

A "pass" status confirms the full stack - nginx, the Gitea server and PostgreSQL - is serving.

Step 4: First Sign-in

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

The Gitea sign-in, served on first boot with a per-instance administrator login.

Step 5: The Dashboard

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 Gitea dashboard - activity feed, repositories and the contribution graph.

Step 6: 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 Gitea repository - code, README, issues, pull requests, actions and packages.

Push an existing local repository to Gitea over HTTPS:

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

Step 7: 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://<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.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve Gitea 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 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 Gitea:

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

Step 9: Backups and Maintenance

Gitea keeps its metadata - users, repositories, issues and settings - in PostgreSQL, and the git repositories themselves under /var/lib/gitea/repositories. Back both up regularly:

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

Gitea also has a built-in dump command that bundles everything into one archive: sudo -u git GITEA_WORK_DIR=/var/lib/gitea /usr/local/bin/gitea dump -c /etc/gitea/app.ini. Ship the archives to an Amazon S3 bucket or another object store. Because the database and the repositories are each on their own EBS volume, you can also take coordinated EBS snapshots. To upgrade Gitea, replace /usr/local/bin/gitea with a newer release and restart - migrations run automatically on start. See https://docs.gitea.com/.

Step 10: Scaling and Operations

• Move PostgreSQL to Amazon RDS for PostgreSQL and update the [database] section of /etc/gitea/app.ini
• Put the web tier behind an Application Load Balancer if you need high availability
• Enable Gitea Actions for built-in CI/CD and register runners for your build workloads

Each of these is documented in the official Gitea documentation at https://docs.gitea.com/.

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 Gitea questions consult the documentation at https://docs.gitea.com/. Gitea is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.