Install the master

The installer puts Hyperion on a fresh Debian server and prints a link to the setup wizard, where you create the administrator and choose the server software. It asks no questions, except when a port it needs is already in use.

Before you start

• A fresh Debian server that meets the requirements, and root access.
• Ports 80, 443 and 8443 free. If something else holds one, the installer offers to stop the holder or abort.

Steps

1. Download the installer and read it. It runs as root.

   curl -fsSLO https://raw.githubusercontent.com/nechodom/hyperion/main/packaging/install/install-master.sh

2. Run it.

   sudo bash install-master.sh

   The installer prints one line per finished step: base packages (nginx, postfix, sudo, restic, sqlite3, git, dig), the source checkout in /opt/hyperion, the PHP package source, the Hyperion programs, and the configuration. The programs are downloaded from the rolling release and checked against SHA256SUMS. If the CPU is not x86_64, a download fails or a checksum does not match, it compiles from source instead.

3. If it reports a port conflict, it lists each port with the process that holds it and asks Choose [s/a] (default a). With no terminal available it aborts.

   Before you type s

   s stops the systemd unit or Docker container that holds the port, and kills the process when it has neither. If that is another service you need, it goes down, and it stays down until you start it and resolve the port conflict. Nothing is backed up. Type a instead if you are unsure, and free the ports yourself.

   Type s to stop the holders, or a to abort.

4. When it finishes it prints:

   The panel is waiting for you. Open this link to finish setup:

   followed by a link of the form https://203.0.113.10:8443/setup?t=XXXX-XXXX-XXXX-XXXX, a SHA-256 fingerprint of the certificate, and the setup code.

5. Open the link in a browser. The panel uses a self-signed certificate at this point, so the browser warns. Compare the fingerprint the browser shows with the SHA-256 line the installer printed, then continue. Continue with Run the setup wizard.

If the printed address is a private one (10.x, 172.16 to 31.x, 192.168.x and similar) and your browser is outside that network, replace it in the link with the server’s public address. The link works on any address the server answers on.

Check that it worked

sudo hyperion status

Expected: both hyperion-agent and hyperion-web show active (running).

hyperion version

Expected: the agent’s version and commit.

The installer log is /var/log/hyperion/install.log. Apt, git and cargo write there instead of the terminal, and the installer prints its tail when a step fails.

Lost the link

While the wizard is unfinished, sudo hyperion setup-link prints a new link and code and invalidates the old one. Add --host 203.0.113.10 to put a different address in the link. A code works once and expires after 24 hours.

Run it again

Running the installer again is safe.

• Before setup is finished and before the wizard’s admin step, it prints a fresh link. HYPERION_ADMIN_PASS is ignored while setup is under way.
• After the wizard’s admin step, it prints “Sign in to finish it” and the panel’s plain address with no setup link. Sign in with that account and the wizard continues.
• After setup is finished, or when an administrator exists, it changes nothing. It makes sure the two services run and tells you to use hyperion update.

Unattended install

To skip the wizard, set HYPERION_ADMIN_PASS before running the installer. It then installs the software itself, creates the administrator, starts the services and prints the panel address. It never enters setup mode. Use a root shell and keep the password out of the command line:

read -rs HYPERION_ADMIN_PASS && export HYPERION_ADMIN_PASS

HYPERION_COMPONENTS="php8.3 mariadb vsftpd phpmyadmin" bash install-master.sh

Run these from a root shell (sudo -i). The administrator’s name is admin unless you set HYPERION_ADMIN_USER. With no HYPERION_COMPONENTS, it installs php8.3 mariadb postgresql vsftpd phpmyadmin. Valid components are php8.1 to php8.4, mariadb, postgresql, redis, vsftpd and phpmyadmin. The certificate stays self-signed until you set a panel domain under Settings, Panel.

Environment variables

Variable	Default	Effect
HYPERION_LISTEN	0.0.0.0:8443	Address and port of the panel. A re-run keeps the port already in /etc/hyperion/web.toml.
HYPERION_ACME_EMAIL	empty	Let’s Encrypt contact. The wizard asks for it when empty.
HYPERION_RELEASE_TAG	rolling	Release to download.
HYPERION_BUILD_FROM_SOURCE	unset	Set to 1 to compile instead of downloading.
HYPERION_INSTALL_DIR	/opt/hyperion	Where the source checkout goes.
HYPERION_REF	main	Branch or tag to check out.
HYPERION_GIT_URL, HYPERION_GIT_TOKEN	the public repository	Clone from another URL, with a token for HTTPS.
HYPERION_LOCAL_TARBALL, HYPERION_SKIP_CLONE	unset	Install from a tarball, or from a checkout you made.
HYPERION_PREFLIGHT_ONLY	unset	Set to 1 to check the ports and install nothing.
HYPERION_STOP_CONFLICTS	unset	Set to 1 to stop port holders without asking.
HYPERION_ALLOW_SHARED	unset	Set to 1 to go ahead despite a port conflict. The services may then fail to bind.
HYPERION_FTP_PORT	21	FTP control port, unattended mode only.

If it fails

• Debian required (got '...') or Debian 12+ required: the server is not Debian 12 or newer.
• Port pre-flight found N conflict(s): free the ports, or choose s. See the variables above.
• Installing the base packages failed: the apt error is printed above the message. Fix it and run the installer again.
• cargo build failed: on a server with little memory, add swap and run the installer again.
• hyperion-agent did not come up or hyperion-web did not come up: run journalctl -u hyperion-agent -n 50 or journalctl -u hyperion-web -n 50.