Gitea: Self-Hosted GitHub Alternative on Your Home Server (2026)

Git is the engine of modern software development, but you don't need to rely on a third-party platform for your private repositories. Gitea is a lightweight, painless way to bring that power in-house. This guide will walk you through deploying your own feature-rich, self-hosted Git server using Docker, tailored for the resource-conscious home lab.

What It Is and Why Self-Host It

Gitea is a community-driven, open-source Git hosting service written in Go. Think of it as a self-contained alternative to GitHub, GitLab, or Bitbucket that you can run on your own hardware. It provides a familiar web interface for repository management, issue tracking, pull requests, wikis, and more.

Self-hosting Gitea offers several compelling advantages, especially for the home server enthusiast:

• Data Sovereignty & Privacy: Your code, issues, and collaboration data stay on your hardware, behind your firewall. You control the backup strategy and access logs.
• Independence & Uptime: You're not subject to a SaaS platform's pricing changes, feature deprecations, or outages. Your server's uptime is your own.
• Cost-Effective at Scale: For private repositories, especially with multiple collaborators, self-hosting can be significantly cheaper than paid tiers of cloud platforms.
• Offline Development & CI: Your entire development workflow—version control, code review, and CI/CD (via Gitea Actions)—can function without an internet connection, perfect for homelab experimentation.
• Learning & Integration: It's a fantastic platform to learn DevOps, CI/CD pipelines, and internal tooling. You can tightly integrate it with other self-hosted services on your network.

For a home server focused on low power consumption, Gitea is an ideal candidate. Its single binary, Go-based architecture is inherently efficient, requiring minimal CPU and memory overhead compared to heavier alternatives like GitLab.

Prerequisites

Before proceeding, ensure your system meets the following requirements:

1. A Linux Server: This guide assumes a Debian/Ubuntu or Raspberry Pi OS (for ARM) base, but any modern Linux distribution with Docker will work.
2. Docker & Docker Compose: Gitea will run in a container. You must have Docker Engine and Docker Compose (v2 plugin is recommended) installed.
3. Domain or Local DNS (Optional but Recommended): For a polished experience, have a domain name (e.g., git.yourhomeserver.net) or local DNS entry pointing to your server's IP. For purely local use, you can use the server's IP address.
4. Basic Command-Line Comfort: You should be comfortable using a terminal, editing configuration files with nano or vim, and managing Linux services.
5. Port Access: Ensure ports 80 (HTTP), 443 (HTTPS), and 22 (SSH - optional, see configuration) on your server are accessible from your network.

Docker Compose Installation

We'll use Docker Compose to manage Gitea and its database (SQLite for simplicity, or PostgreSQL for heavier use). This method isolates the service and simplifies updates and backups.

First, create a dedicated directory and the docker-compose.yml file.

mkdir -p ~/docker/gitea
cd ~/docker/gitea
nano docker-compose.yml

Paste the following complete configuration. This setup uses SQLite for ease, binds-mounts for data persistence, and includes a reverse proxy (Caddy) for automatic HTTPS. Replace all placeholder values (your-user, your-password-here, git.yourdomain.com) with your own.

version: '3.8'

services:
  caddy:
    image: caddy:2-alpine
    container_name: gitea_caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "2222:22" # Maps host port 2222 to container port 22 for SSH.
    environment:
      - CADDY_INGRESS_NETWORKS=gitea_network
    volumes:
      - ./caddy_data:/data
      - ./caddy_config:/config
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    networks:
      - gitea_network

  server:
    image: gitea/gitea:latest
    container_name: gitea_server
    restart: unless-stopped
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=sqlite3
      - GITEA__database__PATH=/data/gitea/gitea.db
      - GITEA__server__DOMAIN=git.yourdomain.com
      - GITEA__server__SSH_PORT=22
      - GITEA__server__SSH_LISTEN_PORT=22
      - GITEA__server__ROOT_URL=https://git.yourdomain.com
    volumes:
      - ./gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - /home/your-user/.ssh/authorized_keys:/data/git/.ssh/authorized_keys:ro # For SSH key passthrough
    networks:
      - gitea_network
    depends_on:
      - caddy

networks:
  gitea_network:
    external: false

Next, create the Caddyfile for the reverse proxy configuration:

nano Caddyfile

git.yourdomain.com {
    log {
        output file /data/access.log
    }
    reverse_proxy server:3000
}

Finally, create the necessary directories and start the stack:

mkdir -p gitea_data caddy_data caddy_config
sudo docker compose up -d

The services will start. Gitea will be available shortly at http://git.yourdomain.com (or your server's IP). The first visit will trigger the initial configuration wizard.

Initial Configuration

The web-based installation wizard appears on first launch. Here are the key settings:

1. Database Settings: Leave them as-is (SQLite3, /data/gitea/gitea.db). Our Docker Compose file already configured this via environment variables.
2. General Settings:
   • Site Title: Your instance's name (e.g., "Home Git").
   • Repository Root Path: /data/git/repositories (default, inside the container).
   • SSH Server Port: 22 (default, but note: the SSH traffic is routed through the Caddy container on host port 2222).
   • Gitea HTTP Listen Port: 3000 (default).
3. Server & Third-Party Settings:
   • Domain: git.yourdomain.com (must match your ROOT_URL).
   • SSH Server Domain: git.yourdomain.com.
   • SSH Port: 2222 (This is the host port you expose to the outside world. Crucial for correct git clone URLs).
   • Gitea Base URL: Should auto-populate as https://git.yourdomain.com.
4. Administrator Account: Create your first admin user. Do not use admin as the username for security. Use a strong password.

After clicking "Install Gitea," you'll be logged in and ready to go.

Key Features & How to Use Them

Gitea packs a surprising number of features. Let's break down the most useful ones.

Repository Management

Creating and cloning repositories works exactly like GitHub. You can make them public, private, or internal (visible to all logged-in users). The web interface provides a rich code viewer, file editor, and commit history browser.

SSH Key Authentication

To push/pull code via SSH (on port 2222), add your public SSH key.

1. Click your profile picture > Settings > SSH / GPG Keys.
2. Paste your public key (cat ~/.ssh/id_ed25519.pub) and give it a title.
3. Clone a repository using the SSH URL provided:

   git clone ssh://git@git.yourdomain.com:2222/username/repo-name.git
   

Mirroring External Repositories

This killer feature lets you create a local, synchronized copy of a repository from GitHub, GitLab, etc.

1. Click + > New Repository.
2. Check "This repository will be a mirror".
3. Enter the Clone Address (e.g., https://github.com/go-gitea/gitea.git).
4. Set a Mirror Interval (e.g., every 8 hours). Gitea will automatically pull the latest changes, keeping your local copy in sync.

Issues, Pull Requests, and Wikis

These collaborative tools function nearly identically to their GitHub counterparts. You can manage milestones, labels, assignees, and templates. Wikis use Markdown and are a great place for project documentation.

Gitea Actions (CI/CD)

Gitea has a built-in CI/CD system compatible with GitHub Actions syntax. To enable it:

1. Go to Site Administration > Actions > Settings.
2. Enable "Enable Actions".
3. You need a "Runner." For your home server, the easiest is to set up an act_runner as a service. Create a runner token in the admin panel, then deploy the runner (simplest via Docker). See the official documentation for detailed setup.
4. Create a .gitea/workflows/build.yaml (or .github/workflows/...) file in your repository to define your pipeline (e.g., build with Go, deploy via SSH).

Package Registries

Gitea can act as a private registry for various package types, a fantastic feature for homelab development.

• Container Registry (OCI): Push/pull Docker images directly to your Gitea instance (e.g., docker push git.yourdomain.com/username/project/image:tag).
• Others: It also supports npm, Maven, PyPI, NuGet, and Composer registries.

Performance on Low-Power Hardware

Gitea's efficiency makes it an excellent fit for low-power servers like the Intel N100 mini-PCs or Raspberry Pi 5. Below is a realistic snapshot of resource usage under typical loads (5-10 users, ~50 repositories, periodic Actions runs).

Key Takeaways:

• Memory is Minimal: Gitea itself is light. Most memory will be used by the database and, if enabled, the Actions runner.
• I/O is Critical: Repository operations (clone, fetch, Actions) are I/O intensive. Using an SSD over an SD card or slow HDD is the single biggest performance upgrade.
• Database Choice: SQLite is perfectly adequate for a home server with a handful of active users and is simpler to back up. Switch to a PostgreSQL container if you experience database locks under very high concurrent access (unlikely in a homelab).
• Actions Runner: The act_runner consumes additional resources only when a workflow is executing. You can limit its parallelism in the runner config to avoid overwhelming your system.

Tips & Best Practices

1. Automated Backups: Your data lives in the ./gitea_data volume. Regularly back it up.

   # Simple backup script (run via cron)
   cd ~/docker/gitea
   tar -czf /path/to/backups/gitea-backup-$(date +%s).tar.gz gitea_data/
   

2. Use SSH Key Passthrough: The Docker Compose example mounts your host's SSH authorized_keys. This allows users to reuse their existing host SSH keys for Gitea authentication without manually adding them to the Gitea web UI (advanced setup).
3. Secure with Fail2ban: Gitea logs failed login attempts. Install fail2ban on your host and configure a jail for Gitea to block brute-force attacks.
4. Schedule Mirror Updates: Use Gitea's built-in cron or your host's systemd timers to force mirror updates at specific times, reducing random load spikes.
5. Separate Actions Runner: Run the act_runner on a different machine or as a separate container with resource limits (docker compose deploy.resources) to isolate CI/CD workload from the main Gitea service.
6. Leverage Webhooks: Integrate Gitea with other self-hosted services like Discord, Matrix, or a custom dashboard by setting up webhooks for push, issue, and pull request events.

Troubleshooting

• Gitea won't start (Docker logs show permission errors): Ensure the USER_UID and USER_GID in your docker-compose.yml match your host user's IDs (check with id -u and id -g).
• "git clone" over SSH hangs or fails on port 22: You are likely using the wrong port. Remember, the host exposes SSH on 2222. Your clone URL must be ssh://git@git.yourdomain.com:2222/.... Check the SSH Port setting in Administration > Settings > General.
• "Repository not found" on push, but web UI shows it: Almost always an SSH key issue. Verify the key is added to your Gitea account and that you are using the correct user account for the repository.
• High memory usage over time: The Go garbage collector can be lazy. A scheduled restart of the container (e.g., weekly via docker compose restart server) can help. Consider adding -e GITEA__performance__ENABLED=true to environment variables for more aggressive GC.
• Caddy fails to get HTTPS certificates: Ensure port 80/443 is forwarded to your server from your router and that your domain's DNS A/AAAA record correctly points to your public IP. For local-only use, remove the Caddy service and access Gitea directly on port 3000.

Conclusion

Gitea delivers a powerful, professional-grade Git hosting experience with a fraction of the resource footprint of its competitors. For the home server enthusiast, it represents the perfect sweet spot: it’s lightweight enough to run silently on a Raspberry Pi in a closet, yet robust enough to handle serious collaborative development, complete with modern CI/CD.

By following this guide, you’ve not only gained control over your code but also built a cornerstone for a wider self-hosted development ecosystem. From here, you can integrate it with your Docker registry, continuous deployment pipelines, and project management tools, all within the privacy and limits of your own network. The power—and now the repository—is in your hands.