xui_installer/README.md

# XUI.ONE 1.5.13 Installer

A bootstrap installer for the pre-patched **XUI.ONE 1.5.13** panel, modeled on
the midesi.net `installxui.sh` wrapper. The release package is mirrored to our
own **Gitea generic-package registry** (fast, self-hosted), with the upstream
[XUIPatch](https://github.com/xuione/XUIPatch) GitHub release as an automatic
fallback.

## What it does

`install_xui.sh` is a thin, safe wrapper around the official XUI installer:

1. Pre-flight checks — root, Ubuntu 20.04/22.04/24.04, x86_64, RAM/disk, re-install guard
2. Installs missing deps (`wget`, `unzip`, `tar`)
3. Downloads `XUI_1.5.13.zip` (~661 MB) from the Gitea mirror (falls back to GitHub)
4. Verifies the SHA-256 checksum (on by default)
5. Extracts `install`, `database.sql`, `xui.tar.gz`
6. Runs the bundled `./install` **non-interactively** — auto-generates a valid
   license key and answers the sysctl prompt
7. Prints the panel **setup URL**; MySQL credentials are saved to
   `<workdir>/credentials.txt`

### About the "license"

XUI.ONE 1.5.13 is the **post-shutdown, license-free build**. The developer
(GTAXUI) wound down the product and took the license servers offline, then
released a clean 1.5.13 with all license verification patched out (unlocked
extensions for PHP 7.2 / 7.4). It **never phones home**.

The bundled installer still asks for a key, but it only checks the format —
`isValidLicense()` is literally `len == 16 and all hex`. So **any valid 16-char
hex string works** (e.g. `a9f3b7e2c6d8140f`). This wrapper auto-generates a
random one with `openssl rand -hex 8`, exactly like the community auto-installers.
Set `XUI_LICENSE` to pin a specific key.

## Usage

On a clean Ubuntu server, as **root**:

```bash
# One-liner — pulls the latest installer from the Gitea repo, then runs it:
bash <(wget -qO- https://git.ops01.hprx.zip/seed/xui_installer/raw/branch/main/install_xui.sh)

# Or locally:
chmod +x install_xui.sh
./install_xui.sh
```

The installer lives in the Gitea repo **`seed/xui_installer`**. The `raw/branch/main`
URL above always serves the latest committed version — just `git push` an update
and the one-liner picks it up, no version bump needed.

## Mirror (where the package lives)

The 661 MB release is hosted on our Gitea, publicly downloadable with **no auth**:

```
https://git.ops01.hprx.zip/api/packages/seed/generic/xui/1.5.13/XUI_1.5.13.zip
sha256: a92e5f21a338c56190d7580f449492c970b5d4219474548ca5ec2f06bc57b2e7
```

Re-uploading later (e.g. a new version) — from any box with the Gitea token:

```bash
curl -X PUT \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/octet-stream" \
  -T XUI_1.5.13.zip \
  "https://git.ops01.hprx.zip/api/packages/seed/generic/xui/<version>/XUI_1.5.13.zip"
```

> `Content-Type: application/octet-stream` is **required** — Gitea's generic
> registry returns HTTP 500 ("isn't multipart/form-data") without it.

## Configuration (env vars)

| Variable            | Default                                              | Purpose                                              |
|---------------------|------------------------------------------------------|------------------------------------------------------|
| `XUI_URL`           | Gitea mirror URL (above)                              | Override the primary download source                 |
| `XUI_FALLBACK_URL`  | GitHub XUIPatch release                               | Override the fallback source                         |
| `XUI_SHA256`        | baked-in known-good hash                              | Override, or set to `""` to skip checksum verify     |
| `XUI_WORKDIR`       | `/opt/xui_install`                                    | Where the package is downloaded/extracted/run        |
| `XUI_LICENSE`       | auto-generated 16-hex                                 | Pin a specific 16-char hex license key               |
| `XUI_SYSCTL`        | `Y`                                                   | Answer to the installer's sysctl-overwrite prompt    |
| `XUI_INTERACTIVE`   | `0`                                                   | Set to `1` to answer the installer's prompts yourself|

Example pinning a license and running fully unattended:

```bash
XUI_LICENSE="a9f3b7e2c6d8140f" ./install_xui.sh
```

Example pointing at a different mirror:

```bash
XUI_URL="https://cdn.example.com/xui/XUI_1.5.13.zip" \
XUI_SHA256="a92e5f21a338c56190d7580f449492c970b5d4219474548ca5ec2f06bc57b2e7" \
./install_xui.sh
```

## Local archive (`release/`)

The package itself is **not** kept in this repo (661 MB, git-ignored) — the
durable copy is the Gitea mirror above. Only the checksum is tracked:

- `release/XUI_1.5.13.zip.sha256` — feed to `XUI_SHA256` for integrity checks.

Package contents (the three files midesi's tarball also ships):

```
install        # the XUI installer (prompts for license + sysctl)
database.sql   # initial schema
xui.tar.gz     # the panel itself
```

To pull a local copy anytime:

```bash
curl -L -o release/XUI_1.5.13.zip \
  "https://git.ops01.hprx.zip/api/packages/seed/generic/xui/1.5.13/XUI_1.5.13.zip"
```

## Credentials

Gitea creds live in `.gitea/` (git-ignored): `token` and `url`. The token is
scoped **public-only + write:repository + write:package**. Rotate it in Gitea
(Settings → Applications) if it's ever exposed.

## Tested

End-to-end on a clean **Ubuntu 20.04.6** box (2026-06): one-liner → unattended
install → `xuione` active, **MariaDB 10.6.22**, nginx on :80, `xui` DB imported,
panel setup page (`/<code>/setup`) returns HTTP 200.

### Installer patches (applied automatically by `patch_installer`)

The 2025-era bundled `install` references two now-broken sources; the wrapper
rewrites them on the fly:

| Problem | Fix |
|---|---|
| MariaDB 10.6 repo `ams2.mirrors.digitalocean.com` no longer resolves (DO retired their distro mirrors) | Rewritten to `mirror.rackspace.com/mariadb/repo/10.6/ubuntu` |
| `add-apt-repository ppa:maxmind/ppa` hangs forever where `launchpad.net` is unreachable | Dropped — `libmaxminddb0/-dev`, `mmdb-bin` come from Ubuntu's own repos |

### Harmless warnings you can ignore

- `E: Unable to locate package libssh2-1t64` — that's the Ubuntu 24.04 (noble)
  package name; on 20.04/22.04 the needed `libssh2-1` is pulled in by `php-ssh2`
  automatically. `ssh2` ends up loaded in XUI's PHP regardless.
- `debconf: ... dumb terminal` / locale warnings — expected under non-interactive apt.

### Security note

XUI's bundled `my.cnf` sets `bind-address = *`, so MariaDB listens on
`0.0.0.0:3306`. The `xui` DB user has a strong random password and root uses
socket auth, but consider firewalling 3306 to localhost if the box is on a
public IP.

## How the panel code is protected (IonCube)

XUI's application code is **IonCube-encoded**, not editable source:

- ~294 of 308 `.php` files are encoded binary (a handful, e.g. the Ministra
  portal, are obfuscated plaintext instead).
- It uses a **custom IonCube loader** keyed via `ioncube.loader.key.xui` in the
  bundled `php.ini`. The encoded files are headerless binary and only run under
  that keyed loader — a stock IonCube loader can't decode them.
- The community "patch" is exactly this loader: a custom-built `ioncube.so`
  (shipped for **PHP 7.2 and 7.4**) that runs the still-encrypted code without
  the original license/phone-home enforcement.

**Consequences:**

- You can't read or modify XUI's PHP source — customization is limited to config,
  templates, and the database.
- **PHP is locked to 7.2 / 7.4.** There is no loader here for PHP 8.x and the
  encoded files won't run on it — which is why XUI ships its own bundled PHP
  7.4.10. Don't repoint it at system PHP 8.
- The load-bearing piece is that bundled `ioncube.so` + key (inside `xui.tar.gz`,
  already in the mirror). Keep the mirror intact.

## System requirements

- Ubuntu 20.04 / 22.04 / 24.04 LTS, clean install, x86_64
- 6+ CPU cores, 16–32 GB RAM, 480 GB+ SSD/NVMe, 1 Gbps recommended