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
Arecord pointing to the server IP (Configured at DNS provider)
- An email address (e.g. firstname.lastname@example.org) 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. smtp.example.com:465)
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.
Install docker and docker-compose.
# Install docker
sudo apt-get install docker
# Install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.10.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# Make docker-compose executable
sudo chmod +x /usr/local/bin/docker-compose
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 https://github.com/jwobith/docker-gitea && 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
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
# Make sure user has UID and GID 1000
usermod -u 1000 -g 1000 git
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 email@example.com "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
Make the file
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
ln -s /var/lib/gitea/git/.ssh/authorized_keys /home/git/.ssh/authorized_keys
git user key into the
For an RSA key:
echo "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty $(cat /home/git/.ssh/id_rsa.pub)" >> /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/id_ed25519.pub)" >> /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
# New sshd_config
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.
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.
|Name to display on homepage and tab
|Gitea: Git with a cup of tea
|Protocol for Gitea server
|Domain for the Gitea service
|Virtual host for Gitea server
|Virtual port for Gitea server to expose to proxy network
|Domain for which to generate the certificate
|E-Mail for receiving important account notifications (mandatory)
|Name for the database
|User for the database
|Password for the database
- 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-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
To make additional configuration changes first shut down the containers with
docker-compose.ymlto update the Docker service
/var/lib/gitea/gitea/conf/app.inito update the Gitea configuration
nginx.tmplto update the Nginx configuration
Restart the containers with
docker-compose up -d
- Gitea Website
- Gitea Docker Installation
- Docker Compose
- Gitea Repo
- Gitea Image
- Nginx Repo
- Nginx Image
- docker-gen Repo
- docker-gen Image
- docker-letsencrypt-nginx-proxy-companion Repo
- letsencrypt-nginx-proxy-companion Image
- If you find any problems please fill out an issue. Thank you!
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.