Gitea Cluster
You set up a gitea cluster by running multiple app nodes behind a load balancer. Each node shares one SQL database and one storage pool for Git repos. Teams often build this setup to keep code online when one server fails. They also add nodes to handle heavy clone traffic from build jobs. Yet fast growth often leads to broad admin roles across these servers. When too many engineers hold root or database keys, one mistake can break the cluster. How a gitea cluster architecture works A standar
Cluster: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up a gitea cluster by running multiple app nodes behind a load balancer. Each node shares one SQL database and one storage pool for Git repos.
Teams often build this setup to keep code online when one server fails. They also add nodes to handle heavy clone traffic from build jobs. Yet fast growth often leads to broad admin roles across these servers. When too many engineers hold root or database keys, one mistake can break the cluster.
How a gitea cluster architecture works
A standard single server keeps all repo files, logs, and queues on one local disk. When you move to a gitea cluster, you must pull all state out of the nodes. Every app node must stay stateless so any server can answer any user request.
First, you place a load balancer in front of your app servers. This balancer routes web traffic and SSH Git pushes to healthy nodes. Next, you point all app nodes to one central relational database. The database holds user accounts, pull requests, issues, and repo metadata.
Then, you set up shared storage for the actual Git data and attachments. Teams often use a network file system for the bare Git repos. They also use object storage for large files, avatars, and release packages. All nodes must read and write to the exact same file paths.
Finally, you must sync background jobs, session data, and local caches across the nodes. Without shared queues and caches, one node might miss an update made on another node. Once you share the database, storage, and queues, the cluster acts as one system.
How team roles and permissions work across nodes
Gitea includes built-in role controls for teams, teams, and individual repos. Admins can grant read, write, or admin rights to specific groups of developers. Because all nodes read from the same database, a role change applies everywhere at once.
Cluster: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Still, managing a cluster requires access below the web app level. Platform engineers need SSH access to the host machines to check system logs. They also need direct database accounts to fix stuck migrations or check slow queries. Shared storage systems also require admin keys for backups and disk resizing.
Teams often share static SSH keys or broad database passwords to speed up maintenance. These shared secrets sit on laptops and in team password vaults for months. Soon, anyone with host or database access can bypass the web app rules entirely.
What native cluster setups leave open
Native app roles do a great job of controlling Git pushes and pull requests. They decide who can log in to the web app and view specific codebases. The shared database enforces these rules across every node in the fleet.
Yet native app roles do nothing to control direct host or database sessions. Once an engineer logs in to a cluster node or database, native controls stop. The system only checks who logs in at the start of the session. It does not check what individual commands or SQL statements do in flight.
An engineer fixing a slow query can accidentally drop a table in the shared database. A developer reading production logs can see raw emails or phone numbers in error traces. Static host keys also leave no clear record of who ran which shell command. To run a safe cluster, you need controls at the command and query level.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Can I run a gitea cluster without shared file storage?
No, every app node needs direct read and write access to the same Git repos. While you can store avatars and attachments in object storage, Git repos need a shared file system.
How do I handle SSH Git operations across multiple nodes?
Your load balancer must forward SSH traffic to the backend app nodes on the right port. All nodes must also share the same host SSH keys so user clients do not show warnings.
Why do database sessions matter for Git server security?
The central database holds all user tokens, webhook secrets, and repo permission mappings. Anyone with direct write access to the database can grant themselves admin rights or read private data.