Install

Before you start

• A fresh server you have root on, 64-bit x86, with systemd.
• One of: Ubuntu 22.04 LTS, 24.04 LTS or 26.04 LTS; Debian 12 or 13; AlmaLinux 9 or 10; Rocky Linux 9 or 10.
• Memory for the footprint you want: 1 GB for Compact, 2 GB for Standard, 4 GB for Full. At least 4 GB of free disk; 10 GB is recommended.
• A host name for the panel, such as panel.example.com, with its DNS A record pointing at the server.
• Free ports: 80 and 443 for websites, 7443 for the panel and 7444 for the editor; 25 and 53 only with mail and your own DNS. The installer checks each one and names the program that holds a taken port.
• For mail: outbound port 25 open at your provider, or a relay to send through.

Another control panel on the same server stops the install: two panels cannot share the web and mail servers. A web, database, mail or DNS server you manage by hand is reported with what will happen to it; nothing is overwritten silently.

Choose a footprint

The default follows the server's memory. Nothing is refused: the installer warns when memory is short and continues. Mail on a 1 GB server works but is tight (the spam filter takes about 450 MB, and it runs on every mail server because it signs outgoing mail); 2 GB is comfortable.

Install

1. Point the panel's host name at the server. Create a DNS A record for the name you will open the panel on, such as panel.example.com, with the server's public address. The free Let's Encrypt certificate for the panel needs it.

2. Run the installer as root. Unpack the release on the server and run: sudo bash install.sh. Simple mode checks the server first; add --advanced to be asked every choice.

   sudo bash install.sh

3. Answer four questions. The panel's host name, the email address of the first administrator, the footprint (Compact, Standard or Full) and the licence key. Press Enter at the key question to start a free 14-day trial. Enter takes the default in brackets, a question mark explains the question and b goes back.

4. Read the plan and confirm once. The installer lists everything it will install and change, with any warnings, and asks Install now? Nothing has been touched before this point.

5. Watch the services install through the panel. The panel is installed first, then the web server, PHP, the database engine, the certificate and the firewall are installed by the panel's own actions, each with its named steps on screen.

6. Copy the setup token and open the panel. The last screen prints the panel address and a one-time setup token. The token is shown only there; later it can be read with: cat /etc/respirecloud/bootstrap.token

A wrong answer is never fatal: the reason is printed and the question is asked again. The log is /var/log/respirecloud/install.log, with secrets masked, and the answers are saved in /etc/respirecloud/install.answers, readable by root only.

The end of a real Simple install on a 1 GB Ubuntu 24.04 server:

RespireCloud is installed

Installed through the panel:
    + Web server (nginx) and PHP 8.4
    + Serve the panel on panel.example.com
    + Certificate for panel.example.com (Let's Encrypt)
    + Database engine: mariadb
    + Firewall (ssh panel web)
    + Keep the firewall (version 1)

  Panel   : https://panel.example.com:7443/
  Setup   : open the panel, paste the one-time setup token, choose a password
  Token   : <64 hex characters>   (shown only here; it is not written to the log)
  Log     : /var/log/respirecloud/install.log

Create the first administrator

1. Create the administrator. Paste the token on the setup screen and choose a password. The email box is already filled with the address you gave. Then add a passkey and an authenticator app and save the recovery codes.

2. Point your domains' DNS at the server.

3. Create a hosting plan and your first account. Each new account gets a local backup target by itself; add a remote one in Backups, because a backup on the same disk does not survive the disk.

Lost the token? It stays in /etc/respirecloud/bootstrap.token until the administrator exists. The guided tour shows the panel's screens.

What Advanced asks

sudo bash install.sh --advanced

Every choice, in groups, each with a default and a one-line explanation. Answers are checked as you give them, with the reason on a bad one; PHP versions and database engines are checked while you type.

With a relay, the installer sends a test message to the administrator and fails the step if the relay does not accept it. The relay password is handed to the panel's secret store and then blanked in the answers file.

Unattended installs

sudo bash install.sh --yes --panel-host panel.example.com --admin-email you@example.com --footprint standard
sudo bash install.sh --advanced --print-answers > my.answers      # then edit and reuse
sudo bash install.sh --yes --answers my.answers

• --yes asks nothing. The panel's host name is taken from the server's own name when that is a full host name; the administrator's email is always required. A missing required answer is an error that names the key.
• The answers file is KEY=value per line with # comments. It is parsed, never executed.
• Later sources win: built-in defaults, the answers an earlier install saved, --answers FILE, RC_ANSWER_<KEY> environment variables, then flags.
• Secrets (the relay password, an external database or cache address) have no flag, so they never appear in the process list: put them in the answers file or in RC_ANSWER_<KEY>. The licence key has a flag too, but a flag shows in the process list, so use RC_ANSWER_LICENCE_KEY. --print-answers leaves the secrets blank.

What the installer does

1. Preflight. Root, the system and architecture, memory, disk and CPU against the footprint, the host name, the clock, free ports (the program holding a taken port is named), another panel or a hand-managed web, database, mail or DNS server, SELinux or AppArmor, outbound port 25 when mail is chosen. Each check is pass, warning or stop, with one sentence.

2. Plan. Everything that will be installed and changed, then one confirmation. With --dry-run it stops here and touches nothing.

3. The panel. The panel's own PostgreSQL and Valkey on the loopback address with generated passwords (or the ones you named), the software, the respirecloud user, the service units and the local agent's enrolment.

4. Services, through the panel. Once the panel is healthy, the installer runs the same actions as the panel's own Install buttons and shows each job's named steps: the web server and PHP, the panel's certificate, database engines, DNS, mail with your relay and filter answers, the firewall (it rolls back by itself unless confirmed), the licence and the update channel. It never installs nginx or Postfix by hand.

5. Finish. What was installed, what was skipped and why, what failed and how to resume, the panel address, the one-time setup token (on screen only, never in the log) and the next three things to do.

--check runs only the first step and --dry-run stops after the second. What is left for you at the end is what only you can do: DNS records, the registrar's glue records and a remote backup target.

Licence and the free trial

The installer asks one question about the licence. A key starts with RC-. Press Enter without one and a free 14-day trial starts for the administrator's email address. The trial has the Pro edition, with limits of 50 hosting accounts, 5 resellers, 3 servers and 1 CDN edge. You can enter a key later on the Licence page.

• The installer makes a key pair for this server. The private key never leaves it; the licence service only gets the public half.
• The licence service answers with the licence key the panel will use. The installer hands it to the panel in a file only root can read, and the panel deletes the file once it has activated the key.
• Running the installer again on the same server reuses the licence, so a trial is not started twice. A trial is given once for each email address and each network address in 90 days.
• If the licence service refuses the installation, or cannot be reached, the installer stops with the reason and installs nothing.
• For a key in an unattended install use RC_ANSWER_LICENCE_KEY: a flag shows in the process list. --trial-email sets another address for the trial.

How a download is verified

Run from an unpacked release, the installer uses the files beside it. Otherwise it asks the licence service for the release, which hands out the archive through short-lived signed links. The signed manifest, its signature and the release notes are public, so anyone can check a release. When it downloads the release for your channel, it installs it only when all of this holds:

1. The signature. The release manifest carries an Ed25519 signature. It must verify against the release key built into the installer; an installer without a key refuses to download.
2. The channel, size and checksum. The manifest must be for the channel you asked for and list the archive with exactly the size and SHA-256 that arrived.
3. The version. A release older than the installed panel, or older than the installer itself, is refused, so a genuine but old signed release cannot be replayed over a newer one. --allow-downgrade lifts this on purpose.
4. The archive. File names that are absolute or climb out with .. are refused.

Any failure ends with release check failed: <reason>. Nothing was installed. The check runs before the first package is installed. Modules are verified again by the panel against the signed manifest when they load.

Update, repeat, uninstall

• The panel updates itself. By default it looks for a signed release and installs it every night from 03:00, keeping the running release and a copy of its database first, and goes back by itself if the new release does not start. Every server and the Store modules follow. You can be told instead, pause it or turn it off on the Updates page. An update needs a licence that is active or in grace. How updates work.
• --update is the same safe path by hand, and --rollback goes back to the saved release on purpose.
• Run the installer again to upgrade in place. It keeps every module and every answer. A failed step says how to resume, and the same command resumes: finished steps are skipped.
• --reconfigure ignores the saved answers and asks again.
• --uninstall removes the panel: its programs, units and modules. Customer sites, databases, mail and the services the panel installed are never touched, and /etc/respirecloud and /var/lib/respirecloud stay.
• --uninstall --purge-data also deletes those two folders and the panel's own database, after you type delete panel data. A wrong phrase removes nothing.

Recovery scripts

The installer places three scripts in /usr/lib/respirecloud/recovery/ and refreshes them on every upgrade:

• server-backup.sh: Writes one encrypted backup repository and a recovery bundle. Run it from cron as root.
• server-restore.sh: Rebuilds a freshly installed server from the bundle and its passphrase.
• server-check.sh: Lists what came back, line by line, and what a server backup never contains.

Keep a second copy of them with the recovery bundle and its passphrase, somewhere that is neither this server nor the backup store. In a lab run, a destroyed server with two customers, sites, MariaDB and PostgreSQL databases, a mailbox, DNS zones and a certificate was rebuilt on a blank one in 312 seconds from a freshly installed panel. A restore goes back to the time of the last backup: there is no recovery to a moment between backups. Sessions, the mail queue, container volumes and the licence activation do not come back.

Add more servers

1. On the Cluster page press Add a server. A default install listens for other servers only on itself, so the page first offers Get this panel ready for more servers: a plan that opens the bus port in the firewall, for the addresses you enter or any address if you leave them empty, and a confirmation.

2. Then create an enrolment token for the new server (action core.node.enrol_token.create). You get a one-time token and the exact command to run.

3. On the new server, as root:

   respirecloud-agent enrol --panel https://panel.example.com --token rcen_… --ca-sha256 FINGERPRINT

4. The agent creates its key on the machine and connects. If the panel's certificate authority does not match the fingerprint you passed, it says so and saves nothing.

Flags

Answer keys

Every key is a line in the answers file, an RC_ANSWER_<KEY> variable and, unless it is a secret, a flag in lower case with dashes (MAIL_HOST is --mail-host).

Troubleshooting

Not proven yet

• SELinux in enforcing mode on AlmaLinux and Rocky Linux: the labs run with it off.
• The antivirus on a Full install was run on Ubuntu 24.04 and AlmaLinux 9; the other systems use the same code but were not run.
• A release signed with production keys, and the public download address.
• Almost all installs ran in lab containers. One install has run on a rented server (a disposable cloud box): it got real certificates for the panel, a site and mail, took mail in over TLS and answered DNS from the internet. That is one server, not a range.