Skip to content
Hyperion

Run the setup wizard

The setup wizard finishes a new installation. The installer’s link opens it. It has nine steps, listed on the left. Progress is saved on the server, so closing the tab is safe: open the link again, or run sudo hyperion setup-link, and it resumes where it stopped.

Before you start

Section titled “Before you start”
  • You ran the installer and have the link and the setup code.
  • For the Panel address step: a DNS A or AAAA record for the panel name that points at this server, and port 80 reachable from the internet.
  • For the Outgoing mail step: the SMTP server details of your mail provider.
  • For the Backups step: an S3-compatible bucket and its access key.

Steps

Section titled “Steps”

  1. Access. Open the link. The page Confirm this is your server has the Setup code filled in. Click Start setup. The code works once. A wrong code is refused with “That code doesn’t match”, and repeated wrong codes from one address are throttled.

  2. Admin account. Fill in Username (1 to 64 characters: letters, digits and . _ - @), Email (password resets and alerts go here), Password and Repeat password (at least 12 characters). Click Create account. This account gets the Owner role.

  3. Two-factor sign-in. Scan the QR code with an authenticator app, or type the key into it. Enter the 6-digit code in the field and click Turn on and continue. Save the ten backup codes somewhere other than this server. They are not shown again. The Skip for now button appears only when the 2FA requirement is off.

  4. Server software. Choose what to install and click Install selected:

    Choice Default
    PHP-FPM 8.3, 8.4, 8.2 or 8.1 (always installed, includes wp-cli) 8.3
    MariaDB on
    PostgreSQL off
    phpMyAdmin on
    FTP (vsftpd), with an FTP port field (1 to 65535) on, port 21
    Redis off

    Each component shows installing, done or failed, with the installer output below. Closing the tab does not stop the install. When it finishes, click Continue. If a component failed, click Try again, or continue and install it later from Service health. You can add more PHP versions later.

  5. Server identity. Set Hostname, Time zone and Contact email. Backups and reports run on this clock, and Let’s Encrypt sends expiry notices to the contact address, which is required. Click Save and continue. This restarts the agent for a few seconds.

  6. Panel address (optional). Create the DNS record for the panel name first. The page shows this server’s addresses. Enter the name in Panel domain and click Check DNS and issue certificate. The page shows the certificate request until it reads “Let’s Encrypt certificate issued”. Then click Continue on https://panel.example.com. You stay signed in on the new address. If the DNS check fails but the record is correct and your resolver is behind, tick the box that appears and try again. Click the Skip for now button below the form to keep using the IP address, and set the panel domain later.

  7. Outgoing mail (optional). Enter SMTP server, Port, Encryption (STARTTLS (587), TLS (465) or None (testing only)), Username, Password and From address, then click Save. Click Send test email to send a message to the administrator’s address, then Continue. Mail sent straight from a VPS often lands in spam, so use your provider’s relay.

  8. Backups (optional). Under Add an S3-compatible bucket enter Endpoint, Bucket, Region (auto when empty), Access key and Secret key, then click Save and check bucket. Hyperion writes and deletes a test object and shows “write + delete ok” or “check failed”. The target is saved with a retention of 7 daily copies. Click Continue.

  9. Review. Each line is checked on the server when the page loads. Items you skipped show a Fix link. Click Open the panel.

The final button is disabled while a required item is missing. A missing PHP blocks it with “Install PHP first”. Everything you skipped can be set up later under Settings.

Check that it worked

Section titled “Check that it worked”

You land on the dashboard, signed in as the Owner. Open https://<your-server>:8443/setup (or the panel domain): it now answers 404, because the wizard is closed.

If it fails

Section titled “If it fails”
  • “This code has expired”: run sudo hyperion setup-link on the server for a new one.
  • “This code has already been used”: someone used the code. If it was not you, run sudo hyperion setup-link.
  • “Too many wrong codes from this address”: wait the number of minutes shown.
  • “That code was not accepted” on the two-factor step: check the phone’s clock and enter the code that is showing now.
  • “Use a password of at least 12 characters”: choose a longer password.
  • The certificate request ends in “Let’s Encrypt refused the certificate”: the DNS record does not point here yet, or port 80 is blocked. Click Try again or skip the step and set the panel domain later under Settings, Panel.