Getting started
Upgrading Maran
Upgrade a running server by taking a panel backup and re-running the installer, what it keeps and migrates, how to check the result, and what to do if it fails.
Upgrading Maran means running the installer again on the server that already has it. There is no
maran update command and no maran rollback command, and the panel has no one-click update, so the
steps below are the whole procedure. Run them as root, from a shell on the server.
1. Take a panel backup first
The installer cannot undo an upgrade, so the backup is your way back. Create it exactly as described in Panel backup and restore:
sudo /usr/local/sbin/maran panel-backup --passphrase-file /root/maran-backup.passphrase
Copy the archive off the server, and keep the passphrase somewhere else, not on the server and not
with the archive. The panel keeps running while the backup is taken. The archive holds the panel's database,
its two keys, the licence and /etc/maran; customers' files and databases are in the account
backups instead.
2. Run the installer again
Run the same command you installed with:
curl -sSL https://get.maran.innovayse.com | sudo bash
The installer is safe to repeat. It fetches the current signed release, verifies the manifest's
signature and every archive's checksum before it unpacks anything, and checks each checksum again
just before extracting that archive. To choose the release channel, run the unpacked installer
with --channel stable or --channel beta. A server without internet access uses the offline bundle
described under Installation:
sudo bash install.sh --offline-tarball <bundle>.tar.gz
On a re-run the preflight accepts the panel's own port as already taken by this install, and
everything is appended to /var/log/maran/install.log, so the log holds the history of every run.
What the installer keeps and what it changes
| Item | On a re-run |
|---|---|
Security__EncryptionKey in /etc/maran/panel.env | Kept. It is never rotated, since a new key would make stored secrets unreadable. |
Jwt__SigningKey in /etc/maran/panel.env | Kept, so people stay signed in across the upgrade. |
The agent's free-space floor in /etc/maran/agent.env | Kept when it is a whole number from 1. |
The rest of panel.env | Written again by the installer, and host facts such as the SSH ports are detected afresh. Note any value you changed by hand before you upgrade, and check it afterwards. |
| The one-time setup token | Replaced with a new one. It only matters before the first administrator exists. |
| The panel's database | Kept, and brought forward by the new release's migrations. |
| The panel and the agent programs | Replaced with the new release's. |
Database migrations
The installer applies every module's database migrations in its own step, after the configuration is
written and before any service is started. It runs the panel's own binary in migrate mode as the
maran service account, so a migration the panel could not run fails here, while you are
watching, and not as an error an hour later. If the step fails, the installer stops and nothing is
restarted.
The panel and the agent move together
The panel and the server agent talk over a versioned contract, and a release can change its revision. The release notes say so under "Before you upgrade" when it happens. The installer replaces both in one run and then restarts the agent first and the panel second, so run the whole installer and do not replace just one of the two. When the panel starts it also converges every PHP site's pool and virtual host with the new release.
3. Check the result
When the installer finishes it prints that Maran is installed and reachable at the panel's address. Then confirm from the server:
sudo /usr/local/sbin/maran status
You want every service listed as active and enabled, and the panel's report to show the database reachable, the agent connected, no pending migrations and the version you expect. The exit status is 0 when everything is healthy and 1 otherwise; see Recovery and diagnostics for what each part means. Then sign in to the panel and open the dashboard.
If the upgrade fails
The installer does not roll back. It stops at the failing step and tells you which one. Earlier steps have already run, and later ones have not.
- Read the end of
/var/log/maran/install.logand the message the installer printed. - Fix the cause and run the installer again. Every step checks the current state before it acts, so a repeat resumes where the last run stopped.
- If the panel does not start, read
journalctl -u maran-apiandjournalctl -u maran-agent, and runmaran status, which works even with the panel down.maran collect-diagnosticswrites a redacted bundle to send to whoever is helping you.
If the server cannot be repaired, go back through the backup from step 1. Install Maran on a clean
server, using the same release as the backup or a newer one. Do not create an administrator in the
browser. Then run maran panel-restore there. The restore applies that release's migrations to the old
database. The steps, and what the restore refuses, are under Panel backup and
restore. Do not restore an archive from a newer release onto an older install.
Customers' files, sites and databases come back from the account backups.