# Gitea

> Lightweight, self-hosted Git service with a beautiful interface, built-in CI/CD, and painless setup.

- Category: Development Tools
- Difficulty: beginner
- Components: gitea, postgres
- Tags: gitea, git, repository, lightweight, ci-cd, devops
- Source: https://docker.recipes/development/gitea

## Overview

Gitea is a lightweight, self-hosted Git service written in Go that provides a GitHub-like interface for managing Git repositories. Born from a fork of Gogs in 2016, Gitea focuses on being painless to install and run while offering comprehensive features including pull requests, issue tracking, wiki pages, and built-in CI/CD through Gitea Actions. Its minimal resource requirements and straightforward setup make it an ideal choice for teams wanting private Git hosting without the complexity of larger platforms. This deployment configuration creates a robust Git hosting environment using two containerized services: the Gitea application server and a dedicated PostgreSQL database for data persistence. The setup leverages PostgreSQL's reliability and performance for storing repository metadata, user accounts, issues, and configuration data, while the Gitea container handles the web interface, Git operations, and SSH access. The two services communicate over a dedicated Docker network, with Gitea configured to automatically connect to PostgreSQL on startup. This combination provides excellent performance and reliability for teams requiring private code repositories with enterprise-grade database backing. The stack is particularly valuable for development teams, DevOps engineers, and organizations seeking complete control over their source code management while maintaining GitHub-like functionality and user experience.

## Features

- GitHub-like web interface with repository browsing, file editing, and commit history visualization
- Built-in CI/CD through Gitea Actions with GitHub Actions compatibility for existing workflows
- Comprehensive issue tracking system with labels, milestones, and project boards for agile development
- Pull request workflow with code review, inline comments, and merge conflict resolution
- PostgreSQL backend providing ACID compliance and robust data integrity for all Git metadata
- SSH Git access on port 222 alongside HTTPS for flexible repository cloning and pushing
- Package registry support for Docker, npm, PyPI, and other package formats
- Repository migration tools for importing from GitHub, GitLab, and other Git services

## Use cases

- Private Git hosting for software development teams requiring code privacy and control
- DevOps environments needing integrated CI/CD pipelines with GitHub Actions compatibility
- Educational institutions providing Git services for programming courses and student projects
- Open source project hosting for communities wanting self-managed infrastructure
- Enterprise development teams migrating from cloud Git services to on-premises solutions
- Homelab environments for personal project management and portfolio development
- Compliance-sensitive organizations requiring air-gapped or geographically restricted code hosting

## Prerequisites

- Docker and Docker Compose installed on the host system
- Minimum 768MB RAM available (256MB for PostgreSQL, 512MB for Gitea application)
- Ports 3000 (HTTP) and 222 (SSH) available and not conflicting with existing services
- DB_PASSWORD environment variable configured in .env file or system environment
- Basic understanding of Git operations and repository management concepts
- SSH client configured if using SSH-based Git operations on port 222

## docker-compose.yml

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: gitea
      GITEA__database__USER: gitea
      GITEA__database__PASSWD: ${DB_PASSWORD}
    volumes:
      - gitea_data:/data
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: gitea-db
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: gitea
    volumes:
      - gitea_db:/var/lib/postgresql/data

volumes:
  gitea_data:
  gitea_db:
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.gitea.io/
- Access at http://localhost:3000 - setup wizard on first visit
- SSH clone: git clone ssh://git@localhost:222/user/repo.git
- First registered user becomes admin
- Gitea Actions for built-in CI/CD (GitHub Actions compatible)
- Package registry, issue tracker, wiki included

## Troubleshooting

- Gitea shows database connection error: Verify DB_PASSWORD environment variable matches between gitea and db services, check that db container is running and healthy
- SSH Git clone fails on port 222: Ensure port 222 is not blocked by firewall and SSH daemon inside Gitea container is running, verify SSH keys are properly configured in Gitea web interface
- First user registration fails: Check that gitea_data volume has proper write permissions for UID/GID 1000, restart gitea container if database initialization is incomplete
- Gitea Actions workflows not triggering: Verify Gitea Actions is enabled in site administration settings and runners are properly registered and online
- PostgreSQL container fails to start: Check available disk space for gitea_db volume and ensure no other PostgreSQL instances are conflicting with container startup
- Web interface returns 502 Bad Gateway: Confirm gitea container started successfully after database connection was established, check container logs for application startup errors

