Updating the Panel

This guide covers how to update your BadgerPanel installation to the latest version. Updates are delivered as new Docker images and may include database migrations that run automatically on startup.

Always Back Up First

Before updating, always create a backup of your database and configuration. Updates may include database migrations that cannot be reversed.

Before You Begin

Check the Changelog

Before updating, review the release notes for any breaking changes, new required environment variables, or manual migration steps.

Create a Backup

cd /opt/badgerpanel

# Back up the environment file
cp .env .env.backup.$(date +%Y%m%d)

# Back up the MySQL database
docker compose exec mysql mysqldump -u root -p"$DB_ROOT_PASSWORD" badgerpanel > backup_$(date +%Y%m%d).sql

# Back up Nginx configuration
cp -r nginx/ nginx.backup.$(date +%Y%m%d)/

Automated Database Backups

For production environments, set up automated daily backups of your MySQL database. Store backups off-server in case of hardware failure.

Standard Update Process

Step 1: Pull Latest Images

cd /opt/badgerpanel

# Pull the latest images for all services
docker compose pull

This downloads the latest versions of the API, Web, and supporting service images.

Step 2: Pull Repository Changes

If you cloned BadgerPanel from Git, also pull the latest compose file and configuration changes:

cd /opt/badgerpanel
git pull origin main

Custom Changes

If you have made local modifications to docker-compose.yml or Nginx configuration, git pull may cause merge conflicts. Use docker-compose.override.yml for custom modifications instead of editing the main compose file directly.

Step 3: Restart Services

cd /opt/badgerpanel

# Stop and recreate containers with the new images
docker compose up -d

Docker Compose will:

1. Stop containers that have newer images available
2. Recreate those containers with the updated images
3. Leave unchanged services running

Step 4: Verify the Update

# Check that all services are running
docker compose ps

# Check API logs for successful startup and migration completion
docker compose logs api --tail 50

Look for log lines indicating:

• Database migrations completed successfully
• API server started and listening
• No error messages

Step 5: Verify in the Browser

Open your panel in the browser and verify:

1. You can log in successfully
2. The admin dashboard loads without errors
3. Server list and console are working
4. Any new features from the update are visible

Handling Database Migrations

BadgerPanel runs database migrations automatically when the API service starts. If a migration fails:

Check Migration Logs

docker compose logs api | grep -i migration

Common Migration Issues

"Table already exists"

This can happen if a previous update was interrupted mid-migration. Check the schema_migrations table in MySQL to see which migrations have been applied:

docker compose exec mysql mysql -u root -p"$DB_ROOT_PASSWORD" badgerpanel \
  -e "SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 10;"

"Column already exists"

Similar to above -- a migration may have partially completed. Contact support or check the specific migration file for manual resolution steps.

"Access denied"

Ensure the DB_USERNAME has sufficient privileges. The migration user needs CREATE, ALTER, DROP, INDEX, and standard CRUD permissions.

Rolling Back

If an update causes issues, you can roll back to the previous version:

Step 1: Stop the Panel

cd /opt/badgerpanel
docker compose down

Step 2: Restore the Database Backup

# Restore the database from your backup
docker compose up -d mysql
docker compose exec -T mysql mysql -u root -p"$DB_ROOT_PASSWORD" badgerpanel < backup_YYYYMMDD.sql

Step 3: Restore Configuration

# Restore the environment file if needed
cp .env.backup.YYYYMMDD .env

Step 4: Use Previous Image Tags

If the previous version used specific image tags, update your docker-compose.yml to pin those versions:

services:
  api:
    image: badgerpanel/api:1.0.0  # Pin to specific version
  web:
    image: badgerpanel/web:1.0.0  # Pin to specific version

Then restart:

docker compose up -d

Database Rollbacks

Rolling back the database to a backup will lose any data created after the backup was taken. This includes new users, servers, billing records, and configuration changes.

Updating Supporting Services

Occasionally, you may need to update MySQL, Redis, or other supporting services:

MySQL

# MySQL minor version updates (e.g., 8.0.35 to 8.0.36) are safe
docker compose pull mysql
docker compose up -d mysql

MySQL Major Upgrades

Do not jump MySQL major versions (e.g., 8.0 to 9.0) without reading the MySQL upgrade documentation first. Major upgrades may require data directory conversion.

Redis

docker compose pull redis
docker compose up -d redis

Redis updates within the same major version (7.x) are generally backward compatible.

Nginx

docker compose pull nginx
docker compose up -d nginx

Maintenance Window

For production environments, plan updates during a maintenance window:

1. Announce downtime -- Use the Announcements feature to notify users in advance
2. Enable maintenance mode -- In Admin > Settings, enable maintenance mode (users see a maintenance page)
3. Perform the update following the steps above
4. Verify everything works
5. Disable maintenance mode
6. Notify users that the update is complete

Next Steps

• Troubleshooting -- Common issues after updates
• Configuration -- New environment variables may be required