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 scenesconfig/.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 Method | App Location | Data Location | Config |
|---|---|---|---|
| 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/ |
| Docker | Inside container | smart-panel-data Docker volume | Inside volume |
Systemd Installations (image, npm, one-liner)
Stop the services
sudo systemctl stop smart-panel smart-panel-displayCreate 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-displayDocker 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-displayDocker 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 -dIf 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 versionThere 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.gzfrom GitHub Releases - Extract it to
/opt/smart-panel/vX.Y.Z/ - Install production dependencies and rebuild native modules
- Stop the service, switch the
currentsymlink, run database migrations, and restart
Update via CLI
sudo smart-panel-service updateThis performs the same steps as the Admin UI update.
How It Works
The image-based updater follows a safe, atomic process:
- Downloads the release archive from GitHub
- Extracts it to a new versioned directory (
/opt/smart-panel/vX.Y.Z/) - Installs production dependencies and rebuilds native modules
- Stops the service
- Switches the
currentsymlink to the new version - Runs database migrations
- 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-panelRolling 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 -dThe container automatically runs pending database migrations on startup.
One-Liner / npm Global Install
sudo smart-panel-service updateThis downloads the latest version, runs migrations, and restarts the services.
Manual Tarball Install
Stop services
sudo systemctl stop smart-panel smart-panel-displayDownload the latest release
curl -sL https://github.com/FastyBird/smart-panel/releases/latest/download/smart-panel.tar.gz \
-o /tmp/smart-panel.tar.gzExtract over existing installation
sudo tar xzf /tmp/smart-panel.tar.gz -C /opt/smart-panel --strip-components=1Install dependencies
cd /opt/smart-panel && pnpm install --productionStart services
sudo systemctl start smart-panel smart-panel-displayDatabase 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.3npm
npm install -g @fastybird/smart-panel@1.2.3Rolling Back
If an update causes problems:
- Stop the services
- Restore your backup (see above)
- Install the previous version using the pinning method above
- 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?
- Check the Troubleshooting guide if you encounter issues after updating
- Visit the GitHub Releases page for changelogs