5.0 KiB
Gitea Multi‑Instance on Ubuntu 24.04
Deploy multiple isolated Gitea servers on Ubuntu 24.04 — each with its own:
✔ service
✔ database
✔ config
✔ data directory
✔ port
All instances share one Gitea binary — upgrades are single-file replacements.
This is a production installer, not a test script.
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.