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

​

Architecture

The deployment consists of:

1. Gitea Server: The main application container running the Git service
2. PostgreSQL Database: Persistent storage for all Gitea data
3. 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

​

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

1. Create the deployment directory:

   mkdir -p /opt/apps/gitea
   

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

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

3. Deploy the service:

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

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

​

Initial Configuration

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

1. Access https://git.trymondo.com in your browser
2. You’ll be redirected to the installation page
3. 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:

1. Stop the Gitea container (keep the database running):

   docker compose stop server
   

2. Back up volumes:

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

3. Restart Gitea:

   docker compose start server
   

​

Updates

To update Gitea:

1. Update the image tag in docker-compose.yml

2. Apply the update:

   docker compose pull
   docker compose up -d
   

3. Check logs for any issues:

   docker compose logs -f server
   

​

Troubleshooting

​

Database Connection Issues

If Gitea can’t connect to the database:

1. Verify PostgreSQL container is running:

   docker compose ps db
   

2. Check database logs:

   docker compose logs db
   

3. Test database connection:

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

​

SSH Connection Problems

If Git SSH operations fail:

1. Verify Traefik is properly routing SSH traffic:

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

2. Check Gitea’s SSH settings:

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

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

• Official Gitea Documentation
• Gitea Container Documentation
• PostgreSQL Documentation
• Traefik TCP Routing Documentation

​

Integration with CI/CD

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