Kennisbank

Gitea is a lightweight, self-hosted Git service — a much lower-resource alternative to GitLab, ideal for individuals and small teams who want private repository hosting without GitLab's heavier resource requirements.

Gitea vs GitLab

Prerequisites

• Docker Engine and Docker Compose installed
• A domain name (recommended)

Step 1 — Create a Project Directory

mkdir ~/gitea && cd ~/gitea

Step 2 — Create docker-compose.yml

services:
  gitea:
    image: gitea/gitea:latest
    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:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: gitea
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  gitea_data:
  postgres_data:

Port 222 is mapped for Git-over-SSH, avoiding conflict with the host's own SSH on port 22.

Step 3 — Start Gitea

docker compose up -d

Step 4 — Complete Setup in the Browser

http://YOUR_SERVER_IP:3000

Follow the installation wizard, confirming database settings match your compose file.

Step 5 — Add HTTPS

See How to Install Nginx Proxy Manager with Docker to route your domain to port 3000.

Cloning a Repository via SSH

git clone ssh://[email protected]:222/username/repo.git

Setting Up Gitea Actions (Built-In CI/CD)

Enable Actions in the admin panel, then register a runner following Gitea's official runner documentation — conceptually similar to GitHub Actions, using YAML workflow files in your repositories.

Creating Your First Repository

1. Click + → New Repository
2. Configure name, visibility, and initial settings
3. Push existing code, or clone the empty repo to start fresh

Backing Up Gitea

docker exec gitea-gitea-1 gitea dump -c /data/gitea/conf/app.ini
docker exec gitea-db-1 pg_dump -U gitea gitea > gitea-db-backup.sql

Common Errors

Can't push via SSH — verify you're using port 222 (or whatever port you mapped), not the default port 22.

Database connection fails on first setup — confirm the database service name (db) matches exactly what's referenced in GITEA__database__HOST.

Best Practices

• Use a separate SSH port for Git operations to avoid conflicting with host SSH
• Enable HTTPS via a reverse proxy for the web interface
• Back up both the data volume and database regularly

Continue Reading

• How to Install GitLab CE on a VPS
• How to Install Docker Compose on Ubuntu & Debian
• How to Install Nginx Proxy Manager with Docker

Browse more articles in Popular Self-Hosted Applications.