Skip to Content
🚀 We just launched! Please star us on Github!
DocumentationUpdating & Backup

Updating & Backup

Smart Panel is actively developed, and updates bring new features, bug fixes, and security patches. This guide covers how to safely update your installation and back up your data.


Before You Update

Always back up your data before updating. While updates include automatic database migrations, it’s good practice to have a recovery point.


Backup

Your Smart Panel stores its database and an owner-only configuration directory. Important contents include:

  • config/config.yaml — system configuration (plugins, weather, display settings)
  • data/database.sqlite — all devices, dashboards, users, and scenes
  • config/.mcp-oauth-provider.json — private OAuth signing and cookie material after MCP OAuth is first activated

Backups are not encrypted. The configuration can contain resolved write-only secrets, and the database contains installation identity and authorization metadata. Restrict backup access and securely remove obsolete copies.

The location depends on your installation method:

Installation MethodApp LocationData LocationConfig
Pre-built Raspbian image/opt/smart-panel/current//var/lib/smart-panel//etc/smart-panel/environment
One-liner script or npm global/usr/lib/node_modules/@fastybird/smart-panel//var/lib/smart-panel//var/lib/smart-panel/config/
DockerInside containersmart-panel-data Docker volumeInside volume

Systemd Installations (image, npm, one-liner)

Stop the services

sudo systemctl stop smart-panel smart-panel-display

Create a backup

sudo tar czf ~/smart-panel-backup-$(date +%Y%m%d).tar.gz -C /var/lib/smart-panel .

For pre-built image installations, you may also want to back up /etc/smart-panel/environment which contains your environment configuration.

Restart the services

sudo systemctl start smart-panel smart-panel-display

Docker Installation

docker run --rm -v smart-panel-data:/data -v $(pwd):/backup alpine \ tar czf /backup/smart-panel-backup-$(date +%Y%m%d).tar.gz -C /data .

You don’t need to stop the Docker container to back up, but stopping it ensures data consistency.


Restore from Backup

Systemd Installations

sudo systemctl stop smart-panel smart-panel-display sudo tar xzf ~/smart-panel-backup-YYYYMMDD.tar.gz -C /var/lib/smart-panel sudo systemctl start smart-panel smart-panel-display

Docker Installation

docker compose down docker run --rm -v smart-panel-data:/data -v $(pwd):/backup alpine \ sh -c "rm -rf /data/* && tar xzf /backup/smart-panel-backup-YYYYMMDD.tar.gz -C /data" docker compose up -d

If you restore a backup into a second or cloned installation, the database also copies the installation UUID, MCP clients, OAuth grants, and token hashes, while the configuration copies the OAuth provider’s private material. Keep the clone isolated, assign a dedicated public origin, revoke all OAuth access, and rotate or revoke every copied static MCP credential before allowing access. Follow the complete MCP restore and compromise runbook.


Updating

Pre-built Raspbian Image

When Smart Panel is installed from a pre-built Raspbian image, updates use a versioned directory layout:

/opt/smart-panel/ current -> v1.1.0/ # symlink to active version v1.0.0/ # previous version (kept for rollback) v1.1.0/ # current version

There are two ways to update: through the Admin UI or via the CLI.

Update via Admin UI

Open System Settings

Go to Settings → System in the Admin UI.

Check for updates

Click “Check for Updates”. The system will query GitHub Releases for a newer version.

Install the update

If an update is available, click “Install Update”. The system will:

  • Download smart-panel-server-vX.Y.Z-arm64.tar.gz from GitHub Releases
  • Extract it to /opt/smart-panel/vX.Y.Z/
  • Install production dependencies and rebuild native modules
  • Stop the service, switch the current symlink, run database migrations, and restart

Update via CLI

sudo smart-panel-service update

This performs the same steps as the Admin UI update.

How It Works

The image-based updater follows a safe, atomic process:

  1. Downloads the release archive from GitHub
  2. Extracts it to a new versioned directory (/opt/smart-panel/vX.Y.Z/)
  3. Installs production dependencies and rebuilds native modules
  4. Stops the service
  5. Switches the current symlink to the new version
  6. Runs database migrations
  7. Starts the service

If any step fails, the symlink is reverted to the previous version automatically.

The updater keeps a maximum of 2 previous versions on disk for rollback. Older versions are removed automatically.

Manual Rollback (Image Install)

If you need to manually revert to a previous version:

If the target version predates the MCP migration, stop the backend and satisfy the MCP rollback precondition before switching the symlink or restarting the service. Switching application versions does not run down migrations automatically.

# List available versions ls -la /opt/smart-panel/
# Switch to a previous version sudo ln -sfn /opt/smart-panel/v1.0.0 /opt/smart-panel/current sudo systemctl restart smart-panel

Rolling back after a database migration may cause issues if the schema has changed. Always test updates on a non-critical setup first if possible.

Docker

docker compose pull docker compose up -d

The container automatically runs pending database migrations on startup.

One-Liner / npm Global Install

sudo smart-panel-service update

This downloads the latest version, runs migrations, and restarts the services.

Manual Tarball Install

Stop services

sudo systemctl stop smart-panel smart-panel-display

Download the latest release

curl -sL https://github.com/FastyBird/smart-panel/releases/latest/download/smart-panel.tar.gz \ -o /tmp/smart-panel.tar.gz

Extract over existing installation

sudo tar xzf /tmp/smart-panel.tar.gz -C /opt/smart-panel --strip-components=1

Install dependencies

cd /opt/smart-panel && pnpm install --production

Start services

sudo systemctl start smart-panel smart-panel-display

Database migrations run automatically when the backend starts.


Model Context Protocol Upgrade Notes

The MCP module is added through the incremental 1000000000008-AddMcpClients migration. It creates installation identity and MCP client tables without converting existing users or credentials. Upgraded installations remain safe by default: MCP is disabled, read is preselected as the enablement default, and the additional browser-origin allowlist is empty.

MCP OAuth remains separately opt-in and uses exactly pinned authorization and protocol dependencies. Before deploying a release that changes oidc-provider, its type definitions, or the MCP server/client packages, review the bounded authorization-server and protected-resource metadata snapshots for newly advertised fields or changed defaults. The release must pass the complete OAuth negative/E2E suite plus the recorded Codex and Claude Code smoke profiles before OAuth is re-enabled. An upgraded dependency must never publish Dynamic Client Registration or Client ID Metadata Document support merely because it enables either feature internally; the supported profile continues to use owner/admin pre-registration.

After updating, an owner or administrator must explicitly enable MCP and create finite-lived client credentials. Back up both the database and configuration first.

Before starting any Smart Panel version that predates this migration, stop the backend and either restore a database backup created before the MCP upgrade or explicitly revert 1000000000008-AddMcpClients with the current release’s migration tooling. Do not only switch a symlink or container tag: application rollback does not run down migrations. The migration’s down step deletes MCP-owned tokens before older authentication code can load them.

See Model Context Protocol for setup, security guidance, and the exact curated catalog.

Rolling Back MCP OAuth

If an upgrade changes OAuth metadata or breaks either supported host profile, use the Admin MCP settings to disable OAuth before rolling back. Disabling OAuth closes its public route gate, revokes its grants and provider artifacts, and closes OAuth subscriptions while preserving registered OAuth clients and the independent static bearer profile. Static LAN/VPN clients can therefore remain available during diagnosis.

Do not attempt to convert, reissue, or reuse an OAuth token as a static credential. Restore the previous application version only after OAuth is disabled and the database schema is compatible with that version. After rollback, keep OAuth disabled until the previous version’s metadata snapshots and target-host smoke profile have been verified, then require every OAuth client to complete a fresh authorization flow.


Pinning a Version

Docker

Edit your docker-compose.yml to use a specific tag:

services: smart-panel: image: ghcr.io/fastybird/smart-panel:1.2.3

npm

npm install -g @fastybird/smart-panel@1.2.3

Rolling Back

If an update causes problems:

  1. Stop the services
  2. Restore your backup (see above)
  3. Install the previous version using the pinning method above
  4. Start the services

For pre-built image installations, switch the symlink as described in Manual Rollback only after satisfying any schema rollback requirements. A target version that predates MCP must follow the MCP rollback precondition.

Rolling back after a database migration may cause issues if the schema has changed. Always test updates on a non-critical setup first if possible.


What’s Next?

Last updated on