Gitea

Overview

Gitea is a lightweight, self-hosted Git service that provides repository management, issue tracking, and CI/CD integration through Woodpecker CI. This document covers the deployment and configuration of Gitea using Docker Compose with Traefik as a reverse proxy.

Service Details

Component	Value
URL	https://git.trymondo.com
Main Image	gitea/gitea:1.23.7-rootless
Database	PostgreSQL 17.4
Containers	gitea, gitea-db
SSH Port	2222 (via Traefik)
Networks	gitea-net, traefik-net
Time Zone	America/Denver

Architecture

The deployment consists of:

Gitea Server: The main application container running the Git service
PostgreSQL Database: Persistent storage for all Gitea data
Traefik Integration: Handles routing, SSL termination, and SSH proxying

                 ┌─────────────┐
                 │   Traefik   │
                 └─────────────┘
                   ↑         ↑
      HTTP/HTTPS ┌─┘         └─┐ SSH
                 │             │
         ┌──────────────┐    ┌─────────────┐
         │ Gitea Server │◄───┤ Gitea SSH   │
         └──────────────┘    └─────────────┘
                 ▲
                 │
         ┌──────────────┐
         │  PostgreSQL  │
         └──────────────┘

Prerequisites

Docker Engine (24.0+)
Docker Compose v2
Traefik reverse proxy configured and running
External networks: gitea-net and traefik-net
SSH entrypoint configured in Traefik
DNS configured for git.trymondo.com

Deployment Configuration

Environment Variables

Create a .env file with the following variables:

GITEA_DB_PASSWORD=secure_password_here
POSTGRES_PASSWORD=secure_password_here

Never commit the .env file to version control. Store passwords securely in a password manager.

Docker Compose File

services:
  server:
    image: gitea/gitea:1.23.7-rootless
    container_name: gitea
    restart: unless-stopped
    volumes:
      - gitea-data:/var/lib/gitea
      - gitea-config:/etc/gitea
    environment:
      - TZ=America/Denver
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${GITEA_DB_PASSWORD}
    depends_on:
      - db
    networks:
      - gitea-net
      - traefik-net
    labels:
      - traefik.enable=true
      - traefik.http.routers.gitea.rule=Host(`git.trymondo.com`)
      - traefik.http.routers.gitea.entrypoints=websecure
      - traefik.http.routers.gitea.tls.certresolver=production
      - traefik.http.services.gitea.loadbalancer.server.port=3000
      - traefik.tcp.routers.gitea-ssh.rule=HostSNI(`*`)
      - traefik.tcp.routers.gitea-ssh.entrypoints=ssh
      - traefik.tcp.routers.gitea-ssh.service=gitea-ssh
      - traefik.tcp.services.gitea-ssh.loadbalancer.server.port=2222
      - 'diun.enable=true'

  db:
    image: postgres:17.4
    container_name: gitea-db
    restart: unless-stopped
    environment:
      - TZ=America/Denver
      - POSTGRES_DB=gitea
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - gitea-db-data:/var/lib/postgresql/data
    networks:
      - gitea-net
    labels:
      - 'diun.enable=true'

volumes:
  gitea-data:
  gitea-config:
  gitea-db-data:

networks:
  gitea-net:
    external: true
  traefik-net:
    external: true

Network Configuration

Before deployment, ensure the required networks exist:

# Create external networks if they don't exist
docker network create gitea-net
docker network create traefik-net

Deployment Instructions

Create the deployment directory:
mkdir -p /opt/apps/gitea

Create the docker-compose.yml and .env files:

nano /opt/apps/gitea/docker-compose.yml
nano /opt/apps/gitea/.env

Deploy the service:

cd /opt/apps/gitea
docker compose up -d

Verify the service is running:
docker compose ps

Traefik Integration Details

HTTP Routing

Gitea’s web interface is available through HTTPS:

Host Rule: git.trymondo.com
Entrypoint: websecure (HTTPS)
TLS: Enabled with production certificate resolver
Backend Port: 3000

SSH Routing

Git SSH operations are handled through Traefik’s TCP router:

Rule: HostSNI(*) - accepts all hostnames for SSH
Entrypoint: ssh (TCP port typically 2222)
Service: gitea-ssh
Backend Port: 2222

Users will need to configure their Git client to use port 2222 for SSH operations: git clone ssh://git@git.trymondo.com:2222/username/repo.git

Initial Configuration

After deploying Gitea, complete the setup through the web interface:

Access https://git.trymondo.com in your browser
You’ll be redirected to the installation page
Configure the following settings:

Database Settings

Database Type: PostgreSQL (pre-configured)
Host: db:5432 (pre-configured)
Username: gitea (pre-configured)
Password: [value from .env file] (pre-configured)
Database Name: gitea (pre-configured)

Application General Settings

Site Title: GitMondo (recommended)
Repository Root Path: /var/lib/gitea/repositories (default)
Git LFS Root Path: /var/lib/gitea/lfs (default)
Run As Username: git (default)
SSH Server Domain: git.trymondo.com
SSH Server Port: 2222
Gitea HTTP Listen Port: 3000 (default)
Gitea Base URL: https://git.trymondo.com/
Log Path: /var/lib/gitea/log (default)

Email Settings (Optional)

SMTP Host: smtp.mailersend.net
SMTP Port: 587
From Email: info@trymondo.com
SMTP Username: [your SMTP username]
SMTP Password: [your SMTP password]

Administrator Account

Create an initial administrator account with secure credentials

Maintenance

Backup Strategy

Back up Gitea regularly using the following steps:

Stop the Gitea container (keep the database running):
docker compose stop server

Back up volumes:

# Use Restic or another backup tool to back up these volumes:
# - gitea-data
# - gitea-config
# - gitea-db-data

Restart Gitea:
docker compose start server

Consider using Backrest to automate regular backups of Gitea’s volumes.

Updates

To update Gitea:

Update the image tag in docker-compose.yml

Apply the update:

docker compose pull
docker compose up -d

Check logs for any issues:
docker compose logs -f server

Troubleshooting

Database Connection Issues

If Gitea can’t connect to the database:

Verify PostgreSQL container is running:
docker compose ps db
Check database logs:
docker compose logs db

Test database connection:

docker compose exec db psql -U gitea -d gitea -c "SELECT 1;"

SSH Connection Problems

If Git SSH operations fail:

Verify Traefik is properly routing SSH traffic:

# Check if port 2222 is open
telnet git.trymondo.com 2222

Check Gitea’s SSH settings:

# View SSH configuration
docker compose exec server cat /etc/gitea/app.ini | grep SSH

Verify user’s SSH configuration:

# Example ~/.ssh/config entry for users
Host git.trymondo.com
    Port 2222
    User git

Monitoring

Gitea and its database have Diun labels for container update monitoring:

labels:
  - 'diun.enable=true'

Additional Resources

Integration with CI/CD

For CI/CD integration with Woodpecker CI, see the DevOps Stack documentation.

Introduction

Applications

Infrastructure

Overview

Service Details

Architecture

Prerequisites

Deployment Configuration

Environment Variables

Docker Compose File

Network Configuration

Deployment Instructions

Traefik Integration Details

HTTP Routing

SSH Routing

Initial Configuration

Database Settings

Application General Settings

Email Settings (Optional)

Administrator Account

Maintenance

Backup Strategy

Updates

Troubleshooting

Database Connection Issues

SSH Connection Problems

Monitoring

Additional Resources

Integration with CI/CD

​Overview

​Service Details

​Architecture

​Prerequisites

​Deployment Configuration

​Environment Variables

​Docker Compose File

​Network Configuration

​Deployment Instructions

​Traefik Integration Details

​HTTP Routing

​SSH Routing

​Initial Configuration

​Database Settings

​Application General Settings

​Email Settings (Optional)

​Administrator Account

​Maintenance

​Backup Strategy

​Updates

​Troubleshooting

​Database Connection Issues

​SSH Connection Problems

​Monitoring

​Additional Resources

​Integration with CI/CD

Overview

Service Details

Architecture

Prerequisites

Deployment Configuration

Environment Variables

Docker Compose File

Network Configuration

Deployment Instructions

Traefik Integration Details

HTTP Routing

SSH Routing

Initial Configuration

Database Settings

Application General Settings

Email Settings (Optional)

Administrator Account

Maintenance

Backup Strategy

Updates

Troubleshooting

Database Connection Issues

SSH Connection Problems

Monitoring

Additional Resources

Integration with CI/CD