Gitea: How to Painlessly Self-Host Your Organization's Source Code
by The Inedo Team, on Aug 1, 2022 6:45:00 AM
Is “the public cloud” really the best place for your source code?
According to Gartner, over 90% of organizations plan to embrace hybrid- or multi-cloud strategies to mitigate the risks of “putting all your eggs in one basket”. Many are starting to do the same with their source control - and you've probably been thinking the same.
However, when you evaluate alternatives to “the public cloud” for your source code, you'll keep running into the huge, complex, bulky, and expensive platforms that don't seem to really be designed for self-management. Fortunately, Gitea is a great alternative.
We’ll also discuss Gitea best practices including:
When you’re evaluating a self-hosted Git server for source control, the first decision to make is the type of tool:
- Monolithic Development Platform that has "Git repositories" as one of its many features (e.g. GitLab)
- Dedicated Git Server that focuses on self-hosted source control (e.g. Gitea)
There are a lot of reasons why a Monolith Development Platform may be the wrong choice, especially if you only need self-hosted Git source control. But the most compelling reason is complexity and the cost of maintenance.
Monoliths like GitLib Enterprise have a very complicated architecture and rely operating system services like Redis, Gitaly, PostgreSQL, and Sidekiq to function. While it’s relatively easy to install these using the provisioning scripts they provide, maintaining the installation of all of these components - plus the monolithic platform itself - is complex, especially if you’re not a Linux expert. This isn’t surprising, considering that monolith platforms are primarily hosted, software-as-a-service tools, and supporting self-hosted isn’t their primary objective.
Gitea, on the other hand, bills itself as “a painless self-hosted Git service” - and as we’ll show you in this article, that’s very accurate. For example, Gitea is just a single executable file, and uses just a single data directory to back-up.
While Gitea isn't the only dedicated Git Server, it is by far the most popular and is quickly becoming the dominant choice.
Challenges with Gitea
Although Gitea has all of the features most teams will need in a source control repository, users familiar with a different repository may find the navigation unfamiliar. It may be missing some “nice to have” things, but Gitea is very actively maintained - and those features will be added, and the product will continue to evolve with the rest of the tools on the market.
The main objection to Gitea is the limited commercial support. However, this is where the simplicity of Gitea really shines – and you may actually be better off without commercial support.
Gitea is very easy to install and maintain, and you likely won’t run into issues. But when you do, you can quickly find an answer from support forums or chatrooms. It’s probably something others have run into, and if not - the Gitea maintainers themselves will quickly help get it resolved. This has been their hobby and passion for nearly a decade.
Monoliths, on the other hand, are much more complex – and have a lot more things that can go wrong. Running into an issue will very likely require a support interaction, which means filling out a ticket, or scheduling a call with your account manager. Because self-hosting is not their primary business, your ticket will likely be routed to specialized, senior engineer for help, and prioritized and addressed during normal business hours at the pace of large business.
Gitea is just a single, executable file. That’s it!
That makes installation an absolute breeze on Linux or Windows:
- Install git
- Download gitea binary executable
- Register the gitea executable as a service/daemon
- Run initial configuration
There are lots of guides for how to install Gitea on Linux (including installing Gitea on Ubuntu), and the Windows guidance is starting to catch-up.
Gitea will run on all modern versions of Windows, and has very minimum system requirements: 2 CPU cores and 1GB RAM is typically sufficient for small teams/projects, and you can scale up as needed.
Before installing Gitea, make sure to install the git client tools on the server.
Download the gitea executable
There are a few Windows-specific downloads in the Gitea download center, but the one you’ll most likely want is
gitea-<latest-version>-windows-4.0-amd64.exe. This file is for all modern versions of Windows.
You can install Gitea to any location, but C:\gitea is generally suggested.
Register Gitea as a Windows Service
The Gitea Windows Service instructions detail this step, but it really just involves using sc.exe to register the service.
sc.exe create gitea start=auto binPath="“C:\gitea\gitea.exe” web --config “C:\gitea\custom\conf\app.ini”"
Optional: Creating a User Account
While not required, it’s generally recommended to use limited-access user accounts to run Windows services. The above command will default to using LocalSystem, which has administrative privileges.
If you do use a different account to run the service, you’ll need to give that user account read access to
C:\gitea\** and read-write access to the
Run Initial Gitea Configuration
When you first run Gitea, there will likely be no configuration file in the location you specified (e.g.
C:\gitea\custom\conf\app.ini from the command earlier). As such, Gitea will run in “initial configuration” mode to help you set-up the service for the first time.
To perform the initial configuration, simply navigate to the default Gitea web interface at
http://localhost:3000 and configure the following items.
Select database engine to use, and optionally configure file paths (or use the defaults). The built-in sqllite database is adequate for nearly all use cases. We do not recommend using SQL Server, as it's not officially supported yet and has been reported as being very buggy.
Create initial user account, which will be like the root account of the service.
After saving the initial configuration, you can then edit the created configuration file. The Gitea configuration file cheat sheet documents all of the settings, but there are two we recommend setting:
[server] ROOT_URL = https://my.git.server.com (set to actual url of your server)
[service] DISABLE_REGISTRATION = false (prevent anonymous new user creation)
Disabling registration is recommended if you plan to integrate with Active Directory, which is also recommended on Windows.
Although not technically required for Gitea itself, using git without https – even internally – is difficult. While Gitea has support for ACME built-in, it’ll be easiest on Windows to configure IIS as a reverse proxy.
Microsoft’s guide for Reverse Proxy with URL Rewrite v2 and Application Request Routing has some great guidance on how to that if you haven’t before.
Gitea provides a lot of authentication options, and you can configure it to integrate with your Active Directory.
The easiest way to integrate with your domain is by leveraging “LDAP via Bind DN”. This mostly refers to how you configure the settings. For example, instead of specifying a login user like you may be used to (
mycompany/admin), you will need to specify “distinguished names” like
CN=Admin,DN=mycompany,DN=local as well as configure specific LDAP paths and queries.
There’s a bit of a learning curve to BindDN, and it may require a bit of trial and error. Before configuring Active Directory in Gitea, make sure that you have a domain user account that can perform searches. While you can use any user with permission, it’s best to maintain a special purpose, limited access account. For example,
searcher as the password.
You’ll first need to find the distinguished name for your search user. To do this, make sure the advanced tools are enabled by navigating to Active Directory Users & Groups > “View” > “Advanced Features”. Then, navigate to your user, use the right-click menu to go to properties, click the “Attribute Editor” tab, then finally look for the
distinguishedName property. It will look something like
Next, you’ll need the distinguished name for the organizational unit you wish to search. You can find this in the same manner under Active Directory Users & Groups by right-clicking on the OU object instead. The
distinguishedName for an OU will look something like
Once you’ve gathered those values, navigate to Site Administration > Authentication Source, and add a new LDAP (via BindDN).
- Authentication Name can the friendly name of your domain, like MyCompany
- Security Protocol should be Unencrypted for regular LDAP, or LDAPS if you’ve configured that already
- Host should be your domain suffix , not the LDAP server. E.g.
- Port should be 389 (default for LDAP) or 636 (default for LDAPS)
- Bind DN should be the
distinguishedNameof your search user, such as
- Bind Password should be that password, like
- User Search Base should be the
distinguishedNameof your OU, such as
- User Filter should be
- Admin Filter is optional, but can be based on the
distinguishedNameof a group Like
- Username Attribute should be
- First Name Attribute should be
- Surname Attribute should be
- Email Attribute should be
These settings may vary from domain to domain. But once configured, users will be able to login with their domain email address or domain username.
One of the major advantages to using lightweight, dedicated tools in a toolchain is that it’s relatively easy to try different tools and discover what works best for your team. While changing tools is easy, it’s not trivial. In addition to training and process changes, data migration will often a consideration before trying new tools.
Fortunately, Git repositories are self-contained and have a history of all code changes, including a trail of all commits, merges, and the people who made those changes. This means that when you migrate a git repository from one tool to another, all of that history will remain intact.
Migrating a Repository Using the Gitea UI
Gitea has a built-in migration tool that can migrate from any Git service. Simply navigate to “New Migration”, and you’ll be presented with a list of options such as the repository name on Gitea, the URL of the repository you want to clone, etc.
If you’re migrating from GitLab and GitHub, Gitea will provide options to migrate milestones, releases, issues, etc. Other settings like the default branch, permissions, protected branches, tag restrictions, etc. may not be migrated, and are things you’ll want to set-up in the Gitea repository.
Creating a Migration Plan With Repository Mirroring
When evaluating and migrating to a new tool, it’s best to do so incrementally and in parallel. That is, use both tools for a little while, perhaps only on a few projects, and plan to slowly migrate away from the old as you use the new.
Gitea has a feature called repository mirroring that makes this staged migration easy. You can configure a Gitea repository to pull or push commits to another Git repository. This allows you to:
- Start with Gitea in “read-only” mode, and pull changes from your current source control repository. This will let developers see the new UI and make sure some of your automations (build servers, etc.) will still work.
- Provisionally swap to Gitea and push changes to your current source control repository. This involves setting the current repository to “read only”, and instruct developers on how to push to Gitea instead. It's really just a new URL.
- Decommission the old source control server, once you’re satisfied.
If you have a lot of repositories to migrate, it may be easier to write a script to migrate them.
The easiest way to go about this would be to use the Gitea API to create a blank repository, and then use the Git command-line to clone repositories from your existing service into Gitea:
git clone --mirror «url to old repository»
git remote set-url origin «url to new gitea repository»
git push --mirror origin
You can also use the Gitea API to set things like default branches, permissions, mirroring, etc.
Gitea provides thorough backup and restore documentation.
The backup strategy that you’ll use will depend on the operating system, whether you’ve opted for an external database, and how you’ve configured the paths that Gitea uses.
At an absolute minimum, there are two things you’ll need to back-up:
- Configuration file, which defaults to
- Data directory, which defaults to
«gitea-directory»/dataand includes the database, git repositories, avatars, issue attachments, etc.
Backing up Gitea on Windows
On Windows, it’s easiest to just back-up the entire Gitea folder (i.e.
c:\gitea) using your preferred backup tool, and save enough snapshots to mitigate file corruption and accidental data deletion risks.
Virtually all backup tools will leverage Window’s Volume Shadow Copy Services, which means that you can just keep Gitea running while the backup proceeds.
However, if you’re using an external database like PostgreSQL or MySQL, it’s advised to shutdown Gitea so that the files and databases are synchronized during back-up.
Although Gitea has never been “field tested” to scale to millions of users that GitHub.com supports, a Gitea instance configured to run as a load-balanced server or Kubernetes cluster and it can scale to more users than you would ever need.
A single-server instance of Gitea can easily support up to 1,000 users with normal developer usage. And with powerful hardware, you can support even more. For example, Codeberg, an emerging platform for open-source development, has over 10,000 users on just a single server.
The reason that Gitea works so well is two-fold.
- Git itself is efficient at transferring data, and users will be uploading and downloading a relatively small number of commits against each repository
- Gitea mostly transfers files and doesn't need to write to its internal database very often, which means concurrency issues almost never occur
Bottlenecks with Gitea
If you’re using git to exclusively transfer large, non-code assets like videos, or using Gitea as some sort of CDN, then you’ll likely run into network bottlenecks. This is when you should consider load balancing.
If you’re heavily relying on Gitea’s commenting features and posting thousands of issue comments or pull request comments each day, then you may run into database slowness issues. However, migrating to an external database may resolve that.
Scaling with Federation
Instead of moving towards a load-balanced or clustered configuration to support more usage, you will likely be better served with multiple, single-server instances of Gitea. This is called "federation" - and it's something that's becoming more and more popular in large organizations.
Federation allows you to delegate the administration of Gitea instances along organizational groups, and then create a "federated governance" structure. This means that you'll require that the groups have certain features enabled (security, etc.), and you can even write a script to verify those features. But, otherwise let them try different ways to managing Gitea.
One group may find a that a plug-in or customization adds a lot of value – and then other groups can simply follow that usage. This federated approach increases organizational agility overall.
In addition, managing a handful of single-instances will generally be much easier than managing a cluster of servers. And lower risk. Especially when it comes time to rolling out upgrades.
Gitea’s repository mirroring makes it relatively easy to replicate critical Git repositories so that teams can still work at minimal capacity until the production environment is back up and running.
For developers, the most critical capability to restore is the ability to read/download code. Even if they can’t share/upload their code to the repository right away, they won’t be blocked from working on changes locally. This is why a two-stage disaster recovery plan is generally preferred for source control.
To prepare for this scenario, you’ll need to set-up a second Gitea server in your disaster recovery environment (
drgit.company.local) and configure the critical repositories to pull changes from the production environment (
Disaster Stage One: Read-only for Hours
When disaster strikes, you just need to change your DNS to have
drgit.company.local be the new
git.company.local. Within minutes, users will be able to access all repositories again, but will get errors if they try to push changes.
Once the production environment is restored, just change the DNS back and users will be able to read and write again. Some may never have even realized that there was a disaster.
Disaster Stage Two: Temporary Environment for Days
If you need to use the disaster recovery environment for the long haul, then simply disable repository mirroring and allow push access. This could work indefinitely.
When you’re ready to go back to the production environment, you’ll need to come up with a plan for migrating all of the changes that were pushed to the disaster recovery server.
The easiest approach is to :
- Configure your production server to mirror changes from disaster recovery
- Alert users of downtime
- Set all disaster recovery repositories to read-only
- Wait until all mirroring is complete
- Disable mirroring configuration on production
- Change DNS
Monolithic Development Platforms like GitHub, GitLab, and Azure DevOps are wildly popular because they’re easy to get started. But they’re not for everyone. A lot of organizations aren’t comfortable with their software supply chain being in “the public cloud” , and many prefer to use a suite of tools that meet their evolving needs instead of following the Monolithic way.
Gitea is great option for these organizations because it’s focused on just being a single, easy-to-manage tool in software supply chain. It’s rapidly growing in popularity as a result of this, and will continue to improve as the community grows.