You've already forked gitea-ubuntu-multi
docs: clearer README, more user-friendly
This commit is contained in:
262
README.md
262
README.md
@@ -1,212 +1,176 @@
|
||||
# Gitea Multi-Instance for Ubuntu 24.04 Server
|
||||
# Gitea Multi‑Instance on Ubuntu 24.04
|
||||
[](#)
|
||||
[](#)
|
||||
[](#)
|
||||
[](#)
|
||||
[](#)
|
||||
[](#)
|
||||
[](#)
|
||||
[](./LICENSE)
|
||||
|
||||
Automated Bash installer script for deploying **multiple isolated Gitea instances** on Ubuntu 24.04 Server.
|
||||
Deploy **multiple isolated Gitea servers** on Ubuntu 24.04 — each with its own:
|
||||
✔ service
|
||||
✔ database
|
||||
✔ config
|
||||
✔ data directory
|
||||
✔ port
|
||||
|
||||
This is a **production-focused installer**, not a demo.
|
||||
All instances share one Gitea binary — upgrades are **single-file** replacements.
|
||||
|
||||
It assumes Nginx, and either MariaDB or MySQL are already installed and running.
|
||||
|
||||
This script works with both MariaDB and MySQL, with or without socket authentication.
|
||||
This is a **production installer**, not a test script.
|
||||
|
||||
---
|
||||
|
||||
## Related Installers
|
||||
## Requirements
|
||||
|
||||
If you don’t have the required components, you can use these compatible installers:
|
||||
You must already have:
|
||||
|
||||
- [Nginx Installer](https://git.x-files.dk/web-server/nginx-ubuntu)
|
||||
- [MariaDB Installer](https://git.x-files.dk/database-server/mariadb-ubuntu)
|
||||
✔ 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
|
||||
|
||||
---
|
||||
|
||||
> **Important**
|
||||
> Always complete one installation fully (including the `/etc/gitea*/gitea-postinstall` step) before running another.
|
||||
|
||||
---
|
||||
|
||||
### Download the Script
|
||||
Clone this repository to your server:
|
||||
|
||||
```
|
||||
git clone https://git.x-files.dk/web-application/gitea-ubuntu-multi.git
|
||||
```
|
||||
## 1. Download
|
||||
|
||||
```
|
||||
git clone https://git.x-files.dk/webapps/gitea-ubuntu-multi.git
|
||||
cd gitea-ubuntu-multi
|
||||
```
|
||||
|
||||
### Usage
|
||||
Run the script using:
|
||||
---
|
||||
|
||||
## 2. Install a new instance
|
||||
|
||||
```
|
||||
sudo ./giteainstall -n <domain name> -p <gitea database password> [options]
|
||||
sudo ./giteainstall-multi -n <domain> -p <dbpassword> [options]
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
The installer automatically detects if socket authentication is active.
|
||||
Only include `-a` and `-m` if your MariaDB setup does **not** use socket authentication.
|
||||
|
||||
Socket auth present:
|
||||
```
|
||||
sudo ./giteainstall -n git.example.com -p giteadbpass
|
||||
sudo ./giteainstall -n git.example.com -p giteadbpass -m rootpwd
|
||||
sudo ./giteainstall -n git.example.com -p giteadbpass -a admin -m adminpwd
|
||||
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
|
||||
```
|
||||
|
||||
### Options
|
||||
### Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|--------------|
|
||||
| `-p <password>` | Gitea database user password |
|
||||
| `-a <username>` | Optional MariaDB admin username (defaults to `root` if not specified) |
|
||||
| `-m <password>` | MariaDB root or admin password — *required only if socket authentication is disabled* |
|
||||
| `-h`, `--help` | Show the help screen (reflects detected socket status) |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
### Logic
|
||||
## How instances are created
|
||||
|
||||
When you run this script:
|
||||
Each install assigns the **next instance number automatically**:
|
||||
|
||||
- Each Gitea instance created by this script is **fully self-contained**.
|
||||
- Every instance has:
|
||||
- Its own **Linux system user** (e.g., `gitea1`, `gitea2`, `gitea3`, …)
|
||||
- Its own **database** (e.g., `gitea1db`, `gitea2db`, `gitea3db`, …)
|
||||
- Its own **service** (e.g., `gitea1.service`, `gitea2.service`, …)
|
||||
- Its own **home directory** (e.g., `/home/gitea1/`, `/home/gitea2/`, …)
|
||||
- Its own **configuration directory** (e.g., `/etc/gitea1/`, `/etc/gitea2/`, …)
|
||||
- Its own **data path** (e.g., `/var/lib/gitea1/`, `/var/lib/gitea2/`, …)
|
||||
- A unique **HTTP port** automatically assigned during post-install
|
||||
| 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 |
|
||||
|
||||
All instances share the same Gitea binary (`/usr/local/bin/gitea`),
|
||||
so upgrading Gitea is simply replacing that binary once.
|
||||
|
||||
| Instance | System User | Database | Config Dir | Service | Port |
|
||||
|-----------|--------------|-----------|-------------|----------|-------|
|
||||
| 1st | `gitea1` | `gitea1db` | `/etc/gitea1/` | `gitea1.service` | 3001 |
|
||||
| 2nd | `gitea2` | `gitea2db` | `/etc/gitea2/` | `gitea2.service` | 3002 |
|
||||
| 3rd | `gitea3` | `gitea3db` | `/etc/gitea3/` | `gitea3.service` | 3003 |
|
||||
|
||||
Each instance is assigned the next available ID automatically.
|
||||
Temporary installer UI runs at `http://domain:3000`
|
||||
Final port assigned **after postinstall**.
|
||||
|
||||
---
|
||||
|
||||
### Customization
|
||||
Each instance has its own configuration and customization paths:
|
||||
|
||||
| Type | Path |
|
||||
|------|------|
|
||||
| Configuration | `/etc/giteaX/app.ini` |
|
||||
| Custom assets (favicon, logo, etc.) | `/etc/giteaX/custom/public/assets/img/` |
|
||||
| Custom templates | `/etc/giteaX/custom/templates/` |
|
||||
| Data & repositories | `/var/lib/giteaX/` |
|
||||
|
||||
---
|
||||
|
||||
### Configuration
|
||||
Once the script finishes, open your browser and visit:
|
||||
## Complete setup
|
||||
|
||||
1. Visit:
|
||||
```
|
||||
http://<domain>
|
||||
```
|
||||
|
||||
and complete the Gitea setup through the web installer form.
|
||||
2. Finish the web installer WITHOUT changing port.
|
||||
|
||||
---
|
||||
|
||||
### Post-install
|
||||
After the web installer is done run:
|
||||
|
||||
```bash
|
||||
sudo /etc/gitea*/gitea-postinstall
|
||||
```
|
||||
|
||||
This adjusts ports, log levels, upload limits, disables SSH access and other tweaks.
|
||||
|
||||
> **Note**
|
||||
> The web installer always uses temporary port 3000.
|
||||
> The postinstall script automatically reconfigures each instance to its permanent port.
|
||||
|
||||
> SSH is disabled by default after post-install (modify `/etc/gitea*/app.ini` if needed).
|
||||
|
||||
---
|
||||
|
||||
### Nginx Integration
|
||||
|
||||
The generated Gitea configuration file listens on port 80.
|
||||
To enable HTTPS (port 443), use the example provided [here](https://git.x-files.dk/xtras/nginxsnippets/src/branch/main/hostfiles/gitea.443.conf).
|
||||
|
||||
> **IMPORTANT**
|
||||
> If you enable HTTPS, update `/etc/giteaX/app.ini` (`ROOT_URL` setting)
|
||||
> from `http` to `https`, then restart both Nginx and Gitea.
|
||||
|
||||
> **NOTE**
|
||||
> The file also includes optional caching directives (commented out by default).
|
||||
> You can enable them to improve load times and performance if needed.
|
||||
> The lines you are looking for are at the bottom of the generated config file and look like this:
|
||||
> ```
|
||||
> ##### Cache js css static content and open files start #####################
|
||||
> # include /etc/nginx/nginxsnippets/cache-open-files.conf;
|
||||
> # include /etc/nginx/nginxsnippets/cache-statics.conf;
|
||||
> # include /etc/nginx/nginxsnippets/cache-js-css.conf;
|
||||
> ##### Cache js css static content and open files stop ######################
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
### Version Handling
|
||||
|
||||
This installer automatically checks the latest **Gitea version** from [https://dl.gitea.com/gitea/version.json](https://dl.gitea.com/gitea/version.json)
|
||||
|
||||
If it fails, it falls back to the version number stored in the **`fallback`** file. That file contains one line, for example:
|
||||
3. Run the postinstall unique to this instance:
|
||||
|
||||
```
|
||||
1.24.6
|
||||
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>
|
||||
```
|
||||
|
||||
> **Why a separate file?**
|
||||
> Keeping the fallback version outside the script avoids polluting the code with constants.
|
||||
> This keeps updates clean and ensures the installer logic never changes just because a version bump is needed.
|
||||
Restart:
|
||||
|
||||
```
|
||||
systemctl restart giteaX nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Troubleshooting
|
||||
## Version Handling
|
||||
|
||||
**Nginx fails to restart**
|
||||
Run `nginx -t` and review any syntax errors reported in `/etc/nginx/conf.d/<domain>.conf`.
|
||||
Script checks latest from:
|
||||
|
||||
**Gitea front-end not loading**
|
||||
Run `systemctl status gitea nginx` and ensure both Gitea and Nginx services are active.
|
||||
```
|
||||
https://dl.gitea.com/gitea/version.json
|
||||
```
|
||||
|
||||
**Access denied during database creation**
|
||||
Your MariaDB setup likely does not use socket authentication.
|
||||
Re-run the installer with the `-m` flag (and optionally `-a`) to provide credentials.
|
||||
Fallback file contains static version:
|
||||
|
||||
```
|
||||
fallback
|
||||
1.25.2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### FAQ
|
||||
## Troubleshooting
|
||||
|
||||
**Q:** Why doesn’t the script ask for a MariaDB password by default?
|
||||
**A:** Ubuntu 24.04’s MariaDB installation defaults to *socket authentication*,
|
||||
allowing the local `root` user to connect without a password.
|
||||
The installer detects this automatically and skips password prompts when applicable.
|
||||
|
||||
**Q:** Can I run the installer multiple times?
|
||||
**A:** Yes. Database and user creation use `IF NOT EXISTS`, making them safe to re-run.
|
||||
Existing configuration files are replaced, but no data is deleted.
|
||||
|
||||
**Q:** Does this modify existing Nginx settings?
|
||||
**A:** No. It adds a standalone host file in `/etc/nginx/conf.d/`
|
||||
and validates configuration changes before applying them.
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
@@ -217,4 +181,6 @@ More guides and documentation can be found on [wiki.x-files.dk](https://wiki.x-f
|
||||
---
|
||||
|
||||
### License
|
||||
Licensed under the [MIT License](./LICENSE)
|
||||
Licensed under the [MIT License](./LICENSE).
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user