Skip to content
Maran

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:

bash
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:

bash
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:

bash
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

ItemOn a re-run
Security__EncryptionKey in /etc/maran/panel.envKept. It is never rotated, since a new key would make stored secrets unreadable.
Jwt__SigningKey in /etc/maran/panel.envKept, so people stay signed in across the upgrade.
The agent's free-space floor in /etc/maran/agent.envKept when it is a whole number from 1.
The rest of panel.envWritten 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 tokenReplaced with a new one. It only matters before the first administrator exists.
The panel's databaseKept, and brought forward by the new release's migrations.
The panel and the agent programsReplaced 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:

bash
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.

  1. Read the end of /var/log/maran/install.log and the message the installer printed.
  2. 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.
  3. If the panel does not start, read journalctl -u maran-api and journalctl -u maran-agent, and run maran status, which works even with the panel down. maran collect-diagnostics writes 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.