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)
Installers if needed:
https://git.x-files.dk/webserver/nginx-ubuntu
https://git.x-files.dk/database/mariadb-ubuntu
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
| Path | Purpose |
|---|---|
/etc/giteaX/ |
Config directory |
/etc/giteaX/gitea-postinstall |
Per‑instance finalize script |
/var/lib/giteaX/ |
Repos + data |
/etc/giteaX/custom/templates |
Override UI templates |
/etc/giteaX/custom/public/assets/img |
Logos + branding |
/usr/local/bin/gitea |
Shared Gitea binary |
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.