Docker Gitea Service
Go to file
2022-09-15 19:11:04 -04:00
.env.sample add functional code and config files 2020-04-07 23:36:49 -04:00
.gitignore add .gitignore and updated README 2020-04-08 00:06:45 -04:00 update contributing doc 2020-04-08 11:23:47 -04:00
docker-compose.yml bump postgres to latest version 2022-09-15 19:10:11 -04:00
LICENSE add LICENSE 2020-04-07 23:31:39 -04:00
nginx.tmpl add functional code and config files 2020-04-07 23:36:49 -04:00 bump docker-compose link to latest version 2022-09-15 19:11:04 -04:00


Docker Gitea Service

Gitea is a self-hosted git service written in Go that is comparable to other self-hosted git projects like Gitlab. It provides an interface that is similar to Github but a solution that you host yourself. While it does not currently have more complex features like built-in CI it is a lightweight and functional solution to host your own public and private repositories. This repository contains the necessary configuration to run a full Gitea service in Docker using Docker Compose and the capability to auto renew SSL certificates with Let's Encrypt.

Table of contents


Here are the basic requirements:

  • An internet connected server or VPS with a static IP address
    • SSH access to the server
    • Storage space on the server for the service and repository data
  • A domain with an A record pointing to the server IP (Configured at DNS provider)
Name TTL Class Type Record 1200 IN A $IP
  • An email address (e.g. configured at your domain (If you want the Gitea service to be able to send email)
    • Make sure to note down the outgoing (SMTP) mail server information (e.g.

This guide assumes you are using Debian/Ubuntu but it can be adapted to other variations of linux. If you would like to add additional configuration options or help automate some of the setup see contributing below.

Quick start

Install docker and docker-compose.

# Install docker
sudo apt-get install docker

# Install docker-compose
sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Make docker-compose executable
sudo chmod +x /usr/local/bin/docker-compose

Create docker group and add current user to group (or add the user you would like to run docker).

# Create docker group
sudo groupadd docker

# Add user to docker group
sudo usermod -aG docker $USER

Create the gitea data directory.

sudo mkdir -p /var/lib/gitea

Check the docker service status and run a test container.

# Verify that docker service is running
sudo systemctl status docker

# Run a test container
docker run hello-world

Clone this repository and setup the .env file for your desired configuration.

# Clone this repository to your computer
git clone && cd docker-gitea

# Create a `.env` file by copying and adjusting `.env.sample` for configuration.
cp .env.sample .env

Start the docker service

# Start docker containers
docker-compose up -d

# Verify containers are running
docker ps

Additional steps

Create git user

Create a new git user on the host machine with UID and GID matching the git user inside the Gitea container.

# Create git user
adduser git

# Make sure user has UID and GID 1000
usermod -u 1000 -g 1000 git

SSH passthrough

A passthrough is configured to allow SSH connection to both the host and the container on the standard port 22. It is possible to explicitly set a different port for either in the docker-compose.yml, however then all future connections will require remembering a custom port for one of the devices so the passthrough is the recommended setup.

Create the file /app/gitea/gitea with the following contents:

ssh -p 2222 -o StrictHostKeyChecking=no git@ "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"

Make the file /app/gitea/gitea excecutable.

sudo chmod +x /app/gitea/gitea

Generate an SSH key for the git user. When prompted for a password you can leave it empty.

To generate an RSA key:

sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"

Alternately, to generate an ED25519 key:

sudo -u git ssh-keygen -t ed25519 -C "Gitea Host Key"

Create a symlink between the container authorized_keys and the host git user authorized_keys.

ln -s /var/lib/gitea/git/.ssh/authorized_keys /home/git/.ssh/authorized_keys

Echo the git user key into the authorized_keys file.

For an RSA key:

echo "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty $(cat /home/git/.ssh/" >> /var/lib/gitea/git/.ssh/authorized_keys

For an ED25519 key:

echo "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty $(cat /home/git/.ssh/" >> /var/lib/gitea/git/.ssh/authorized_keys


The first time you go to the site Gitea will guide you through the installation wizard.

  • Create an administrator user with a strong password.
  • Enter the email address and password for the Gitea server email account.
  • Enter the correct mail server information.
  • The remaining items should stay at the default setting.


On the host machine, make sure to use a strong user password and strong SSH keys. When you create the Gitea administrator for the first time use a strong password as well.

SSH root access

Disable root SSH access on the host machine. Edit /etc/ssh/sshd_config by changing the following line:

# Old sshd_config
PermitRootLogin yes

# New sshd_config
PermitRootLogin no

NOTE: If you are currently remotely accessing the machine as root or have edited the /etc/ssh/sshd_config incorrectly, the next command may cause you to lose connection to the server. Make sure you are connected via SSH as a non-root user.

Restart the ssh server with sudo service ssh restart.

External ports

If a firewall is configured on the host the following external ports must be opened:

  • 80/tcp for Web UI HTTP
  • 443/tcp for Web UI HTTPS
  • 22/tcp for SSH

On a Debian/Ubuntu server this can be configured using UFW:

# Install ufw
sudo apt-get install ufw

# Enable ufw service
sudo systemct enable ufw

# Set ufw default to deny all incoming
sudo ufw default deny incoming

# Set ufw default to allow all outgoing
sudo ufw default allow outgoing

# Set ufw to allow 80/tcp, 443/tcp, and 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp

# Display status of ufw service
sudo ufw status verbose



The configuration is performed via environment variables contained in a .env file. You can copy the provided .env.sample file as a reference.

Variable Description Example
APP_NAME Name to display on homepage and tab Gitea: Git with a cup of tea
PROTOCOL Protocol for Gitea server (Default: https)
DOMAIN Domain for the Gitea service
VIRTUAL_HOST Virtual host for Gitea server
VIRTUAL_PORT Virtual port for Gitea server to expose to proxy network 3000
LETSENCRYPT_DOMAIN Domain for which to generate the certificate
LETSENCRYPT_EMAIL E-Mail for receiving important account notifications (mandatory)
DB_NAME Name for the database gitea
DB_USER User for the database gitea
DB_PASSWD Password for the database gitea


  • nginx/nginx: Nginx docker image on docker hub.
  • jwilder/docker-gen: Docker-gen image on docker hub.
  • jrcs/letsencrypt-nginx-proxy-companion: Proxy companion docker image on docker hub.
  • gitea/gitea: Gitea docker image on docker hub.
  • postgres:14.5: PostgreSQL docker image on docker hub.


  • nginx: Reverse proxy provided by nginx.
  • nginx-gen: Container generation for nginx using docker-gen and template nginx.tmpl.
  • nginx-proxy-companion: Companion to nginx for creating, renewing, and using Let's Encrypt SSL certificates.
  • gitea: Gitea, a self-hosted git service written in Go.
  • db: PostgreSQL, the database for the git server.



  • /var/lib/gitea: Persistent volume for Gitea data


  • conf: Persistent volume for nginx configuration
  • vhost: Persistent volume for nginx virtual host configuration
  • html: Persistent volume for nginx html data
  • certs: Persistent volume for nginx certificate data
  • postgres: Persistent volume for PostgreSQL database

Advanced configuration

To make additional configuration changes first shut down the containers with docker-compose down

  • Edit docker-compose.yml to update the Docker service
  • Edit /var/lib/gitea/gitea/conf/app.ini to update the Gitea configuration
  • Edit nginx.tmpl to update the Nginx configuration

Restart the containers with docker-compose up -d



Do you want to help contribute to this repository? Check out the contributing documentation.


This project is licensed under the MIT License. See the LICENSE file for the full license text.