Upgrade Guide

This page explains how to upgrade an existing Mopheus deployment. Before upgrading, confirm the installation directory, backup strategy, and target version, and make sure no maintenance operation is in progress.

Online Service Upgrade

From the existing installation directory, check the current and remote versions first:

cd /app/mopheus
./mopheus.sh online-version

After confirming the target version, run the upgrade:

# Auto-detect and upgrade to the latest stable version
./mopheus.sh online-update

# Use the dev channel
./mopheus.sh online-update --dev

# Specify a target version
./mopheus.sh online-update --tag v1.2.3

Use dry run when you need to preview the changes first:

./mopheus.sh online-update --dry-run

After the upgrade, check the service status and logs:

./mopheus.sh status
./mopheus.sh ps
./mopheus.sh logs

Offline Service Upgrade

Upload the target version's offline package to the server, then run the following command from the existing installation directory:

cd /app/mopheus
./mopheus.sh update-offline /tmp/mopheus-install-<new-version>-linux-<arch>.tar.gz

To force reinstall the CLI tools included in the package:

./mopheus.sh update-offline \
  /tmp/mopheus-install-<new-version>-linux-<arch>.tar.gz \
  --reinstall

First Upgrade from a Pre-Rename Installation

For the first upgrade from an installation created before the product rename, use the bootstrap script from the new package:

cd /path/to/existing-installation
mkdir -p /tmp/mopheus-upgrade
tar -zxvf /tmp/mopheus-install-<new-version>-linux-<arch>.tar.gz \
  -C /tmp/mopheus-upgrade
/tmp/mopheus-upgrade/upgrade-offline.sh --install-dir "$PWD" \
  /tmp/mopheus-install-<new-version>-linux-<arch>.tar.gz

Important: Do not run setup.sh update-offline from a pre-rename installation. That updater only recognizes the old package layout and cannot install the new migration logic.

Before changing files, the upgrade creates a configuration snapshot at backups/<old-version>-<timestamp>/. The snapshot contains .env, the active docker-compose.yml, nginx/, and newapi/. Application data remains in data/ and is not copied or removed by the upgrade.

CLI Upgrade

# Upgrade to the latest stable release
mopheus upgrade

# Upgrade to the latest development build
mopheus upgrade --dev

# Install a specific version
mopheus upgrade --version v1.1.0

After upgrading the CLI, check its version and current configuration:

mopheus version
mopheus config show

Post-Upgrade Checks

1. Run ./mopheus.sh status and confirm that the services are healthy.
2. Run ./mopheus.sh logs and check startup and database migration logs.
3. Log in to the Web UI and confirm that workspaces, tickets, and files are accessible.
4. If you use a daemon, run mopheus daemon status and confirm that the runtime has reconnected.