mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-06-18 10:17:36 +07:00

Files

Sanaei 7c2598fae9 feat: release-driven golden-image & unattended-install deployment pipeline (#5323 )

* feat(install): add non-interactive install path for cloud/golden-image use

Trigger non-interactive mode when XUI_NONINTERACTIVE=1 or stdin is not a
TTY (curl | bash, cloud-init). Every prompt is then replaced by an env var
or a sane default; interactive prompts stay byte-for-byte identical.

Honored env vars: XUI_USERNAME, XUI_PASSWORD, XUI_PANEL_PORT,
XUI_WEB_BASE_PATH (unset => random, as before), XUI_SSL_MODE=none|ip|domain
(default none), XUI_DOMAIN, XUI_ACME_EMAIL, XUI_DB_TYPE/XUI_DB_DSN, plus
additive XUI_ACME_HTTP_PORT, XUI_SSL_IPV6, XUI_SERVER_IP.

On success, write /etc/x-ui/install-result.env (mode 600) with the panel
creds + access URL + api token, in both interactive and non-interactive
modes, so cloud-init/MOTD can surface them. Postgres in non-interactive
mode requires XUI_DB_DSN or installs locally; never silently downgrades.

* feat(deploy): add first-boot per-instance credential generation

Golden images ship with no x-ui.db. x-ui-firstboot.sh runs once (guarded by
/etc/x-ui/.firstboot-done), before x-ui.service, and replaces the seeded
admin/admin with fresh random username/password on a random high port,
regenerates the session secret/panel GUID via 'x-ui setting -reset', mints an
API token, and writes the creds to /etc/x-ui/credentials.txt (600) + /etc/motd.

Idempotent: skips regeneration if a non-default admin already exists. The
oneshot unit is ordered After=network-online/cloud-init and Before=x-ui.service
so the panel never serves default credentials.

* chore(deploy): force LF for cloud-image deploy assets (.service/.hcl/.yaml)

* feat(deploy): add Packer config + provisioning scripts for golden image

One build, two sources: amazon-ebs (AWS AMI, Canonical Ubuntu 24.04 base via
source_ami_filter) and qemu (qcow2 + raw, NoCloud-seeded for build-time SSH).
Provisioner order is fixed: provision.sh -> harden.sh -> cleanup.sh.

- provision.sh: downloads the released x-ui tarball (no Go build), installs the
  panel + firstboot unit, enables but does NOT start services, creates NO DB.
- harden.sh: key-only SSH, no root password login, locks default account
  passwords, enables unattended-upgrades (scanner-compliant).
- cleanup.sh: wipes any DB/creds, SSH host keys, authorized_keys, machine-id,
  cloud-init state, logs and history; fails the build if any secret survives.

packer fmt -check clean; packer validate passes for both sources.

* feat(deploy): add generic cloud-init user-data for unattended install

cloud-init.yaml installs the latest 3x-ui non-interactively (XUI_NONINTERACTIVE=1)
on any cloud-init platform, generating unique per-instance credentials and
surfacing them via /etc/x-ui/install-result.env, serial console and MOTD.
README documents per-provider usage (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
and all XUI_* knobs.

* ci: add image.yml to build cloud images on release

On release: published (or workflow_dispatch with a tag), waits for the
x-ui-linux-amd64.tar.gz asset (handles the release-matrix upload race), then:
- qemu-image (always): builds the qcow2 with Packer and attaches a compressed
  .qcow2.xz + sha256 to the GitHub release. Uses KVM when /dev/kvm exists,
  else TCG.
- ami-image (gated): builds the AWS AMI only when AWS creds exist (OIDC role
  preferred, else access keys), so forks skip cleanly. Prints the AMI ID to the
  job summary. No secrets or AMI IDs are committed.

* test(deploy): add container smoke tests for install + firstboot

smoke-noninteractive.sh: runs install.sh piped (no TTY) with
XUI_NONINTERACTIVE=1 in an Ubuntu container; asserts install-result.env (600)
holds random non-default creds, hasDefaultCredential is false, and the panel
serves HTTP.

smoke-firstboot.sh: installs the released binary with no DB, runs
x-ui-firstboot.sh; asserts per-instance creds + credentials.txt (600) + MOTD,
no admin/admin, and that a second run is a no-op (sentinel honored).

smoke.yml runs both as gated jobs on PRs/pushes touching install.sh or deploy/**.
Both pass locally against the v3.3.1 release binary.

* docs(deploy): add Packer/marketplace docs and link from README

- deploy/README.md: index of the cloud-deploy tooling and the two models
- deploy/packer/README.md: how to build locally, variables, first-boot behavior
- deploy/marketplace/aws/README.md: seller registration -> AMI scan ->
  limited-visibility preview -> go-public checklist
- deploy/marketplace/hetzner/README.md: cloud-init-first guidance + snapshot
  caveat (delete x-ui.db first) + hetznercloud/apps reference
- README.md: link the unattended-install / cloud-image docs from Quick Start

* feat(deploy): build golden images for arm64 as well as amd64

The install path was already multi-arch (install.sh auto-detects arch); this
extends the golden image + CI to arm64:

- packer: xui_arch (amd64|arm64, validated) now derives the base AMI filter and
  the Ubuntu cloud image; the qemu source switches to qemu-system-aarch64 + virt
  machine + AAVMF UEFI firmware for arm64. amd64 path unchanged.
- image.yml: arch matrix. AMIs for amd64 (t3.small) + arm64 (t4g.small/Graviton)
  from one runner; qcow2 for amd64 on a standard runner and arm64 on a native
  ubuntu-24.04-arm runner. Waits for both release tarballs.
- smoke.yml: run install + firstboot smoke tests on amd64 and arm64 runners;
  smoke-firstboot.sh now resolves the arch tarball via dpkg.
- docs updated for both arches.

packer fmt/validate pass for amd64 and arm64; actionlint + shellcheck clean.
Verified locally: non-interactive install AND firstboot run on the real arm64
release binary under emulation (ELF aarch64, no admin/admin).

* chore(deploy): default AWS region to eu-central-1 (Frankfurt)

Replace the us-east-1 fallback in image.yml (4 sites) and the Packer 'region'
default + doc examples. Still overridable via the AWS_REGION repo variable / the
-var 'region=...' flag.

* feat(deploy): add Amazon Lightsail support (launch script + snapshot builder)

Lightsail can't launch from an EC2 AMI and its blueprint list isn't
self-publishable, so add the two self-service paths instead:

- launch-script.sh: paste into Lightsail 'Add launch script' (or --user-data) to
  install 3x-ui non-interactively with unique per-instance credentials.
- snapshot-userdata.sh + build-snapshot.sh: AWS CLI pipeline that provisions a
  build instance (panel installed, NO DB, firstboot enabled), runs the shared
  cleanup.sh, then snapshots it. Instances launched from the snapshot mint their
  own credentials on first boot. Optional --panel-port pins a known port for the
  Lightsail firewall.
- README documents both paths, the firewall caveat, and the blueprint reality.

EC2 AMI / Marketplace path kept untouched alongside. All scripts shellcheck-clean.

* fix(deploy): address Copilot PR review findings

- install.sh + firstboot: write install-result.env / credentials.txt values with
  printf %q so the files stay safe to source even if creds are pinned with shell
  metacharacters (no-op for the alphanumeric random defaults).
- firstboot: fail closed if 'x-ui setting -show' can't be parsed to true/false —
  exit without writing the sentinel so the next boot retries, instead of silently
  skipping regeneration and risking admin/admin.
- firstboot + cloud-init + lightsail launch-script: keep secrets out of the
  world-readable /etc/motd (show URL + username only; full creds via the mode-600
  file / serial console).
- lightsail build-snapshot: handle download-default-key-pair returning either a
  PEM or base64, and assert a valid PEM before using it for SSH.
- image.yml: pin hashicorp/setup-packer@v3 (was @main).
- deploy/README: document XUI_ACME_HTTP_PORT / XUI_SSL_IPV6 / XUI_SERVER_IP.

Both container smoke tests still pass; shellcheck + actionlint clean.

2026-06-14 18:08:35 +02:00

cloud-init.yaml

feat: release-driven golden-image & unattended-install deployment pipeline (#5323 )

2026-06-14 18:08:35 +02:00

README.md

feat: release-driven golden-image & unattended-install deployment pipeline (#5323 )

2026-06-14 18:08:35 +02:00

README.md

3x-ui via cloud-init (generic, no golden image)

This is the secondary deployment path: a single cloud-init.yaml user-data file that installs 3x-ui non-interactively on a fresh Ubuntu/Debian VM and generates unique random credentials per instance. Use it when you do not want to build a golden image — it works on any cloud-init platform.

For AWS Marketplace / reusable images, use the Packer build in ../packer/ instead.

How it works

The VM boots a stock Ubuntu/Debian cloud image.
cloud-init writes and runs /opt/xui-bootstrap.sh, which exports XUI_NONINTERACTIVE=1 and pipes the project's install.sh into bash.
install.sh runs end-to-end with zero prompts, picking secure random values for any credential you didn't pin.
The generated credentials are written to /etc/x-ui/install-result.env (mode 600), echoed to the serial console, and appended to /etc/motd.

Retrieve them after boot with either:

sudo cat /etc/x-ui/install-result.env     # over SSH

…or read the provider's serial console output (handy before you have SSH).

Customising

Edit the export XUI_* lines inside the write_files block of cloud-init.yaml. All knobs are optional; unset ⇒ random/secure default.

Env var	Default	Meaning
`XUI_SSL_MODE`	`none`	`none` (plain HTTP), `ip` (Let's Encrypt IP cert), `domain`
`XUI_USERNAME`	random	Admin username
`XUI_PASSWORD`	random	Admin password
`XUI_PANEL_PORT`	random high port	Panel listen port
`XUI_WEB_BASE_PATH`	random	Panel base path (obscures the URL)
`XUI_DOMAIN`	—	Required when `XUI_SSL_MODE=domain`
`XUI_ACME_EMAIL`	—	Let's Encrypt account email (domain mode)
`XUI_DB_TYPE` / `XUI_DB_DSN`	`sqlite`	Set `postgres` + DSN to use PostgreSQL

TLS note: none serves the panel over plain HTTP on a random high port — fine behind a reverse proxy or an SSH tunnel, but put TLS in front of it before exposing the panel publicly. domain mode needs a public DNS A record pointing at the box and port 80 reachable at install time.

Per-provider usage

Hetzner Cloud — Create Server → Cloud config: paste the file. Or CLI: hcloud server create --image ubuntu-24.04 --user-data-from-file cloud-init.yaml ...
AWS EC2 — Advanced details → User data: paste the file. Or aws ec2 run-instances --user-data file://cloud-init.yaml ... (For a reusable Marketplace image use the Packer AMI build instead.)
DigitalOcean — Create Droplet → Advanced options → Add Initialization scripts (user data): paste the file. Or doctl compute droplet create --user-data-file cloud-init.yaml ...
Vultr — Deploy → Additional Features → Cloud-Init User-Data: paste the file.
Google Cloud (GCE) — gcloud compute instances create xui \ --image-family ubuntu-2404-lts-amd64 --image-project ubuntu-os-cloud \ --metadata-from-file user-data=cloud-init.yaml
Azure — az vm create --image Ubuntu2404 --custom-data cloud-init.yaml ...
Oracle Cloud (OCI) — Create Instance → Show advanced options → Management → Cloud-init script: paste (or base64-upload) the file.

Validate before you deploy

cloud-init schema --config-file deploy/cloud-init/cloud-init.yaml