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

Backup

Your Smart Panel stores two important files:

• config/config.yaml — system configuration (plugins, weather, display settings)
• data/database.sqlite — all devices, dashboards, users, and scenes

The location depends on your installation method:

Systemd Installations (image, npm, one-liner)

sudo systemctl stop smart-panel smart-panel-display

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

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 .

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

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

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.

Manual Rollback (Image Install)

If you need to manually revert to a previous version:

# 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

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

sudo systemctl stop smart-panel smart-panel-display

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

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

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

sudo systemctl start smart-panel smart-panel-display

Database migrations run automatically when the backend starts.

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

What’s Next?

• Check the Troubleshooting guide if you encounter issues after updating
• Visit the GitHub Releases  page for changelogs