Installation¶
The installation script is the supported way to install, restore and extend a Claugine portal. It is the only path
that is tested against a clean machine before each release. It installs the edition of your
licence; the LICENSE file of the release says what use is allowed.
Names and addresses below are examples.
The installation script¶
A Claugine installation is a server you run. You download the installation script, run it as an ordinary user with sudo rights, and give it your licence key and the address of your portal.
Nothing on the machine is changed until the licence answers. The script activates the licence, checks in, downloads the release your licence is entitled to as a bundle from your licensing portal, verifies its checksum before unpacking it, installs it, and only then binds the installation to your licence key. Nothing is cloned from GitHub; updates and restores come as bundles in the same way.
The script refuses to run as root. Every step that needs root asks for it one command at a time.
Requirements¶
Ubuntu Server 26.04 LTS, 4 vCPU, 8 GB RAM and 60 GB of disk for the portal itself. A user with passwordless sudo, and outbound HTTPS to your licensing portal (my.claugine.com), and to GitHub once, to download the installation script.
The script is downloaded into ~/claugine in the home directory of the user who connects over ssh, and run
from there. That user must be able to use sudo without a password; every step that needs root is run with
sudo, so nothing has to be run as root over ssh.
The script comes from the public repository claugine, which holds the code to read and this one script (see
Licensing). Everything else it installs comes as a release bundle from the
licensing portal.
The two VMs of an Enterprise installation must reach each other directly: ssh, MySQL (3306), the portal's HA agent and its status port. Each VM must reach an Ubuntu package mirror.
Running it¶
As the ssh user, with your licence key and your portal's address:
mkdir -p ~/claugine && cd ~/claugine
curl -fsSLO https://raw.githubusercontent.com/ivladek/claugine/main/deploy/claugine-install.sh
bash claugine-install.sh --new --licence-key CLG-… --site-url https://portal.example.com
The portal's address names the installation: its installation id is the host of the site URL
(portal.example.com here), and both nodes of an Enterprise pair use it.
--new installs a fresh portal. A restore starts from the backup itself: its own script (bash <name>.sh
--licence-key CLG-…) checks the archive and runs the installation script with --restore, which asks for the
archive password once, before anything is written (see Backup and restore). --dry-run prints every command that needs root instead of running it,
and changes nothing.
Enterprise: two VMs, one command¶
An Enterprise installation is two virtual machines, and the installation starts only when both are ready. Prepare the second VM as you prepared the first — a clean Ubuntu 26.04 and an ordinary user with passwordless sudo — then run the installation script on the first VM only, naming the second one:
bash claugine-install.sh --new --licence-key CLG-… --site-url https://portal.example.com \
--second admin@192.0.2.20
The first run stops before changing anything and prints a line: the first VM's own ssh key. Add that line to
~/.ssh/authorized_keys of that user on the second VM, and run the same command again.
The script then checks the second VM — it can log in, has passwordless sudo, runs Ubuntu, has no portal on it, and the two VMs reach each other — and changes nothing on either VM until every check passes. Then it installs the first VM, installs the second one from the same release, copies the database to it, keeps it replicating as the standby, and puts HAProxy in front of both so the portal's address always reaches the active node.
--site and --second-site name the two nodes' sites (default site1 and site2).
If the run stops part way — a network problem, a package mirror that does not answer — fix the cause and run the same command again. A second VM that already carries this installation is picked up where it was left, not refused.
When the licence refuses¶
The installation stops, and says why, if the licence has expired, if the key is already bound to another running installation, or if the installation was released from another customer's licence. In each case nothing is installed. When the licensing portal refuses an activation, the installer prints the licensing portal's reason (for example, that the key is renewed for another customer) instead of an HTTP error code; a check-in in conflict prints its notice.
Installing again under the same name¶
Installing again on new VMs under the same name, or restoring a backup there, is the same installation: the installation id is the same, so nothing has to be released on the licensing portal and no installation id is given. This holds after the installation was released too: activating under its name with a free licence of the same customer reinstates it. A portal under another name is a new installation: release the old one first.
Updates¶
Releases come from the licence control plane. With automatic updates on (Settings → Portal → Updates), the portal installs a new release by itself, the same way as Update portal (Settings → Portal), which checks in and installs the newest release offered to this installation: on two nodes one node at a time, switching over and back (see Software delivery and updates); on one node after a backup. The Standard edition installs in its weekly window. The steps of every operation are in Administration → Logs.
Break-glass only (the portal's UI is down), on a node:
Releases older than the oldest version an installation in use runs are put on hold by themselves; a newer release stays offered even when nobody runs it, and with no installation in use nothing is held. Naming a release on hold is refused with "on hold or not offered to this installation"; an installation can still download the version it runs. The oldest releases, once no installation runs them, are withdrawn in time and their builds deleted: naming one stops with "vNN.NN.NN was withdrawn: its build is no longer available.", and nothing is unpacked. Both refusals end with "Nothing was changed. Install the release the control plane offers instead (the portal's update does)."
A portal update installs the packages it needs when they are missing, and never upgrades the ones already there: the system's own updates are Update OS in Settings → Portal (on two nodes: the standby's OS, the switch over, the other node's OS, the switch back; each node rebooted if it needs it). On a standby the OS update lifts the database's read-only setting for the time of the upgrade (a MySQL upgrade needs it) and puts it back.
Both take the release as a bundle from the licensing portal. In an Enterprise pair the standby gets each release first.
After the installation¶
The script ends by printing a one-time link, valid 24 hours, that creates the first super admin. Open it and create that account before anything else.
Then, in Settings:
- Mail. The portal sends invitations, approvals and alerts from each node's own mail server. Until the DNS records that Settings → Mail lists are in place (the A record of the node's mail name, SPF, DKIM, DMARC and the PTR record), they may not arrive.
- The portal's address. Check it matches the name you installed with and the name your certificate is for.
- The licence. Settings → Portal shows the licence state and the installation id (the portal's name). It should read active within ten minutes of the installation.
Outside the portal, the one thing the provider must do is DNS: the portal's name must resolve to this machine, both for your users and for the certificate authority.
Nothing of the provider's platform has to exist yet. The portal is installed first and the inventory is entered into it afterwards: what to have ready, and the order, are on Inventory.
To restore a backup onto a new machine, see Backup and restore.