How to Install Gitea with Docker on Ubuntu

December 29, 2022

Introduction

Gitea is a self-hosted lightweight Git platform similar to GitHub, GitLab, and Gogs. The Gitea project aims to provide a code hosting tool that focuses primarily on speed and simplicity.

This tutorial will show you how to install and set up Gitea on Ubuntu using Docker.

How to install Gitea with Docker on Ubuntu.

Prerequisites

How to Install Gitea with Docker on Ubuntu

Gitea's Docker Hub repository contains automatically updated Gitea Docker images that you can use with Docker and Docker Compose to deploy a local Gitea installation. However, before installing Gitea on Ubuntu, ensure the system is properly set up.

Follow the steps below to create a self-hosted Gitea instance on Ubuntu.

Step 1: Create Git User

Gitea Docker deployment communicates with the external OS environment through a dedicated git system user.

To create a git user account:

1. Execute the following adduser command:

sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' --group --disabled-password --home /home/git git

2. Make a note of the UID (User ID) and GID (Group ID) numbers in the output:

Creating a system user in Ubuntu.

Step 2: Deploy Gitea with Docker Compose

The most straightforward way to deploy Gitea with Docker is by using Docker Compose. The steps below explain the procedure in detail.

1. Create a directory for the Docker Compose deployment and go to that directory:

mkdir gitea && cd gitea

2. Create the docker-compose YML file using a text editor. The example below uses Nano.

nano docker-compose.yml

3. Enter the configuration for a new Gitea instance. The following example creates a deployment with the latest version of the gitea/gitea image and maps the TCP and SSH container ports to the external ports 3000 (TCP) and 2222 (SSH):

version: "3"

networks:
  gitea:
    external: false

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=[uid]
      - USER_GID=[gid]
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /home/git/.ssh/:/data/git/.ssh
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "127.0.0.1:2222:22"

Assign the UID and GID numbers from Step 1 of this tutorial to the USER_UID and USER_GID environment variables.

Editing the docker-compose file in Nano.

Save the file and exit.

4. Install Gitea with the command below:

docker-compose up

Docker Compose follows the specifications from the file and deploys a containerized Gitea instance.

Creating and running a Gitea container with docker-compose.

The instance runs in the foreground, so you need to open a new terminal window to continue with the next step. Alternatively, run a detached container in the background by adding the -d option.

docker-compose up -d

The output confirms Gitea has started in the background, and the command prompt appears.

Creating and running a Gitea container in the detached mode.

Step 3: Add Reverse Proxy

For the collaboration features to work as expected, the Gitea installation must be accessible from the internet. Installing a reverse proxy allows you to connect a domain name or an IP address to the Gitea instance.

Follow the steps below to install and set up an Nginx reverse proxy.

1. Install Nginx from the official Ubuntu repository:

sudo apt install nginx 
Installing Nginx as a reverse proxy.

Type Y and press Enter to proceed.

2. Create a server configuration file for Gitea:

sudo nano /etc/nginx/sites-available/gitea 

3. Add the configuration for the Gitea instance.

server {
    server_name [your-domain];

    root /var/www/html;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header HOST $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Replace [your-domain] in the file with the actual domain.

Editing the gitea configuration file in the Nginx sites-available directory.

Save the file and exit.

4. Create a symbolic link in the sites-enabled directory. The link points to the configuration file in the sites-available directory.

sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/gitea

5. Test the configuration with the following command:

sudo nginx -t

The output shows that the test is successful.

Testing Nginx configuration.

6. Restart Nginx.

sudo systemctl restart nginx

Step 4: Add TLS Encryption

Provide TLS encryption for the Gitea instance to enable HTTPS access:

1. Install certbot, a tool for installing Let's Encrypt certificates.

sudo apt install certbot python3-certbot-nginx

2. Run certbot with the --nginx flag. Provide your domain name with the -d flag.

sudo certbot --nginx -d [your-domain]

3. Enter an email address for security-related notices. Type Y and press Enter to agree to the Terms of Service.

Creating a TLS certificate with certbot.

Once certbot generates the certificate, the tool automatically reloads Nginx with the new configuration.

Step 5: Configure Gitea

After you create a system user, install a reverse proxy, and generate a TLS certificate, proceed to configure Gitea:

1. Access the Gitea instance in a web browser. Navigate to:

https://[your-domain]

The Initial Configuration page appears.

The Initial Configuration page in Gitea.

2. Scroll to the General Settings section and change the Site Title and Server Domain fields to your values.

Editing General Settings in Gitea.

3. Scroll further down and change the Gitea Base URL field.

Further editing of General Settings in Gitea.

Save the configuration by selecting the Save button at the bottom of the page.

Step 6: Create User Account

After you perform the initial configuration of Gitea, create the administrative user by following the procedure below:

1. Select the Register now link on the Sign In page.

Gitea Sign In page.

2. Fill out the necessary account information and select the Register Account button.

Registering a new user in Gitea.

Step 7: Create Test Repository

Repository management in Gitea is similar to other code-hosting solutions. Follow the steps below to create a repository using Gitea's GUI:

1. Click the + sign in the upper-right corner of the screen.

2. Select New Repository to load the repository creation page.

Navigating to the New Repository option in Gitea.

3. Fill out the required information, such as the owner and the name of the repository.

Creating a new repo in Gitea.

4. Scroll to the bottom of the page and select the Create Repository button.

Confirming the creation of a new repo in Gitea.

The repository page appears.

The new repository in Gitea.

Step 8: Enable SSH Access

Additional configuration is necessary to enable the SSH connection with the Gitea container.

To enable SSH access:

1. Generate an RSA 4096 key for the git user:

sudo -u git ssh-keygen -t rsa -b 4096 -C "[key-name]"

2. Leave the field empty when prompted to enter a passphrase and press Enter.

The system generates an SSH key.

Generating an RSA 4096 SSH key for the git user.

3. Add the key to the authorized_keys file in the .ssh directory of the git user by running this command:

sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
Moving the SSH key to the authorized_keys file.

4. Limit the permissions for the file with the chmod command:

sudo -u git chmod 600 /home/git/.ssh/authorized_keys

5. Create the gitea command. This enables the Gitea Docker container to establish an SSH connection through the host.

cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF

6. Make the file executable:

sudo chmod +x /usr/local/bin/gitea

Step 9: Add SSH User

Once you configure the Gitea container to accept SSH connections, start authorizing users that will connect to the instance via SSH.

1. Generate an SSH key for the user who needs SSH access.

2. Output the key with the cat command and copy it to the clipboard.

Copying an SSH key with the cat command in Ubuntu.

3. In the Gitea GUI, click the user icon in the upper-right corner of the screen.

4. Select Settings in the menu.

Navigating to Gitea Settings.

5. Select the SSH / GPG Keys item in the Settings menu.

6. Click the blue Add Key button.

7. Paste the SSH key you copied in the Content field.

8. Click the green Add Key button in the lower-left corner.

Adding an SSH key to the list of authorized SSH keys in GItea.

The user is now authorized to use SSH for connecting to Gitea.

Conclusion

After reading this tutorial, you know how to deploy a Gitea instance using Docker.

The article also explained the procedure for performing the initial configuration of the instance and how to enable SSH access to Gitea.

Was this article helpful?
YesNo
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
How to Use Git {Beginner's Guide}
September 2, 2021

Knowing how to use Git has become a mandatory skill in the world of coding. In this step-by-step beginner's guide, you will learn how to start using Git effectively.
Read more
Git Submodule Guide & Basic Commands to Get Started
September 1, 2022

When developing an application using Git, it is practical to integrate code available in other repositories. Reusing the code shortens...
Read more
How Does Git Work?
September 16, 2021

Having a good understanding of Git is essential if you want to code and work on a collaborative software development project. In this article...
Read more
Git Tag: An Overview of the Basic Functions
September 6, 2022

Tags mark program release versions, bug fixes, patches, or specific commits, and help you find every project stage quickly. This tutorial provides an overview...
Read more