Containr/templates/gitea.md

Gitea Git Hosting Template

Overview

Gitea is a painless self-hosted Git service. It is similar to GitHub, Bitbucket, and GitLab.

Quick Start

# Create docker-compose.yml with the content below
docker-compose up -d

Docker Compose

version: '3.8'

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=gitea-db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
      - GITEA__server__DOMAIN=git.yourdomain.com
      - GITEA__server__ROOT_URL=https://git.yourdomain.com/
      - GITEA__server__SSH_DOMAIN=git.yourdomain.com
      - GITEA__server__SSH_PORT=2222
      - GITEA__server__SSH_LISTEN_PORT=22
      - GITEA__webhook__ALLOWED_HOST_LIST=git.yourdomain.com
      - GITEA__service__DISABLE_REGISTRATION=true
      - GITEA__service__REQUIRE_SIGNIN_VIEW=true
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__FROM=git@yourdomain.com
      - GITEA__mailer__MAILER_TYPE=smtp
      - GITEA__mailer__HOST=smtp.gmail.com:587
      - GITEA__mailer__USER=your-email@gmail.com
      - GITEA__mailer__PASSWD=your-app-password
      - GITEA__security__INSTALL_LOCK=true
      - GITEA__security__SECRET_KEY=your-secret-key
    ports:
      - "2222:22"
      - "3000:3000"
    volumes:
      - gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      - gitea-db
    networks:
      - gitea-network

  gitea-db:
    image: postgres:15-alpine
    container_name: gitea-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=gitea
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
    volumes:
      - gitea-db:/var/lib/postgresql/data
    networks:
      - gitea-network

volumes:
  gitea-data:
  gitea-db:

networks:
  gitea-network:
    driver: bridge

Environment Variables

• USER_UID/USER_GID: User ID for file permissions
• GITEA__database__*: Database configuration
• GITEA__server__*: Server settings
• GITEA__service__*: Service configuration
• GITEA__mailer__*: Email configuration
• GITEA__security__*: Security settings

Setup Guide

1. Generate Secret Key:

   openssl rand -base64 32
   

2. Create Directories:

   mkdir -p gitea-data
   

3. Deploy:

   docker-compose up -d
   

4. Access: Open http://localhost:3000

5. Initial Setup:

   • Create admin account
   • Configure repository settings
   • Set up SSH keys

Configuration

App.ini Configuration

# /data/gitea/conf/app.ini
[database]
DB_TYPE  = postgres
HOST     = gitea-db:5432
NAME     = gitea
USER     = gitea
PASSWD   = gitea

[server]
DOMAIN           = git.yourdomain.com
ROOT_URL         = https://git.yourdomain.com/
SSH_DOMAIN       = git.yourdomain.com
SSH_PORT         = 2222
SSH_LISTEN_PORT  = 22
LFS_START_SERVER = true
LFS_JWT_SECRET  = your-lfs-jwt-secret

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW  = true
ENABLE_NOTIFY_MAIL    = true

[mailer]
ENABLED    = true
FROM       = git@yourdomain.com
MAILER_TYPE = smtp
HOST       = smtp.gmail.com:587
USER       = your-email@gmail.com
PASSWD     = your-app-password

[security]
INSTALL_LOCK = true
SECRET_KEY   = your-secret-key

SSH Configuration

# Add SSH key to Gitea
ssh-keygen -t ed25519 -C "your-email@example.com"

# Add public key to Gitea web interface
# Test SSH connection
ssh -T git@git.yourdomain.com -p 2222

Repository Management

Create Repository

# Create new repository via API
curl -X POST http://localhost:3000/api/v1/user/repos \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","description":"My first repository","private":false}'

Clone Repository

# HTTPS clone
git clone https://git.yourdomain.com/username/my-repo.git

# SSH clone
git clone ssh://git@git.yourdomain.com:2222/username/my-repo.git

Push to Repository

cd my-repo
git init
git add .
git commit -m "Initial commit"
git remote add origin https://git.yourdomain.com/username/my-repo.git
git push -u origin main

User Management

Create User

# Create user via API
curl -X POST http://localhost:3000/api/v1/admin/users \
  -H "Authorization: token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","email":"user@example.com","password":"password","must_change_password":false}'

Organizations

# Create organization
curl -X POST http://localhost:3000/api/v1/orgs \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"myorg","description":"My organization"}'

Actions (CI/CD)

Enable Actions

# In app.ini
[actions]
ENABLED = true

# Create .gitea/workflows/build.yml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
      - name: Build
        run: npm run build

Package Registry

# Publish npm package
npm publish --registry https://git.yourdomain.com/api/packages/npm

# Publish Docker image
docker push git.yourdomain.com/username/my-image:latest

Reverse Proxy (Traefik)

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.gitea.rule=Host(`git.yourdomain.com`)"
  - "traefik.http.routers.gitea.tls=true"
  - "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
  - "traefik.http.services.gitea.loadbalancer.server.port=3000"

Backup Strategy

# Backup Gitea data
docker run --rm -v gitea-data:/data -v $(pwd):/backup alpine tar czf /backup/gitea-backup.tar.gz -C /data .

# Backup PostgreSQL database
docker exec gitea-db pg_dump -U gitea gitea > gitea-db-backup.sql

# Restore database
docker exec -i gitea-db psql -U gitea gitea < gitea-db-backup.sql

# Restore Gitea data
docker run --rm -v gitea-data:/data -v $(pwd):/backup alpine tar xzf /backup/gitea-backup.tar.gz -C /data

# Restart after restore
docker-compose restart gitea

Performance Optimization

# For better performance
environment:
  - GITEA__cache__ENABLED=true
  - GITEA__cache__ADAPTER=redis
  - GITEA__cache__HOST=redis://redis:6379/0
  - GITEA__queue__TYPE=redis
  - GITEA__queue__CONN_STR=redis://redis:6379/1

# Add Redis service
  redis:
    image: redis:7-alpine
    container_name: gitea-redis
    restart: unless-stopped
    volumes:
      - gitea-redis:/data
    networks:
      - gitea-network

Security

SSH Keys

# Generate SSH key pair
ssh-keygen -t ed25519 -C "gitea@yourdomain.com"

# Add to Gitea admin settings
# Configure in app.ini
[ssh]
MINIMUM_KEY_SIZE = 2048
AUTHORIZED_KEYS_ALLOW = true

Access Control

environment:
  - GITEA__service__DISABLE_REGISTRATION=true
  - GITEA__service__REQUIRE_SIGNIN_VIEW=true
  - GITEA__security__LOGIN_REMEMBER_DAYS=30
  - GITEA__security__COOKIE_USERNAME=git
  - GITEA__security__COOKIE_REMEMBER_NAME=gitea_incredible

Two-Factor Authentication

environment:
  - GITEA__security__TWO_FACTOR_ENABLED=true
  - GITEA__security__TWO_FACTOR_REQUIRE_SIGN_IN=true

Monitoring

Health Checks

# Check Gitea health
curl http://localhost:3000/api/v1/version

# Check database connection
docker exec gitea-db pg_isready -U gitea

Logs

# View logs
docker-compose logs -f gitea

# Check specific logs
docker exec gitea tail -f /data/gitea/log/gitea.log

Troubleshooting

• SSH connection issues: Check SSH key configuration
• Database connection: Verify PostgreSQL settings
• Performance problems: Monitor resource usage
• Email issues: Check SMTP configuration
• Repository access: Verify permissions

Maintenance

# Restart services
docker-compose restart

# Update images
docker-compose pull && docker-compose up -d

# Clean up old data
docker exec gitea gitea admin cleanup

# Check repository integrity
docker exec gitea gitea admin repo check

Advanced Features

LFS (Large File Storage)

environment:
  - GITEA__server__LFS_START_SERVER=true
  - GITEA__server__LFS_JWT_SECRET=your-lfs-jwt-secret

# Install LFS client
git lfs install

# Track large files
git lfs track "*.zip"
git add .gitattributes
git commit -m "Add LFS tracking"

Mirror Repositories

# Create mirror
curl -X POST http://localhost:3000/api/v1/repos/migrate \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clone_addr":"https://github.com/user/repo.git","repo_name":"my-mirror","mirror":true}'

Webhooks

# Create webhook
curl -X POST http://localhost:3000/api/v1/repos/username/repo/hooks \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"gitea","config":{"content_type":"json","url":"https://your-domain.com/webhook","events":["push"]}}'

Integration Examples

GitHub Migration

# Migrate from GitHub
curl -X POST http://localhost:3000/api/v1/repos/migrate \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clone_addr":"https://github.com/user/repo.git","repo_name":"repo","service_type":"github","auth_token":"GITHUB_TOKEN"}'

CI/CD Integration

# GitHub Actions compatible workflows
name: CI/CD Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

Package Registry

# Setup npm registry
npm config set registry https://git.yourdomain.com/api/packages/npm

# Login to registry
npm login --registry https://git.yourdomain.com/api/packages/npm

# Publish package
npm publish

Customization

Custom Themes

# In app.ini
[ui]
DEFAULT_THEME = gitea-auto
THEMES = gitea,gitea-auto,gitea-dark

# Custom CSS
[ui.meta]
AUTHOR = Your Name
DESCRIPTION = Your Git Service
KEYWORDS = git,forge,development

Custom Pages

# Custom home page
[ui]
CUSTOM_EMOJIS = :gitea:,:git:
SHOW_MILESTONES_DASHBOARD_PAGE = true
SHOW_ISSUES_SUMMARY_PAGE = true