Updates and rollback

This document explains how a panel update is offered and started, what the Updates page shows, what is kept for a rollback, what happens when a step fails and how to go back to the previous version.

Updates come from the license server at https://api.xtreamgo.io. Some messages on the Updates page use another name for this server. This document quotes those messages and gives their meaning.

Before you start

• Take a database backup before every update. A new version can change the database structure when it starts. No rollback step restores the database. See Backup and restore.
• Updates are delivered by the license server over SSH. It needs valid SSH access details for your server. Read the section "SSH access for updates".
• Keep a few GB of free disk space. The new images are copied to the server and loaded next to the running ones. Old images are removed only after a successful update.
• Your license must be active. The update request must come from the IP address the license is bound to.
• Only users of the administrator groups can start an update.

How an update is offered

1. The panel asks the license server for the newest published release and sends its own running version. This happens when the dashboard loads, every 4 hours while it stays open, each time you open the Updates page and when you press Check for Updates.
2. When a newer release exists, the dashboard shows an update notice with the button Update Now. The button opens the Updates page.
3. The Updates page is in the sidebar group Setup & Migration under the entry New Updates. Its address is /dashboard/updates.
4. The page shows Update Available, the Current and the Latest version, the release type and the release notes. The notes are grouped as New Features, Bug Fixes and Improvements.

A panel that already runs the newest release shows System is Up to Date, its version and the time of the last check.

How an update is started

1. An administrator presses Install Now on the Updates page.
2. The panel sends an update request with its license key to the license server.
3. The license server checks the request. The license must be active, the request must come from the bound IP address, SSH details must be registered for the license and no other update may be running for the license.
4. The license server connects to your server over SSH and carries out the update. The page shows the live progress.

The update is a push from the license server. Your panel does not download images by itself. The xtreamgo update command on the server does not download a new version either. See Install the main server.

The buttons Tonight (03:00), Tomorrow Night and This Weekend are not active. The page says Scheduled updates are coming soon. Use Install Now to update immediately.

SSH access for updates

Updates are delivered by the license server over SSH. It logs in to your server with the server access details registered for your license: the SSH port, the user and the password. The password is stored encrypted. The install directory defaults to /home/xtreamgo.

How the access details are registered:

• If you bought the panel with the automatic setup on the XtreamGo website, the SSH details you entered at purchase are registered for the license.
• If you installed the panel yourself with install.sh, no SSH details are registered. An update request fails until they are. Ask XtreamGo support to register the SSH details for your license.
• The function to change the server in the customer dashboard also registers the SSH details of the new server. See License.

What you must keep valid:

• Password login for the registered user must be allowed on the server.
• The SSH port must be reachable from the license server.
• If you change the SSH password or port of the server, updates fail with SSH connection failed. Check the panel's SSH settings and network. until the registered details are corrected.
• If you reinstall the operating system, the SSH host key of the server changes. Updates then fail with The panel server's SSH key changed. If the server was reinstalled, save its SSH settings again to accept the new key. until the details are registered again.

To change or renew the registered details, contact XtreamGo support.

When the license server does not accept an update request, the Updates page shows Could not reach CMS. Please update from CMS panel → Releases → Deploy. The name in this message means the license server. The page named in the message is not available to operators. Contact XtreamGo support when you see this text. The usual causes are listed in the section "If something goes wrong".

What the update does on your server

A release names its components. The default is api and frontend. A release can also include portal.

Every release installs exact, fixed images. The license server does not send whatever image is newest at that moment. For each component it sends the image that was recorded for the release, and your server checks it twice before use.

The API runs in two alternating containers named xtreamgo-api-blue and xtreamgo-api-green. This is called blue/green mode: the panel keeps the previous API version stopped next to the new one so it can switch back. After the first update the original container xtreamgo-api is stopped and kept.

After a panel update the panel also refreshes the agent program on your own load balancers. The agent accepts only a signed file and restores its previous version when the new one does not stay up for 60 seconds.

What is kept for a rollback

The image cleanup at the end of an update never removes an image that a container uses, running or stopped. It also keeps the latest tags, the two rollback-pre-update tags and the images of the release just installed.

A rollback therefore stays possible after a successful update. It goes back one version, not further.

What the Updates page shows

During an update the page shows a progress card with a percentage, the elapsed time, the label Live from the CMS and the text of the current step. The name in this label means the license server.

You can leave the Updates page during an update. The update is driven by the license server and continues. The dashboard shows Update in progress… with a link View status, and the Updates page shows the live progress again when you return.

During the API switch viewers and the panel stay connected. The admin interface container is recreated, so the browser can lose the page for a short moment.

What happens automatically on failure

The Updates page then shows one of these results:

• The reason alone, for example The new API did not pass its checks; the panel kept running the old API. Nothing was switched, so nothing had to be restored. When no reason is available the text is The update stopped before anything was changed on your panel.
• The update did not pass its checks, so the previous version was restored. Your panel keeps running as before. followed by the reason. A service was switched and the automatic restore succeeded.
• A reason that ends with Restoring the previous version failed too; check the panel now. The automatic restore did not complete. Contact XtreamGo support at once and do not restart containers yourself.

How to request a rollback

The panel has no rollback button. There are two ways.

Ask XtreamGo support

Write to XtreamGo support and name your license and the version you updated to. Support starts a rollback for your panel over the same SSH access as an update. The rollback:

1. Runs scripts/fast_rollback.sh to switch the API back to the kept container.
2. Sets the admin interface and the portal back to their rollback-pre-update images, where such an image exists.
3. Reads the panel version before and after.

If no kept API container exists, or it fails its checks, the rollback stops and the current API keeps running.

Do it on the server

API:

cat /home/xtreamgo/nginx/.bg-rollback.meta
bash /home/xtreamgo/scripts/fast_rollback.sh

The script works when the file .bg-rollback.meta exists. It checks that the kept container still has the recorded image, starts it, waits up to 60 seconds for its health check, moves the traffic, checks that requests reach the old version and only then stops the newer container. It ends with Fast rollback complete: now serving '<slot>'.

Admin interface (use portal in place of frontend for the customer portal):

cd /home/xtreamgo
docker image inspect xtreamgo-frontend:rollback-pre-update >/dev/null && \
  docker tag xtreamgo-frontend:rollback-pre-update xtreamgo-frontend:latest && \
  docker compose --env-file .env.production up -d --no-deps frontend

A rollback by XtreamGo support runs the same commands. Keep --no-deps. Without it Docker Compose also starts the original xtreamgo-api container next to the live one.

Limits of a rollback:

• It does not restore the database. If the newer version changed the database structure, the older API may not work with it. Restore your backup from before the update in that case, or contact XtreamGo support first.
• The API rollback works once. After a rollback the file .bg-rollback.meta is removed.
• It goes back one version only.

Manual installation of an update

An update cannot be installed by hand. New versions arrive only through the Updates page. xtreamgo deploy [image] only switches to an API image that is already loaded on the server. Otherwise it stops with a message that starts with image '<name>' not loaded.

How to check the running version

curl -s http://127.0.0.1/api/v1/build/info
docker ps --filter name=xtreamgo- --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
sed -n '/BG_UPSTREAM_BEGIN/,/BG_UPSTREAM_END/p' /home/xtreamgo/nginx/nginx.conf
cat /home/xtreamgo/nginx/.bg-rollback.meta 2>/dev/null
docker images | grep -E 'xtreamgo-(api|frontend|portal)'

Expected results after an update:

• build/info shows the new version, the slot (blue or green) and a recent started_at.
• Exactly one running API container, with status healthy.
• The upstream block names only the running API container.
• .bg-rollback.meta names the stopped container of the previous version.
• The image list shows the tag rollback-pre-update for each interface service that was updated.
• The Updates page shows System is Up to Date and the new version.

If something goes wrong