5.5 KiB
Gitea Multi‑Instance on Ubuntu 24.04
Install multiple Gitea instances on Ubuntu 24.04 server.
This is not a demo environment. This is a production-focused installer built to scale cleanly and update centrally.
Why this installer exists
Running several Gitea installations shouldn't require manual setup each time. This script makes multi-instance hosting repeatable.
What this installer does
✔ Auto-numbers instances (gitea1, gitea2 …) ✔ Creates isolated DB + service per instance ✔ Assigns final ports safely post-install ✔ Includes robots + sitemap generation ✔ Shared binary — one upgrade updates all
What this installer does NOT do
It won’t stop you from running the script without reading the documentation like there’s no tomorrow. Skip the README, and whatever happens next is your headache, not a bug report.
Requirements
You must already have:
✔ Nginx installed
✔ MariaDB/MySQL running
✔ Port 3000 free during install (temporary only)
Optional Installers (if you need them — saves you some googling)
1. Download
git clone https://git.x-files.dk/webapps/gitea-ubuntu-multi.git
cd gitea-ubuntu-multi
2. Install a new instance
sudo ./giteainstall-multi -n <domain> -p <dbpassword> [options]
Examples
Socket auth present:
sudo ./giteainstall-multi -n git1.example.com -p gitea1pwd
No socket → use DB credentials:
sudo ./giteainstall-multi -n git2.example.com -p pass2 -m rootpwd
Flags
| Option | Meaning |
|---|---|
-p password |
DB password for the new Gitea instance |
-m password |
Admin/root MariaDB password (if no socket) |
-a username |
Admin DB user (default = root) |
-h |
Help screen |
How instances are created
Each install assigns the next instance number automatically:
| Instance | User | DB | Config | Service | Final Port |
|---|---|---|---|---|---|
| 1 | gitea1 | gitea1db | /etc/gitea1 | gitea1.service | 3001 |
| 2 | gitea2 | gitea2db | /etc/gitea2 | gitea2.service | 3002 |
| 3 | gitea3 | gitea3db | /etc/gitea3 | gitea3.service | 3003 |
Temporary installer UI runs at http://domain:3000
Final port assigned after postinstall.
Complete setup
- Visit:
http://<domain>
-
Finish the web installer WITHOUT changing port.
-
Run the postinstall unique to this instance:
sudo /etc/giteaX/gitea-postinstall
(X = instance number)
That step:
✔ moves Gitea from 3000 → final assigned port
✔ configures logging, UI, paging, themes
✔ disables SSH by default
✔ updates Nginx proxy target
File Layout (auto-increment per instance)
When first installed, paths look like this:
Instance 1
| Path | Purpose |
|---|---|
/etc/gitea1/app.ini |
Main config file |
/etc/gitea1/gitea-postinstall |
Postinstall script |
/var/lib/gitea1/ |
Data, repos, indexers, logs |
/var/lib/gitea1/custom/templates/ |
UI overrides |
/var/lib/gitea1/custom/public/assets/img/ |
Logos + branding |
/var/lib/gitea1/custom/public/ |
robots + sitemap (optional) |
/usr/local/bin/gitea |
Shared binary |
Instance 2 (identical structure, next number auto-assigned)
| Path | Purpose |
|---|---|
/etc/gitea2/app.ini |
Main config file |
/etc/gitea2/gitea-postinstall |
Postinstall script |
/var/lib/gitea2/ |
Data, repos, indexers, logs |
/var/lib/gitea2/custom/templates/ |
UI overrides |
/var/lib/gitea2/custom/public/assets/img/ |
Logos + branding |
/var/lib/gitea2/custom/public/ |
robots + sitemap (optional) |
/usr/local/bin/gitea |
Shared binary |
Every new install increments automatically (
gitea3,gitea4,gitea5…)
Important (but optional):
robots.txtandsitemap.xmlare supported automatically by the Nginx configuration being created, however the installer does not generate these files. Create them manually in the directory listed above.
HTTPS
Use the TLS template here:
https://git.x-files.dk/webserver/nginx-snippets/src/branch/main/hostfiles/gitea.443.conf
Then update in /etc/giteaX/app.ini:
ROOT_URL = https://<domain>
Restart:
systemctl restart giteaX nginx
Version Handling
Script checks latest from:
https://dl.gitea.com/gitea/version.json
Fallback file contains static version:
fallback
1.25.2
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| Nginx restart fails | Bad config | nginx -t |
| DB denied | No socket | Add -m (and -a) |
| Blank web UI | Service down | systemctl status giteaX |
| Next instance reusing port | Postinstall not run | Run /etc/giteaX/gitea-postinstall |
More Information
More guides and documentation can be found on wiki.x-files.dk
License
Licensed under the MIT License.