How to Install Gitea with Docker on Ubuntu

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.

Prerequisites

• Ubuntu 20.04 or later.
• Administrative access to the system.
• Docker and Docker Compose installed.
• A domain name pointing to the system's IP address.

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:

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.

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.

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.

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 

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.

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.

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.

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.

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

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

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.

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

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.

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

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

The repository page appears.

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.

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

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.

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

4. Select Settings in the menu.

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.

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.