// Tutorial //

How to Install Gitea on Ubuntu Using Docker

Published on May 5, 2022 · Updated on May 5, 2022

By Madison Scott-Clary

Tech Writer at DigitalOcean

Introduction

When working on software development, it’s important to be able to manage the source code in an efficient and traceable way. Source code management (SCM) systems are an excellent way to provide an efficient and flexible process for working on projects of any size with any number of developers. Many different pieces of SCM software have existed through the years, from CVS to SubVersion, Perforce to Mercurial, but the current industry leader is Git, which has seen major growth with the popularity of sites such as GitHub and GitLab.

However, with free accounts on these services geared towards public, open-source repositories, the ability to work on private or proprietary software incurs a cost to the developer. Additionally, one’s access to the repository is beholden to an external organization, and many would prefer to control their own software from start to finish.

To that end, several self-hosted solutions such as Gogs, Gitea, and GitLab have been developed over the last several years. This tutorial focuses on setting up one of the more popular solutions, Gitea, to allow you to host private repositories and manage your own projects throughout their entire life-cycle. Gitea is small, self-contained, and lightweight, making it a quick process to deploy without breaking the bank on hardware requirements. You will be using a Docker installation of Gitea, which ensures that the software will be kept up to date.

Prerequisites

Before beginning this tutorial, you should have the following:

• An Ubuntu 20.04 server with a non-root user configured with sudo privileges as described in the initial server setup for Ubuntu 20.04.
• Docker installed on your server. Follow Steps 1 and 2 of How to Install Docker on Ubuntu 20.04 to install Docker.
• Docker Compose installed on your server. Follow Step 1 of our guide on How to Install and Use Docker Compose on Ubuntu 20.04 to set this up.
• A domain name pointed at your server. If you are using a DigitalOcean Droplet, you can accomplish this by following our Domains and DNS documentation. This tutorial will use your_domain in examples throughout.

Step 1 — Creating the Git user

Gitea, like many source code repositories, uses SSH for accessing remote repositories. This allows users to control access to their code by managing their SSH keys within Gitea itself. In order for users to be able to access the host via SSH, however, you will need to create a git user on the host machine. This step is completed first so that you can access the user’s user and group ID.

First, create the user on the host who will be accepting these connections:

In this command, you create a system user that uses bash as its shell, but does not have a login password. This allows you to use sudo to run commands as that user but prevents logging in as it. You also set the user’s home directory to /home/git.

This command will output some information about the user it just created:

Make note of the UID and GID values provided here (in this case, a UID of 112 and a GID of 119), as they will be used in a future step.

Step 2 — Installing the Gitea Docker Image

Gitea has an image available in the global Docker repository, meaning that, using Docker Compose, you can install and run that image as a service with little extra work. The image itself runs the Gitea web and SSH services, allowing Git access both from the browser and the command line.

In order to spin up the Gitea container, you will be using Docker Compose, a declarative tool for setting up an environment.

To begin with, create a directory to host your service and enter it:

Once there, create a file called docker-compose.yml using your preferred text editor. The following example uses nano. This file will contain the descriptions of the containers that will run as part of your Gitea installation:

Add the following into this new file:

version: "3"

networks:
  gitea:
    external: false

services:
  server:
    image: gitea/gitea:1.16.5
    container_name: gitea
    environment:
      - USER_UID=UID_from_step_1
      - USER_GID=GID_from_step_1
    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"

Let’s walk through what this file does:

• version: "3": this lets Docker Compose what version of configuration file this is.
• networks: this section declares the networking setup of our collection of containers. In this case, a gitea network is created, but is not exposed externally.
• services
  • image: gitea/gitea:1.16.5: this specifies that we will be using Gitea version 1.16.5; however you can change the value after the colon to specify other versions, whether a specific release, a major version such as :1, or a tag such as :latest or :dev.
  • environment: the environment section specifies environment variables that will be available to the image during installation and running. In this case, we are specifying a user and group ID for the environment, using the UID and GID provided in the output of the adduser command in Step 1.
  • restart: always: this line instructs Docker to always restart the container if it goes down, whether because the container itself goes down or the host machine does; essentially, Gitea will start on boot.
  • networks: this specifies that the Gitea service will have access to and be accessible on the network named above.
  • ./gitea:/data and /home/git/.ssh/:/data/git/.ssh: these are the locations where Gitea will store its repositories and related data. Currently, this is mapped to the folder named gitea in the current directory. Docker will create this folder when the container starts if it doesn’t exist. The .ssh folder will be described further later on in Step 6.
  • /etc/timezone and /etc/localtime: these two files contain information about the timezone and time on the host machine. By mapping these directly into the container as read-only files (specified with the final :ro part of the definitions), the container will have the same information as the host.
  • ports: Gitea listens for connections on two ports. It listens for HTTP connections on port 3000, where it serves the web interface for the source code repository, and it listens for SSH connections on port 22. In this case, you are keeping port 3000 for HTTP connections by mapping it to the same number, and you are mapping the port on Gitea’s container from the usual 22 to 2222 to avoid port-clashing. In Step 6, you will set up an SSH shim to direct traffic to Gitea when requested.

Save and close the file. If you used nano to edit the file, you can do so by pressing CTRL + X, Y, and then ENTER.

With this file in place you can then bring the containers up using Docker Compose:

This command will pull down the images, start the Gitea container, and will return output like this:

This will leave the container running in the foreground, however, and it will stop as soon as you exit the process with Ctrl + C or by losing your connection. In order to have the container run in the background as a separate process, you can append the -d flag to the Compose command:

You will be notified when the container starts and then returned to your shell.

Step 3 — Installing Nginx as a Reverse Proxy

Running a web service such as Gitea behind a reverse proxy is common practice, as modern server software such as Apache or Nginx can more easily handle multiple services on one machine, balance load across multiple servers, and handle SSL. Additionally, this will allow you to set up a domain name pointing to your Gitea instance running on standard HTTP(S) ports.

For the purposes of this tutorial, we’ll use Nginx. First, update the package lists on your host machine:

Next, install Nginx using apt:

Now, as you are using the firewall ufw, you will need to allow access to these ports:

Once this is installed, you should be able to access your server in your browser by visiting http://your_domain. This will lead you to a very plain page welcoming you to Nginx.

At this point, you’ll need to create a reverse proxy entry to direct incoming traffic through Nginx to the Gitea instance running in Docker. Create a new file in the Nginx sites-available directory using your preferred text editor. The following example uses nano:

In this file, set up a new server block with requests to / proxied to your Gitea instance:

server {
    # Listen for requests on your domain/IP address.
    server_name your_domain;

    root /var/www/html;

    location / {
        # Proxy all requests to Gitea running on port 3000
        proxy_pass http://localhost:3000;
        
        # Pass on information about the requests to the proxied service using headers
        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;
    }
}

Once you are finished editing the file, save and close it.

Nginx determines what sites it will actually serve based on whether or not those files are present in its sites-enabled directory. This is managed via symbolic links pointing to the files in the sites-available directory. You will need to create one of those symbolic links for Nginx to start serving Gitea:

Before you restart Nginx to make your changes live, you should have Nginx itself check that those changes are valid by testing its config.

If everything’s okay, this command will return output like the following:

If there are any issues, it will tell you what and where they are.

When you’re ready to move ahead with this change, restart the Nginx system service:

Now, when you visit http://your_domain in your browser, you should find yourself on the initial setup page for Gitea ready for you to fill out.

Step 4 — Installing Certbot and Setting Up TLS Certificates

Thanks to Certbot and the Let’s Encrypt free certificate authority, adding TLS encryption to your Gitea installation app will take only two commands.

First, install Certbot and its Nginx plugin:

Next, run certbot in --nginx mode, and specify the same domain that you used in the Nginx server_name configuration directive:

You’ll be prompted to agree to the Let’s Encrypt terms of service, and to enter an email address.

Afterwards, you’ll be asked if you want to redirect all HTTP traffic to HTTPS. It’s up to you, but this is generally recommended and safe to do.

After that, Let’s Encrypt will confirm your request and Certbot will download your certificate:

Certbot will automatically reload Nginx with the new configuration and certificates. Reload your site in your browser and it should switch you over to HTTPS automatically if you chose the redirect option.

Your site is now secure and it’s safe to continue with the web-based setup steps.

You can find more information on securing domains with Let’s Encrypt on the How to Secure Nginx with Let’s Encrypt on Ubuntu 20.04 tutorial.

Step 5 — Configuring Gitea and Adding a First User

Now you can move on to configuring Gitea itself and creating the first admin user. Visit your Gitea instance by opening https://your_domain in a browser. On the initial Gitea configuration screen, there will be several options for the service:

Some of these such as the site title are up to your particular use case, though for the purposes of this tutorial, you’ll need to change the following:

• Server domain: the server domain that you set up in Step 3
• Gitea Base URL: the full URL that you’ll use to access Gitea in the browser, including the protocol. For example, https://your_domain.

When you save your configuration changes, you will be directed to the Gitea login page.

As you do not yet have a user, you will need to create one, first. Click the Need an account? Register now link below the login form to register a new user. As the first user on the system, this user will be created as an administrator. If you set up email settings on the configuration screen, you may need to verify your account first.

Once you are logged in as that user, clicking on your user icon in the upper right-hand corner of the page and then clicking Site Administration from the drop-down menu will take you to a page where you will be able to run maintenance jobs, manage user accounts and organizations, and further configure Gitea.

Creating a Test Repository

In order to test Gitea, both on the web interface and using Git itself, create a test repository. You can always delete this repository later.

Click on the + sign in the upper right corner of the page, and then click on + New Repository from the drop-down menu. Here, you will be presented with a screen allowing you to name and customize your repository with information such as its description, settings such as whether or not it’s private, and any default contents such as a README or .gitignore file.

Once you hit Create Repository, you will have a new repository to play around with.

Step 6 — Configuring an SSH Shim

The final step of the process is to prepare the host machine with an SSH shim. Because Gitea is running in a Docker container, it cannot accept SSH connections on the default port of 22, as this will clash with the host. In the docker-compose.yml file you created above, Docker was instructed to map a port on the host to port 22 on the container so that it accepts SSH connections to port 2222. Additionally, the SSH authorized_keys file will not be accessible to someone SSHing into the host by default.

In order to take this into account, you will need to create an SSH shim which will pass SSH connections to the git user on the host on to the container. In the compose file, you also specified that the USER in the container will have a user and group ID of 1000, and on the Gitea configure screen, you told the service to use the user named git.

Creating the Git user and its SSH key

Next, you will need to create an SSH key for the user. This will only be used in a step below and not shared with anyone outside the host.

This command uses sudo to create an SSH key as the user you created above. In this instance, the key will be a 4096-bit RSA key. You will be asked a series of questions such as what password you would like for the key and what to name the key file. Hit ENTER for each of them, leaving them blank to accept the default.

You will need to ensure that the user within the Gitea container will accept this key. You can do this by adding it to the .ssh/authorized_keys file:

These commands all work with the shim due to the fact that the directory /home/git/.ssh on the host is mounted as a volume on the container, meaning that the contents are shared between them. When a connection to the host via git over SSH is received, it will use the same authorized_keys file as the container.

Creating the SSH Shim Script

The final step for the shim is to create a stub gitea command on the host. This is what allows git commands to work over SSH: when an SSH connection is made, a default command will be run. This gitea command on the host is what will proxy the SSH connection to the container.

For this script, use cat to write to the file /usr/local/bin/gitea:

The command in this script SSHes to the Gitea Docker container, passing on the contents of the original command used by git.

Finally, make sure that the script is executable:

Testing Git SSH Connections

You can test out pulling from and pushing to Git repositories on your Gitea instance by adding your SSH key to your Gitea user.

You will need the contents of your SSH public key. This usually lives in a file named something like ~/.ssh/id_rsa.pub, depending on which algorithm you used when creating your key:

Copy the output of this command.

In Gitea, click on your user icon in the upper right-hand corner and select Settings. On the settings page, there will be a series of tabs on the top. Click on SSH/GPG Keys, then the Add Key button beside Manage SSH Keys. Paste your key into the large text area in the form and then click the Add Key button beneath it.

Now, navigate to the test repository you created in Step 3 and copy the SSH URL provided. On your local machine, clone the repository:

This will use SSH to clone the repository. If you have a password set on your SSH key, you will be asked to provide that.

Move to that directory, create a new file:

Next, add it to your staged changes:

Finally, commit that file:

Now, you should be able to push your changes to the remote repository:

When you refresh the page in your browser, your new file will appear in the repository.

Conclusion

You’ve set up a Gitea service using Docker in order to self-host your source-code repositories. From here, you will be able to work on both public and private repositories, using familiar workflows such as pull-request code reviews and projects organized by organization. Gitea also works well with various continuous integration and deployment (CI/CD) tools such as Drone, Jenkins, and GoCD. Additionally, using Docker volumes such as this allows you to extend your storage to fit Git LFS (large file storage) content on network or block storage.