Update SixPanel itself

Updating SixPanel is not the same as updating your 6ammart code. They are two separate things, they use two different commands, and mixing them up is the most common mistake on this page.

This page is about the second one. For the first, see Deploy and update your code. For the third, see Server updates and restarts.

You need

• Root SSH access, or the panel open on the Settings page.
• The server able to reach the internet over HTTPS. An update is downloaded from the same signed release channel your installer used. There is no offline update path.
• A recent backup. Take one now if you are unsure:

  sudo sixpanel backup run full

1. Which build am I on?

The version is printed under the product name in the panel's sidebar, on every page — so you never have to hunt for it. A chip next to it appears when there is something to act on, and it links to the button.

The first-run setup shows the same notice at the top of its card. While you are still answering the setup's questions on your very first sign-in, it only tells you a newer release is out: finish (or exit) the setup, then install it from Settings. If you reopen the setup later from Home, the notice has a Settings button.

Over SSH:

sudo sixpanel version

It prints the CLI version, the SixPanel version, the panel version, and the Node, nginx, PHP, MariaDB, kernel and OS versions.

It also tells you when those numbers disagree with each other — for example when the panel has been updated but the sixpanel command on the server is still the older one. That matters, because the command line is what you reach for when the panel will not let you in. Re-running the update settles it.

On older servers the CLI line could not be trusted: it reported the version of the folder it was pointed at rather than its own, so a command line several releases behind still printed the current number, and updates from the panel never replaced it on a server installed from the published link. Both are fixed. If your server has taken an update from the panel since then, the number is the command line's own.

2. Update from the panel

1. Open Settings (in the Panel menu group).
2. Find the panel-updates card. It shows the version this server runs, and one of these answers:

• This is the newest published version. — nothing to do.
• A newer version has been published — with a link to what changed.
• Installed but not running yet — a previous update landed on disk and the panel has not restarted. It finishes when the panel restarts, and the card says so.
• Could not be checked — treat that as unknown rather than up to date. Nothing was changed and your project is running normally.

3. Read what changed, then press the install button and confirm.

Watch the log. The last step restarts the panel itself, so the page disconnects for a few seconds. You do not reload anything: the page says Updated — this page reloads by itself, and it does, as soon as the updated panel answers.

So does every other tab or window you have the panel open in — within about a minute, or the moment you look at it again. A tab is never reloaded under your hands: if a dialog is open, a field on the page holds something you typed and have not saved, a file is uploading, a Terminal session is running or the first-run setup is open, that tab shows a bar instead — SixPanel was updated with a Reload button — and reloads when you press it or go to another page. A tab waiting at the sign-in screen is not reloaded either: what you typed stays, and the bar is there once you have signed in. The same happens after an update that ran by itself at night.

Most updates leave your project open the whole time. If an update also rebuilds the customer website, that website is unreachable for a few seconds while it restarts — visitors see an error, not a slow page — so prefer a quiet hour.

Release channels

SixPanel publishes its releases on two channels:

• Stable — the most tested releases, and the recommended choice for every live site. Every release here has already run on real servers.
• Latest — the newest release, published once it is fully tested and ready for production. After it has run on real servers for a while, the same release moves to Stable.

Every server installed with the usual command starts on Stable, and every server installed before channels existed is on it. A server can also start on Latest: see Install. A server that runs 1.4.x has no channel card — the card came with 1.5.0 — and stays on Stable.

Settings → Updates, on the Release channel card, shows the two to choose from (it can take a few hours after a new channel launches before a server's next update check notices it). A Latest server is still offered a newer Stable release, so it is never stuck behind one. Switching installs nothing by itself: the next check offers releases from the new channel, and you still decide when to press the button. Each choice shows the version its channel carries, and a switch never moves a server back. Moving to Latest is always open. Moving to Stable is open once Stable carries the same version as the server or a newer one; until then the card shows which version it is waiting for.

3. Update over SSH

Look first, change nothing:

sudo sixpanel server update --check

Then apply it:

sudo sixpanel server update

It tells you what changes, what restarts and how to undo, then asks. The old name sudo sixpanel update still works and still means this — it prints a note saying so.

4. What actually happens

1. The signed release record is fetched and its signature is checked against a key that was pinned onto this server when you installed it. If the signature does not match, nothing is changed and the update stops. A build older than the one you run is refused too, and so is a release record that has gone stale.
2. The small installer script that does the work is downloaded and checked against the fingerprint inside that signed record before it is run. If the two disagree, both fingerprints are printed and nothing runs. The key on your server is also what the installer verifies the release against — it is never replaced by whatever key the installer happens to carry, only by a new key that arrives signed by the one being replaced.
3. The new release is downloaded and its contents checked against the size and fingerprint in the same signed record.
4. The version your server is running is kept, beside the SixPanel folder (in /opt/sixpanel/.previous), and then the new code is laid over that folder. Files it does not carry — your settings, your data, your certificates, your application code — are not touched. If the new code cannot be laid whole — the disk fills part way — the kept version is put back at once, the update stops and nothing was changed.
5. The Node.js version is matched to what this release needs. See below.
6. Everything the release ships is applied, not merely copied: the web server and PHP settings, the database tuning, the pool your site's PHP runs in, the systemd units, the alerting, the server's own sizing numbers, and the sixpanel command line. This is the step that makes an updated server and a freshly installed one the same server. Configuration that a service has to parse is checked before that service is asked to use it, and put back if it does not parse, so a bad file can never take your site down.
7. The panel's own dependencies are re-installed from the release's lock file.
8. Any migration the release ships is run.
9. The services that are running are brought onto the new configuration. Services you had stopped stay stopped. From the panel, the services are rolled in two ordered groups: everything a visitor's request passes through moves together, then the background workers. Over SSH they are not rolled. nginx and PHP are reloaded, and a service restarts only when the update changed what it runs, such as MariaDB's settings, a project's Redis, or the Node.js your customer website runs on. Either way PHP is reloaded, so a request being served is allowed to finish (it gets up to five seconds), unless the release changes which folders PHP may write to, which takes a PHP restart. The queue worker and the scheduler are paused while the database or a Redis restarts, and started again after it, so they never fail because of it. If the panel itself restarts during that pause, it starts them again as it comes back.
10. The panel restarts last, and is asked whether it answers. If it does not within a minute, the version from step 4 is put back — see If the new version does not start on your server, below.

If the panel restarts in the middle of an update — a reboot, or the server's own automatic updates starting at that moment — the update is not lost. When the panel comes back and the new version is already in place, it finishes the remaining steps itself and the update ends as done, in the same entry on the Activity page. If the update had not installed anything yet, the entry says so, and it is safe to run the update again. If it stopped while the new version was being put in place, the version your server was running is put back whole before the panel starts again: the entry says so, nothing was changed, and it is safe to run the update again. (On a server where nothing could be kept — the update's log says so at step 4 — the entry tells you to finish it with sudo sixpanel server update instead.)

If the new version does not start on your server

A release is started on our own servers before it is published, and it can still fail to start on yours — a setting only your server has, or a Node.js version that could not be installed. Until this was built, that left you with no panel and no word, and the way back was SSH. Now:

• The new panel gets one minute to answer. When it never does, the version that was running before the update is put back and started: the panel's own files, the Node.js version it needs (an update may have moved it) and the sixpanel command line. The panel is away for about a minute and a half instead of twenty seconds. Your websites keep serving the whole time.
• You are told, in three places. The update's entry on the Activity page reads failed, with a sentence like The new SixPanel (build …) did not answer within 60 seconds of starting on this server, so the build it replaced (build …) was put back and is the one running now. Under it are the last lines the new version wrote before it stopped — they are why. The failure e-mail is sent, if e-mail alerts are set up. And the same sentence is in the panel's own log (sudo journalctl -u sixpanel -n 80). Over SSH, sudo sixpanel server update prints it and ends with update failed.
• What is not put back: the serving settings the update applied in step 6 (web server, PHP, database tuning). They were checked before the services took them and your websites are serving on them. Health may list them under Serving configuration with the one command that renders this version's own again; nothing is wrong while they stay.
• Trying again is the same button. Do it once the reason — in those log lines — is dealt with, or tell us and wait for the next release. The weekly maintenance window does not install that same version again by itself: its record shows the panel update as skipped with the reason, and it installs the next version when one is published.

If even the version that was put back does not start, the panel stays down and your websites keep serving. Over SSH, read sudo journalctl -u sixpanel -n 80: the line that begins SixPanel … did not answer says what was done and what to run. It is one of two things:

• Node.js could not be put back (the server could not reach the package source). The line gives the command, which installs exactly the Node.js the version on disk needs and starts the panel:

  sudo bash /opt/sixpanel/installer/install.sh --node-only && sudo systemctl restart sixpanel

• It does not answer either, so what stops the panel is not the new build. Something outside both versions is in the way — a full disk, the panel's port taken by another program, a damaged settings file — and the lines above that one name it. Once it is dealt with, sudo systemctl restart sixpanel starts the panel, and sudo sixpanel server update installs the newest release again from the start.

One earlier version is kept this way, about as large as one release, until the next update replaces it. It is not part of your backups, and nothing runs from it.

Two things an update deliberately does not do. It never upgrades a package your server already has — only one this release newly needs and your server is missing — so an update cannot restart your web server or database for a reason the release did not ask for. And it never touches your database passwords.

Your site is up throughout, apart from short pauses as each service comes back. Expect the panel itself to be away for about ten to twenty seconds at the end — or about a minute and a half when the new version does not start and the one before it is put back.

Never touched by an update: your settings file, your data (database, uploads, certificates, local backups) and your application code.

About that Node.js step

The panel ships as compiled bytecode rather than readable source. Bytecode is accepted by only the exact Node.js version that produced it — not "22 or newer", the exact one. Every release records the version it was built against, and step 5 above installs that version if the server is on a different one. It also holds it there on every update, so the server's own automatic updates cannot move it. If those automatic updates happen to be running at that moment, the step waits for them to finish rather than failing, and it checks that the hold really took; if it cannot, the update's log gives you the one command that holds it.

Two things follow from that, and they are worth knowing:

• Do not change the server's Node.js by hand. Not with apt install nodejs, not with nvm, not by adding another package source. A box that drifts off the pinned version has a panel that will not start, and the panel is where you would normally fix it. If it has already happened, the repair is one command on the server:

  sudo bash /opt/sixpanel/installer/install.sh --node-only

That installs exactly the version the installed release names, and nothing else.

• Node.js on this server belongs to SixPanel. Your 6ammart code runs on PHP; the only things using Node here are the panel itself and the customer website build. If you need a different Node for something of your own, run it somewhere else.

5. When the panel says it cannot do it

Two honest refusals you may meet:

• the jump is too big for the in-place path;
• this server has no pinned release key — the file that proves which releases to trust is missing.

Both have the same answer: fetch the installer again and run it. It is the same one line as the first install, and a re-run over an existing server is the supported update path:

curl -fsSL https://installer.allsweb.net/sixpanel/install.sh -o install.sh
sudo bash install.sh --update

That does the full upgrade path and re-pins the release key. Your settings, data and code are not touched.

How to check it worked

• The version under the product name in the sidebar is the new one.
• Settings says this is the newest published version.
• sudo sixpanel version shows the same number for the CLI, SixPanel and the panel — no disagreement warning.
• sudo sixpanel doctor is green.
• Your site opens as normal.

If it went wrong

• The download did not match its hash — that is almost always an interrupted download. Run the update again.
• The update stopped in the middle — the verified code is already on disk, so it is safe to run again. Then run sudo sixpanel doctor.
• The panel did not come back after the update — give it two minutes: a new version that does not start is replaced by the one before it, and the panel comes back on that (see If the new version does not start on your server). If it still has not, check it from SSH:

  sudo sixpanel service status panel
  sudo sixpanel logs panel -n 80

The log says what the update did and what to run. If it mentions the panel's own code failing to load, the Node.js version is the first thing to check: sudo bash /opt/sixpanel/installer/install.sh --node-only.

• A service did not come back — start it and read its log:

  sudo sixpanel service start all
  sudo sixpanel logs all -n 50

• sixpanel version says the CLI is older than the panel — run sudo sixpanel server update once more. The rescue commands live in the CLI, so a stale one is worth settling straight away.
• You want to go back — there is no "undo update" button: only a version that does not start is taken back, and that happens by itself. For anything else the way back is a backup taken before it. A restore cannot be undone: it writes that snapshot over your live database and files, and everything created since it was taken is lost. Take a fresh backup first, then sudo sixpanel backup list and sudo sixpanel backup restore SNAPSHOT_ID. See Backups.
• The signature check failed — do not retry in a loop and do not work around it. Send us the file from sudo sixpanel support-bundle and wait for an answer.