docker-gitea/README.md

docker-gitea

Docker Gitea Service

Gitea is a self-hosted git service written in Go. It provides a setup that is similar to Github but a solution that you host yourself. 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

• Requirements
• Quick start
• Additional steps
  • Create git user
  • SSH passthrough
• Security
  • External ports
• Configuration
  • Environment
  • Images
  • Containers
  • Volumes
  • Advanced configuration
• Documentation
• Contributing

Requirements

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
  • --- | --- | --- | --- | ---
  • git.example.com | 1200 | IN | A | $IP
• An email address (e.g. gitea@example.com) 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.

Quick start

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/1.25.4/docker-compose-$(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

Setup the .env file for your desired configuration.

# Verify that docker service is running
sudo systemctl status docker
# Run a test container
docker run hello-world
# Clone this repository to your computer
git clone https://github.com/bitdexgroup/docker-gitea && cd docker-gitea
# Create a ``.env`` file by copying and adjusting ``env.sample`` for configuration.
cp env.sample .env
# Create required ``CONFIG`` directories
sudo mkdir -p /var/lib/gitea
# Start docker containers
docker-compose up -d
# Verify containers are running
docker ps

Addtional 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

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

#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "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 and create a symlink between the container and host authorized_keys.

# 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 container ``authorized_keys`` and 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/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

Installation

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

• Enter the email address and password for the Gitea email account
• Enter the correct mail server information.
• Most of the remaining items should stay at the default setting.

Security

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.

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

Configuration

Environment

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	git.example.com
VIRTUAL_HOST	Virtual host for Gitea server	git.example.com
VIRTUAL_PORT	Virtual port for Gitea server to expose to proxy network	3000
LETSENCRYPT_DOMAIN	Domain for which to generate the certificate	git.example.com
LETSENCRYPT_EMAIL	E-Mail for receiving important account notifications (mandatory)	admin@example.com
DB_NAME	Name for the database	gitea
DB_USER	User for the database	gitea
DB_PASSWD	Password for the database	gitea

Images

• 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:9.6: PostgreSQL docker image version 9.6 on docker hub.

Containers

• 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.

Volumes

Local

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

Named

• 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

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

docker-compose up -d

Documentation

• If you find any problems please fill out an issue. Thank you!

Contributing

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

License

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