Skip to content
Klutch.sh Docs

Deploying Gitea

Introduction

Gitea is a painless, self-hosted Git service that provides a lightweight yet powerful alternative to platforms like GitHub, GitLab, and Bitbucket. Written in Go, Gitea is designed to be easy to install, fast to run, and simple to maintain, making it an ideal choice for teams and organizations seeking complete control over their code repositories.

Gitea excels at:

  • Lightweight Performance: Minimal resource requirements with excellent speed and responsiveness
  • Complete Git Hosting: Full-featured repository management with branching, merging, and version control
  • Issue Tracking: Built-in issue tracker with labels, milestones, and project boards
  • Pull Requests & Code Review: Comprehensive code review workflow with inline comments and approval processes
  • Wiki & Documentation: Integrated wiki for project documentation
  • Organizations & Teams: Multi-level permission system with organization and team management
  • Third-Party Integrations: Webhooks, API access, and integration with external tools
  • Migration Tools: Easy migration from GitHub, GitLab, Bitbucket, and other Git services
  • CI/CD Integration: Native support for Gitea Actions and external CI/CD pipelines
  • Multilingual Support: Available in over 30 languages

Common use cases include private code hosting, team collaboration, open-source project management, DevOps pipelines, and enterprise source control.

This comprehensive guide walks you through deploying Gitea on Klutch.sh using Docker, including detailed installation steps, configuration options, persistent storage setup, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Gitea deployment project:

Terminal window
mkdir gitea-klutch
cd gitea-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Gitea container configuration:

FROM gitea/gitea:1.21


# Expose the default Gitea HTTP port
EXPOSE 3000


# Expose the SSH port for Git operations
EXPOSE 22


# The container will use the official Gitea entrypoint
# Data will be stored in /data (should be mounted as a persistent volume)

Note: The Gitea official image is well-optimized and includes everything needed to run Gitea in production.

Step 3: (Optional) Create a Custom Configuration File

For advanced configurations, you can create a custom app.ini file. Create a file named app.ini:

# app.ini - Custom Gitea Configuration
# This file can be placed in /data/gitea/conf/ in your container


[server]
APP_NAME = My Gitea Instance
DOMAIN = example-app.klutch.sh
HTTP_PORT = 3000
ROOT_URL = https://example-app.klutch.sh/
DISABLE_SSH = false
SSH_PORT = 22
START_SSH_SERVER = true
OFFLINE_MODE = false


[database]
DB_TYPE = sqlite3
PATH = /data/gitea/gitea.db


[repository]
ROOT = /data/git/repositories
DEFAULT_BRANCH = main


[security]
INSTALL_LOCK = false
SECRET_KEY =
INTERNAL_TOKEN =


[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL = false
DEFAULT_KEEP_EMAIL_PRIVATE = true
DEFAULT_ALLOW_CREATE_ORGANIZATION = true
NO_REPLY_ADDRESS = noreply.example.com


[mailer]
ENABLED = false


[openid]
ENABLE_OPENID_SIGNIN = false
ENABLE_OPENID_SIGNUP = false


[log]
MODE = console
LEVEL = info
ROOT_PATH = /data/gitea/log

Note: The initial setup wizard will guide you through configuration on first launch, so this file is optional. Most settings can be configured through the web interface.

Step 4: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Gitea setup locally:

Terminal window
# Build the Docker image
docker build -t my-gitea .


# Run the container with volume mounts
docker run -d \
  --name gitea-test \
  -p 3000:3000 \
  -p 2222:22 \
  -v gitea-data:/data \
  my-gitea


# Access Gitea in your browser
# Open http://localhost:3000


# Stop and remove the test container when done
docker stop gitea-test
docker rm gitea-test
docker volume rm gitea-data

Step 5: Push to GitHub

Commit your Dockerfile to your GitHub repository:

Terminal window
git add Dockerfile
git commit -m "Add Gitea Dockerfile for Klutch.sh deployment"
git remote add origin https://github.com/yourusername/gitea-klutch.git
git push -u origin main

Connecting to Gitea

Once deployed, you can access your Gitea instance through your web browser and via Git operations.

Web Interface Access

Navigate to your Klutch.sh app URL in a web browser:

https://example-app.klutch.sh

Replace example-app.klutch.sh with your actual Klutch.sh app URL.

On first access, you’ll be presented with the Gitea installation wizard where you can:

  • Configure database settings (SQLite is pre-configured and recommended for small to medium deployments)
  • Set up the administrator account
  • Configure server and application settings
  • Customize email and authentication options

Git Operations via HTTPS

Clone repositories using HTTPS:

Terminal window
git clone https://example-app.klutch.sh/username/repository.git
cd repository


# Configure your Git credentials
git config user.name "Your Name"
git config user.email "your.email@example.com"


# Make changes and push
git add .
git commit -m "Initial commit"
git push origin main

Git Operations via SSH

For SSH access, you’ll connect through port 8000 on Klutch.sh, which routes to the internal SSH port (22):

Terminal window
# Add your SSH public key to Gitea through the web interface first
# Then clone repositories using SSH


git clone ssh://git@example-app.klutch.sh:8000/username/repository.git

Note: Configure your SSH client to use port 8000 for Gitea connections:

Terminal window
# Add to ~/.ssh/config
Host example-app.klutch.sh
    User git
    Port 8000
    IdentityFile ~/.ssh/id_rsa

Deploying to Klutch.sh

Now that your Gitea project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Gitea Server”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (for web interface access)
      • Internal Port: Set to 3000 (the default Gitea HTTP port that your container listens on)

      Note: If you need SSH access for Git operations, you’ll need to create a separate app configuration with TCP traffic type on port 22, or use HTTPS for Git operations which works through the same HTTP endpoint.

    6. Set Environment Variables (Optional)

      You can customize Gitea’s behavior with environment variables:

      • USER_UID: User ID for the git user (default: 1000)
      • USER_GID: Group ID for the git user (default: 1000)
      • GITEA__database__DB_TYPE: Database type (default: sqlite3)
      • GITEA__server__DOMAIN: Your domain name (e.g., example-app.klutch.sh)
      • GITEA__server__ROOT_URL: Full URL to your Gitea instance (e.g., https://example-app.klutch.sh/)

      Note: Most configuration is better done through the web interface during initial setup or by editing the app.ini file in your persistent volume.

    7. Attach a Persistent Volume

      This is critical for ensuring your repositories, database, and configuration persist across deployments:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /data (this is where Gitea stores all data including repositories, database, and configuration)
      • Size: Choose an appropriate size based on your expected repository storage needs (start with at least 10GB, scale up as needed)

      Important: Gitea stores all critical data in the /data directory:

      • /data/git/repositories - Git repositories
      • /data/gitea/gitea.db - SQLite database (if using SQLite)
      • /data/gitea/conf/app.ini - Configuration file
      • /data/gitea/log - Application logs
      • /data/gitea/indexers - Search indexes

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your workload (minimum 512MB RAM recommended, 1GB or more for production with multiple users)
      • Instances: Start with 1 instance (Gitea handles concurrency well on a single instance)

    9. Deploy Your Gitea Instance

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Gitea container
      • Assign a URL for access

    10. Complete Initial Setup

      Once deployment is complete, navigate to your app URL (e.g., https://example-app.klutch.sh). You’ll be greeted with the Gitea installation wizard:

      • Database Settings: Keep the default SQLite3 for simplicity (or configure PostgreSQL/MySQL if you have an external database)
      • General Settings:
        • Set your application name
        • Configure the Server Domain (your Klutch.sh app URL without https://)
        • Set the Gitea Base URL (full URL including https://)
      • Administrator Account: Create your admin user credentials
      • Click “Install Gitea” to complete setup

    11. Access Your Gitea Instance

      After installation, you can:

      • Log in with your administrator credentials
      • Create organizations and teams
      • Create repositories
      • Invite users
      • Configure webhooks and integrations
      • Import existing repositories from GitHub, GitLab, or other services

Production Best Practices

Security Recommendations

  • Strong Administrator Password: Use a secure, unique password for your admin account
  • User Registration: Consider disabling public registration in production (DISABLE_REGISTRATION = true)
  • Two-Factor Authentication: Enable 2FA for all user accounts, especially administrators
  • HTTPS Only: Klutch.sh provides HTTPS by default; ensure ROOT_URL uses https://
  • SSH Key Management: Educate users on proper SSH key management and rotation
  • Regular Updates: Keep Gitea updated to the latest stable version for security patches
  • Private Repositories: Set repositories to private by default for sensitive code
  • Access Tokens: Use personal access tokens instead of passwords for API access
  • Webhook Secrets: Always configure webhook secrets for third-party integrations

Performance Optimization

  • Database Choice: SQLite3 is fine for small teams (< 50 users); consider PostgreSQL or MySQL for larger deployments
  • Repository Mirroring: Use Gitea’s mirroring feature judiciously as it can impact performance
  • Indexing: Enable repository indexing for better search performance
  • Caching: Gitea includes built-in caching; configure cache settings in app.ini for optimal performance
  • Compute Resources: Monitor CPU and memory usage; scale up resources as your team and repository count grows
  • Git LFS: Configure Git Large File Storage (LFS) for repositories with large binary files

Backup Strategy

Your persistent volume on Klutch.sh contains all critical Gitea data. Implement a backup strategy:

  • Database Backups: Regularly backup /data/gitea/gitea.db (for SQLite) or your external database
  • Repository Backups: The /data/git/repositories directory contains all Git repositories
  • Configuration Backup: Backup /data/gitea/conf/app.ini for configuration recovery
  • Full Volume Backup: Consider periodic backups of the entire /data directory
  • Test Restores: Regularly test your backup restoration process

Monitoring

Monitor your Gitea instance for:

  • Repository count and total storage size
  • Active user count and concurrent sessions
  • CPU and memory utilization
  • Disk space usage (especially for the persistent volume)
  • Failed authentication attempts
  • API rate limiting and abuse
  • Webhook delivery success rates
  • Git operation response times

Advanced Configuration

Customizing Gitea with Nixpacks Environment Variables

If you need to customize how Gitea starts or runs, you can use Nixpacks environment variables in Klutch.sh:

To change the start command:

  • Add environment variable: NIXPACKS_START_CMD
  • Value: Your custom start command (e.g., /usr/local/bin/gitea web --config /data/gitea/conf/app.ini)

To set buildtime variables:

  • Add environment variable: NIXPACKS_BUILD_CMD
  • Value: Your custom build commands

Note: For most Gitea deployments, the default Docker image configuration is sufficient and doesn’t require Nixpacks customization.

Email Configuration

To enable email notifications for issues, pull requests, and password resets, configure the [mailer] section in /data/gitea/conf/app.ini:

[mailer]
ENABLED = true
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 587
FROM = noreply@yourdomain.com
USER = your-email@gmail.com
PASSWD = your-app-password

After updating the configuration, restart your Gitea app in the Klutch.sh dashboard.

External Database Configuration

For production deployments with many users, consider using an external PostgreSQL or MySQL database:

  1. Deploy a separate database instance (see the Postgres guide)
  2. During Gitea setup, select PostgreSQL or MySQL as the database type
  3. Provide the database connection details (host, port, username, password, database name)
  4. Ensure the persistent volume is still attached for repositories and configuration

OAuth and SSO Integration

Gitea supports authentication via:

  • OAuth 2.0 providers (GitHub, GitLab, Google, etc.)
  • LDAP/Active Directory
  • SAML 2.0

Configure these through the Gitea admin panel under Site Administration → Authentication Sources.

Troubleshooting

Cannot Access Gitea Web Interface

  • Verify your app URL is correct and the deployment is running
  • Check that the internal port is set to 3000 in your Klutch.sh app configuration
  • Ensure the traffic type is set to HTTP
  • Check the container logs in Klutch.sh dashboard for any startup errors

Git Clone/Push Operations Failing

  • For HTTPS operations, verify the repository URL is correct
  • Ensure your Git credentials are correct
  • For SSH operations, verify your SSH key is added to your Gitea user profile
  • Check that the SSH port configuration in your ~/.ssh/config uses port 8000

Installation Wizard Not Appearing

  • If you see a blank page or error, check that the persistent volume is properly mounted at /data
  • Verify the volume has sufficient space allocated
  • Check container logs for database initialization errors

Database Connection Errors

  • If using SQLite, ensure the persistent volume is mounted correctly at /data
  • If using external database, verify connection details and network connectivity
  • Check database credentials and ensure the database exists

Repositories Not Persisting

  • Verify the persistent volume is correctly attached at /data
  • Check volume permissions (Gitea runs as UID 1000 by default)
  • Ensure sufficient disk space is allocated to the volume

Performance Issues

  • Check CPU and memory usage in Klutch.sh dashboard
  • Consider upgrading compute resources if limits are reached
  • Review the number of repositories and active users
  • Consider switching from SQLite to PostgreSQL for better performance with many users
  • Check for large repositories that might benefit from Git LFS

Migration Issues

  • When migrating from GitHub or other services, ensure you have proper API tokens
  • Large repositories may take time to import; be patient during migration
  • Verify network connectivity to external Git services during migration

Additional Resources

Conclusion

Deploying Gitea to Klutch.sh with Docker provides a powerful, self-hosted Git service with complete control over your code repositories. With persistent storage, you maintain all repositories, issues, pull requests, and wiki content across deployments. Gitea’s lightweight design and rich feature set make it an excellent choice for teams of any size seeking an alternative to cloud-based Git hosting platforms. Your Gitea instance is now ready to host your code, facilitate collaboration, and power your DevOps workflows.