Loading Now
WordPress

How to Install Gitea on Ubuntu Using Docker

How to Install Gitea on Ubuntu Using Docker

Deploying Gitea on Ubuntu with Docker is one of the simplest methods to establish a lightweight, self-hosted Git service, sidestepping complicated installation processes. Gitea serves as a reliable alternative to platforms like GitLab and GitHub, offering version control with an intuitive interface, issue tracking, and collaboration features, while giving users complete oversight of their repositories. This guide will walk you through the process of installing Gitea using Docker containers, configuring it appropriately, and addressing common troubleshooting scenarios.

Understanding Gitea and Its Functionality

Gitea is a community-driven iteration of Gogs, crafted in Go, and aimed at being a lightweight yet robust Git hosting solution. Unlike heavy alternatives such as GitLab, Gitea operates efficiently on basic hardware while still offering crucial functionalities like pull requests, issue tracking, project wikis, and tools for organisational management.

The architecture consists of three layers: a web interface facilitated by Go’s templating system, a Git backend to manage repository tasks, and a database layer (SQLite, MySQL, or PostgreSQL) for metadata storage. When hosted via Docker, Gitea operates in an isolated container environment, simplifying the management of dependencies, updates, and backups.

Main technical benefits include:

  • Minimal memory usage (generally between 50-100MB RAM)
  • Integrated SSH server for Git operations
  • Support for Git LFS (Large File Storage)
  • RESTful API for automation and integration
  • Support for multiple database backends

Comparing Gitea with Alternatives

Feature Gitea GitLab CE Gogs GitHub Enterprise
Memory Consumption 50-100MB 4GB+ 30-50MB 8GB+
Integrated CI/CD Gitea Actions (from v1.19) Yes Yes
Docker Registry Yes Yes Yes
License Type MIT MIT/Enterprise MIT Proprietary
Development Activity High Very High Low High

Necessary Prerequisites and System Specifications

Prior to installation, make sure your Ubuntu system adheres to the following requirements:

  • Ubuntu 18.04 LTS or later (tested on versions 20.04 and 22.04)
  • At least 1GB of RAM (2GB recommended for multiple users)
  • Docker Engine version 20.10 or higher and Docker Compose v2
  • Minimum of 10GB available disk space
  • A non-root user with sudo rights

To install Docker, if it’s not already set up:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Comprehensive Installation Instructions

Method 1: Fast Setup with a Single Container

If you’re testing or have a small team, a single-container setup will suffice:

mkdir -p /opt/gitea/{data,config}
sudo chown -R 1000:1000 /opt/gitea

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 2222:22 \
  -v /opt/gitea/data:/data \
  -v /etc/timezone:/etc/timezone:ro \
  -v /etc/localtime:/etc/localtime:ro \
  gitea/gitea:latest

Method 2: Full Setup with Docker Compose

For a production setting, employ Docker Compose together with a dedicated database. Begin by creating a docker-compose.yml file:

version: "3.8"

services:
  gitea:
    image: gitea/gitea:1.21
    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=gitea_password
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db

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

networks:
  gitea:
    external: false

Deploy the stack with:

docker compose up -d

Initial Configuration and Setup Steps

To access the initial setup wizard, navigate to http://your-server-ip:3000. Key configuration aspects include:

  • Database Configuration: For the compose setup, database fields should auto-fill
  • server Domain: Enter your actual domain or IP address
  • SSH server Port: Change to 2222 (as the container port 22 maps to host 2222)
  • HTTP Port: Maintain at 3000 or alter if using a reverse proxy
  • Application URL: Ensure it matches your real access URL

Create the primary admin user during the setup, as changing this post-setup without database manipulation is complex.

Advanced Configurations and Customisation

The configuration for Gitea is located in /data/gitea/conf/app.ini. Key settings for production use are:

[server]
DOMAIN = your-domain.com
SSH_DOMAIN = your-domain.com
ROOT_URL = https://your-domain.com/
DISABLE_SSH = false
SSH_PORT = 2222
LFS_START_SERVER = true

[security]
INSTALL_LOCK = true
SECRET_KEY = your-secret-key-here
INTERNAL_TOKEN = your-internal-token

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
ENABLE_CAPTCHA = true

[mailer]
ENABLED = true
FROM = [email protected]
MAILER_TYPE = smtp
HOST = smtp.your-provider.com:587
USER = your-smtp-user

After any configuration changes, restart the container with:

docker restart gitea

Setting Up Nginx as a Reverse Proxy

For production instances, it’s advisable to use Nginx as a reverse proxy. Install and set it up as follows:

sudo apt install nginx certbot python3-certbot-nginx

# Create Nginx configuration
sudo nano /etc/nginx/sites-available/gitea

Add this configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_max_body_size 512M;
    }
}

Enable the site and acquire SSL:

sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d your-domain.com

Practical Use Cases and Scenarios

Small Development Team (5-10 developers): A single-container deployment with an SQLite database, utilising 512MB RAM and managing over 100 repositories efficiently.

Enterprise Setup: Multi-container deployment featuring PostgreSQL, Redis caching, and external storage integration. Adequate for 100+ concurrent users with appropriate resource allocation.

CI/CD Integration: Gitea Actions, akin to GitHub Actions, can be configured for automated testing and deployment:

# .gitea/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      - run: go test ./...

Troubleshooting Common Issues

Problems with SSH Cloning: The most frequent issue is confusion regarding the SSH port. Users should set up their Git client as follows:

# ~/.ssh/config
Host your-domain.com
    Port 2222
    User git

Permission Issues: Ensure correct ownership of data directories:

sudo chown -R 1000:1000 /opt/gitea/data
# Check the container logs for permission issues
docker logs gitea

Database Connection Problems: Confirm database accessibility and credentials:

# Check database connection from the container
docker exec -it gitea sh
# Inside the container:
nc -zv db 5432

Memory Issues: Monitor resource consumption and adjust as required:

docker stats gitea
# Limit memory if necessary
docker update --memory=1g gitea

Best Practices and Security Measures

  • Regular Backups: Frequently back up both the data directory and database
  • Update Approach: Test updates in a staging environment before moving to production
  • Network Security: Implement firewall rules to limit access to essential ports
  • Enforce HTTPS: Always utilise SSL certificates in production settings
  • User Management: Disable public registration and implement SSO where feasible
  • Resource Surveillance: Establish monitoring for disk space, RAM, and database efficiency

Example Backup Script:

#!/bin/bash
# Back up Gitea data and database
BACKUP_DIR="/backup/gitea/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# Back up data directory
tar -czf $BACKUP_DIR/gitea-data.tar.gz /opt/gitea/data

# Back up database (PostgreSQL)
docker exec gitea-db pg_dump -U gitea gitea > $BACKUP_DIR/gitea-db.sql

# Keep only the most recent 7 days of backups
find /backup/gitea -type d -mtime +7 -exec rm -rf {} \;

Performance monitoring can be facilitated using the Prometheus metrics endpoint available at /metrics, once enabled in configuration.

For further details and advanced configuration alternatives, refer to the official Gitea documentation at https://docs.gitea.io/ and the Docker Hub repository at https://hub.docker.com/r/gitea/gitea.

This article draws on information and resources from several online sources. We acknowledge and value the efforts of all original authors, publishers, and websites. Every effort has been made to appropriately attribute the source material; any inadvertent oversights do not constitute copyright infringement. All trademarks, logos, and images referenced are properties of their respective owners. If you believe any content used in this article violates your copyright, please reach out to us for review and prompt action.

This article serves solely for informational and educational purposes and does not infringe upon copyright owners’ rights. If any copyrighted material has been improperly credited or used in violation of copyright laws, it is unintentional, and we will correct it upon notification. Please note that republishing, redistributing, or reproducing any part of the contents in any form is prohibited without explicit written consent from the author and website owner. For permissions or other inquiries, please contact us.

Related Posts