Skip to main content
Regular backups are essential for protecting your Homarr configuration, boards, and settings. This guide covers backup strategies for all supported database types and how to restore your data.

​
What to Backup

A complete Homarr backup includes three components:

Database

Contains all your configuration:
  • User accounts and groups
  • Boards and widgets
  • Integrations
  • Settings and preferences

Configuration Files

Environment variables and settings:
  • .env file
  • docker-compose.yml
  • Custom configuration files

Data Directory

Application data:
  • Icons and images
  • Uploaded assets
  • Certificates
  • Logs (optional)
Your .env file contains sensitive information including encryption keys. Never commit it to version control and store backups securely.

​
Database Backup Procedures

Backup procedures vary by database type. Identify your database driver from your .env file: 
DB_DRIVER='better-sqlite3'  # SQLite
DB_DRIVER='mysql2'          # MySQL/MariaDB
DB_DRIVER='node-postgres'   # PostgreSQL

​
SQLite Backup

SQLite stores everything in a single file, making backups straightforward.
1

Locate Database File

Check your .env file for the database location:
DB_URL='/app/data/db.sqlite'
The database file is typically in your data directory.
2

Stop Homarr (Recommended)

For the most consistent backup, stop Homarr before copying the database:
# Docker
docker stop homarr

# Docker Compose
docker compose down
You can backup while Homarr is running, but may risk data inconsistency during active writes.
3

Copy Database File

Copy the SQLite database file to your backup location:
# Docker - copy from container
docker cp homarr:/app/data/db.sqlite ./backups/db-$(date +%Y%m%d).sqlite

# Bare Metal - direct copy
cp /path/to/homarr/data/db.sqlite /path/to/backups/db-$(date +%Y%m%d).sqlite
4

Restart Homarr

Start Homarr again:
# Docker
docker start homarr

# Docker Compose
docker compose up -d

​
SQLite Online Backup

For backups without downtime, use SQLite’s built-in backup command: 
# Using sqlite3 command
sqlite3 /path/to/db.sqlite ".backup /path/to/backups/db-$(date +%Y%m%d).sqlite"

# Docker example
docker exec homarr sqlite3 /app/data/db.sqlite ".backup /app/data/backup.sqlite"
docker cp homarr:/app/data/backup.sqlite ./backups/

​
MySQL/MariaDB Backup

Use mysqldump to create SQL backup files.
1

Get Database Credentials

From your .env file or Docker Compose configuration:
DB_HOST='localhost'
DB_PORT='3306'
DB_USER='homarr'
DB_PASSWORD='your_password'
DB_NAME='homarrdb'
2

Create Backup

Use mysqldump to export the database:
# Standard backup
mysqldump -h localhost -P 3306 -u homarr -p homarrdb > backup-$(date +%Y%m%d).sql

# With compression
mysqldump -h localhost -P 3306 -u homarr -p homarrdb | gzip > backup-$(date +%Y%m%d).sql.gz
Enter the database password when prompted.
3

Backup from Docker

If MySQL is in a Docker container:
docker exec mysql-container mysqldump -u homarr -p homarrdb > backup-$(date +%Y%m%d).sql

# Or using docker compose
docker compose exec -T db mysqldump -u homarr -ppassword homarrdb > backup-$(date +%Y%m%d).sql
Add --single-transaction flag for InnoDB tables to ensure consistent backups without locking:
mysqldump --single-transaction -u homarr -p homarrdb > backup.sql

​
PostgreSQL Backup

Use pg_dump to create PostgreSQL backups.
1

Get Database Credentials

From your .env file:
DB_URL='postgres://homarr:password@localhost:5432/homarrdb'
Or individual variables:
DB_HOST='localhost'
DB_PORT='5432'
DB_USER='homarr'
DB_PASSWORD='password'
DB_NAME='homarrdb'
2

Create Backup

Use pg_dump to export:
# Custom format (recommended - supports parallel restore)
pg_dump -h localhost -p 5432 -U homarr -Fc homarrdb > backup-$(date +%Y%m%d).dump

# Plain SQL format
pg_dump -h localhost -p 5432 -U homarr homarrdb > backup-$(date +%Y%m%d).sql

# Compressed SQL
pg_dump -h localhost -p 5432 -U homarr homarrdb | gzip > backup-$(date +%Y%m%d).sql.gz
3

Backup from Docker

If PostgreSQL is in a Docker container:
# Custom format
docker exec postgres-container pg_dump -U homarr -Fc homarrdb > backup-$(date +%Y%m%d).dump

# Using docker compose
docker compose exec -T db pg_dump -U homarr -Fc homarrdb > backup-$(date +%Y%m%d).dump
PostgreSQL custom format (.dump) is recommended as it supports parallel restoration and selective table restoration.

​
Configuration and Data Backup

​
Environment Variables

Backup your .env file securely: 
# Create encrypted backup
cp .env .env.backup-$(date +%Y%m%d)

# Or with encryption (recommended)
tar czf - .env | openssl enc -aes-256-cbc -out env-backup-$(date +%Y%m%d).tar.gz.enc
The .env file contains:
  • SECRET_ENCRYPTION_KEY - Required to decrypt integration secrets
  • AUTH_SECRET - Used for session encryption
Losing these keys means losing access to encrypted data!

​
Docker Compose Configuration

Backup your Docker Compose file: 
cp docker-compose.yml docker-compose-backup-$(date +%Y%m%d).yml

​
Data Directory

Backup the application data directory: 
# Docker volume backup
docker run --rm -v homarr-data:/data -v $(pwd)/backups:/backup alpine tar czf /backup/data-$(date +%Y%m%d).tar.gz /data

# Direct directory backup
tar czf backups/data-$(date +%Y%m%d).tar.gz /path/to/homarr/data

​
Restore Procedures

​
SQLite Restore

1

Stop Homarr

docker stop homarr
# or
docker compose down
2

Replace Database File

# Docker - copy to container
docker cp ./backups/db-backup.sqlite homarr:/app/data/db.sqlite

# Bare Metal - direct copy
cp ./backups/db-backup.sqlite /path/to/homarr/data/db.sqlite
3

Set Permissions

Ensure Homarr can read/write the database:
# Docker
docker exec homarr chown node:node /app/data/db.sqlite

# Bare Metal
chown homarr:homarr /path/to/homarr/data/db.sqlite
chmod 644 /path/to/homarr/data/db.sqlite
4

Start Homarr

docker start homarr
# or
docker compose up -d

​
MySQL/MariaDB Restore

1

Prepare Database

Optionally drop and recreate the database for a clean restore:
mysql -u root -p -e "DROP DATABASE IF EXISTS homarrdb; CREATE DATABASE homarrdb;"
2

Restore Backup

# From SQL file
mysql -u homarr -p homarrdb < backup.sql

# From compressed backup
gunzip < backup.sql.gz | mysql -u homarr -p homarrdb

# Docker container
docker exec -i mysql-container mysql -u homarr -p homarrdb < backup.sql
3

Verify Restoration

Check that tables were restored:
mysql -u homarr -p homarrdb -e "SHOW TABLES;"

​
PostgreSQL Restore

1

Prepare Database

Drop and recreate the database:
dropdb -U homarr homarrdb
createdb -U homarr homarrdb
2

Restore Backup

# From custom format
pg_restore -U homarr -d homarrdb backup.dump

# From SQL file
psql -U homarr -d homarrdb < backup.sql

# From compressed SQL
gunzip < backup.sql.gz | psql -U homarr -d homarrdb

# Docker container
docker exec -i postgres-container pg_restore -U homarr -d homarrdb < backup.dump
3

Verify Restoration

psql -U homarr -d homarrdb -c "\dt"

​
Restore Configuration and Data

# Restore .env file
cp .env.backup .env

# Or decrypt encrypted backup
openssl enc -aes-256-cbc -d -in env-backup.tar.gz.enc | tar xzf -

# Restore data directory
tar xzf data-backup.tar.gz -C /path/to/homarr/

# Docker volume restore
docker run --rm -v homarr-data:/data -v $(pwd)/backups:/backup alpine tar xzf /backup/data-backup.tar.gz -C /

​
Automated Backup Strategies

​
Backup Script

Create a backup script for automation: 
#!/bin/bash
# backup-homarr.sh

BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d-%H%M%S)
RETENTION_DAYS=30

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Database backup (SQLite example)
cp /path/to/homarr/data/db.sqlite "$BACKUP_DIR/db-$DATE.sqlite"

# Configuration backup
cp /path/to/homarr/.env "$BACKUP_DIR/env-$DATE"
cp /path/to/homarr/docker-compose.yml "$BACKUP_DIR/compose-$DATE.yml"

# Data directory backup
tar czf "$BACKUP_DIR/data-$DATE.tar.gz" /path/to/homarr/data

# Remove old backups
find "$BACKUP_DIR" -type f -mtime +$RETENTION_DAYS -delete

echo "Backup completed: $DATE"

​
Cron Job

Schedule automated backups with cron: 
# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * /path/to/backup-homarr.sh

# Add weekly backup on Sunday at 3 AM
0 3 * * 0 /path/to/backup-homarr.sh

​
Docker Backup Container

Use a backup container for automated Docker backups: 
services:
  backup:
    image: offen/docker-volume-backup:latest
    environment:
      BACKUP_CRON_EXPRESSION: "0 2 * * *"
      BACKUP_FILENAME: homarr-backup-%Y%m%d.tar.gz
      BACKUP_RETENTION_DAYS: "30"
    volumes:
      - homarr-data:/backup/homarr-data:ro
      - ./backups:/archive

​
Backup Best Practices

3-2-1 Rule

  • 3 copies of your data
  • 2 different storage media
  • 1 copy off-site
Example: Original + local backup + cloud backup

Automation

  • Schedule regular automated backups
  • Test restore procedures periodically
  • Monitor backup success/failure
  • Alert on backup failures

Security

  • Encrypt backups containing sensitive data
  • Secure backup storage locations
  • Restrict access to backup files
  • Include encryption keys in secure storage

Retention

  • Keep multiple backup versions
  • Balance storage cost vs. retention period
  • Follow 7 daily + 4 weekly + 12 monthly pattern
  • Document retention policy

​
Testing Your Backups

Untested backups are unreliable backups. Regularly verify that your backups can be restored successfully.

​
Test Restore Procedure

1

Prepare Test Environment

Set up a separate test instance of Homarr to avoid affecting production.
2

Perform Restore

Follow the restore procedures using your latest backup.
3

Verify Data

  • Check all boards load correctly
  • Verify users can log in
  • Test widget functionality
  • Confirm integrations work
4

Document Results

Record the test date, any issues found, and resolution time.
Recommended test frequency:
  • Monthly for production systems
  • Quarterly for personal instances
  • After any major configuration changes

​
Disaster Recovery

In case of complete data loss:
1

Reinstall Homarr

Deploy a fresh Homarr instance following the installation guide.
2

Restore Configuration

Copy your .env and docker-compose.yml files from backup.
The SECRET_ENCRYPTION_KEY must match the original for encrypted data to be accessible.
3

Restore Database

Follow the restore procedure for your database type.
4

Restore Data Directory

Extract your data directory backup.
5

Verify and Test

Start Homarr and verify all functionality is restored.

​
Next Steps

Migration Guide

Learn how to migrate between database types or upgrade versions

Database Configuration

Detailed database setup and configuration

Docker Installation

Deploy Homarr with Docker Compose

Troubleshooting

Get help with backup and restore issues

Build docs developers (and LLMs) love

Get started for freeTalk to us