High Availability Deployment

This guide shows how to deploy Gitea Enterprise in a highly available (HA) topology. HA keeps code hosting online when a node fails by running multiple application instances behind a load balancer and offloading state to shared services.

1. Prerequisites

• At least two application nodes (Linux VMs, bare-metal, or Kubernetes workloads) with outbound access to the shared services below.
• An external database cluster (MySQL/MariaDB or PostgreSQL) that provides its own replication or managed high availability.
• A Redis/Redis cluster deployment for cache, session, task queues and globalLock.
• A Elastic Search deployment for code search if enabled
• Shared non-git-repository storage: either an S3-compatible bucket or a POSIX volume (NFS/Gluster/NetApp) mounted at the same path on every node.
• Shared git repository storage: a POSIX volume (NFS/Gluster/NetApp) mounted at the same path on every node.
• A load balancer that can forward HTTP/HTTPS (port 3000/443) and SSH (port 22/222) traffic with health checks.

Follow Install on Linux, Install with Docker, or Install on Kubernetes for per-node provisioning. The HA-specific steps below build on top of those guides.

2. Bootstrap the first application node

1. Install the Enterprise binary or container following the single-node guide of your choice.
2. During configuration set APP_DATA_PATH to the shared storage mount (/data).
3. Update /data/gitea/conf/app.ini (or the equivalent environment variables) with HA-friendly settings:

APP_NAME = Gitea Enterprise
RUN_MODE = prod

[server]
DOMAIN               = git.example.com
ROOT_URL             = https://git.example.com/
PROTOCOL             = http
HTTP_PORT            = 3000
SSH_DOMAIN           = git.example.com
SSH_PORT             = 222
LANDING_PAGE         = explore
LFS_START_SERVER     = true
LFS_JWT_SECRET       = <shared secret>

[database]
DB_TYPE  = mysql
HOST     = db.internal:3306
NAME     = gitea
USER     = gitea
PASSWD   = <password>

[session]
PROVIDER         = redis
PROVIDER_CONFIG  = redis://:<password>@redis.internal:6379/0?pool_size=100&idle_timeout=120s

[cache]
ADAPTER = redis
HOST    = redis://:<password>@redis.internal:6379/1

[queue]
TYPE          = redis
CONN_STR      = redis://:<password>@redis.internal:6379/2

[storage]
STORAGE_TYPE = minio ; once the storage added, the path on other places should be removed like attachment
; lfs. Use gitea migrate-storage to migrate the original files to the new places if it's a migration
MINIO_BUCKET = gitea-ee-data
MINIO_ENDPOINT = s3.internal:9000
MINIO_ACCESS_KEY_ID = <access>
MINIO_SECRET_ACCESS_KEY = <secret>

[indexer]
ISSUE_INDEXER_TYPE = db, elasticsearch or melllisearch ; bleve will not work for HA mode
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200

REPO_INDEXER_ENABLED = true
REPO_INDEXER_TYPE = elasticsearch
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200

[log]
; please ensure the log path hasn't been shared by different instances

[global_lock]
SERVICE_TYPE = redis
SERVICE_CONN_STR = redis://:<password>@redis.internal:6379/5

3. Add additional nodes

Repeat the installation for every extra node:

1. Reuse the same Enterprise version and configuration files. If you template app.ini, consider using Ansible, Helm, or Terraform to avoid drift.
2. Mount the shared /data volume read/write. When using object storage, only /data/gitea/conf need to stay on shared disk, while repositories live in the bucket.
3. Double-check file permissions (git:git) and confirm that the node can reach the database, Redis, and storage endpoints.
4. Start the service and verify GET /api/healthz returns 200 OK.

4. Configure the load balancer

• Add all healthy nodes to the HTTP/HTTPS pool. If TLS terminates on the balancer, forward X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers so Gitea generates correct URLs.
• Forward SSH traffic via TCP (either a separate VIP or port 222 on the same address). When using Kubernetes, expose SSH with a LoadBalancer service or NodePort plus an external LB.
• Configure health probes against /api/healthz or /api/v1/version. Mark nodes unhealthy if the check fails three times to avoid sending user traffic to a degraded instance.
• Enable connection draining so running git pushes can finish before a node is removed for maintenance.

5. Operations checklist

• Backups: snapshot the database, Redis, and object storage regularly. Follow the upstream backup guide.
• Upgrades: roll nodes one at a time. Drain traffic at the load balancer, stop the service, upgrade the binary or container tag, run migrations (first node only), then re-add it.
• Monitoring: scrape the /metrics endpoint with Prometheus, alert on queue depth, HTTP error rates, and replication lag.
• Disaster recovery: test restoring a node by bootstrapping from the same config plus shared storage. Verify license status and outbound integrations (SMTP, webhooks) afterward.

With these steps, your Gitea Enterprise deployment can survive single-node failures and scale horizontally as your organization grows.