> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymondo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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:

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
```

<Warning>
  Never commit the `.env` file to version control. Store passwords securely in a
  password manager.
</Warning>

### Docker Compose File

```yaml theme={null}
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:

```bash theme={null}
# 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:

   ```bash theme={null}
   mkdir -p /opt/apps/gitea
   ```

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

   ```bash theme={null}
   nano /opt/apps/gitea/docker-compose.yml
   nano /opt/apps/gitea/.env
   ```

3. Deploy the service:

   ```bash theme={null}
   cd /opt/apps/gitea
   docker compose up -d
   ```

4. Verify the service is running:
   ```bash theme={null}
   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

<Note>
  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`
</Note>

## 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/](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](mailto: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):

   ```bash theme={null}
   docker compose stop server
   ```

2. Back up volumes:

   ```bash theme={null}
   # Use Restic or another backup tool to back up these volumes:
   # - gitea-data
   # - gitea-config
   # - gitea-db-data
   ```

3. Restart Gitea:
   ```bash theme={null}
   docker compose start server
   ```

<Tip>
  Consider using Backrest to automate regular backups of Gitea's volumes.
</Tip>

### Updates

To update Gitea:

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

2. Apply the update:

   ```bash theme={null}
   docker compose pull
   docker compose up -d
   ```

3. Check logs for any issues:
   ```bash theme={null}
   docker compose logs -f server
   ```

## Troubleshooting

### Database Connection Issues

If Gitea can't connect to the database:

1. Verify PostgreSQL container is running:

   ```bash theme={null}
   docker compose ps db
   ```

2. Check database logs:

   ```bash theme={null}
   docker compose logs db
   ```

3. Test database connection:
   ```bash theme={null}
   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:

   ```bash theme={null}
   # Check if port 2222 is open
   telnet git.trymondo.com 2222
   ```

2. Check Gitea's SSH settings:

   ```bash theme={null}
   # View SSH configuration
   docker compose exec server cat /etc/gitea/app.ini | grep SSH
   ```

3. Verify user's SSH configuration:
   ```bash theme={null}
   # 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:

```yaml theme={null}
labels:
  - 'diun.enable=true'
```

## Additional Resources

* [Official Gitea Documentation](https://docs.gitea.com/)
* [Gitea Container Documentation](https://docs.gitea.com/installation/install-with-docker)
* [PostgreSQL Documentation](https://www.postgresql.org/docs/)
* [Traefik TCP Routing Documentation](https://doc.traefik.io/traefik/routing/services/#configuring-tcp-services)

## Integration with CI/CD

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