Last Updated: 3/10/2026

Backup & Restore

Protect your LinkAce data with automated backups to local storage or cloud services. This guide covers complete backup configuration and restoration procedures.

Overview

LinkAce uses the Spatie Laravel Backup package  to provide:

✅ Full application backups - Database + uploaded files
✅ Automated scheduling - Daily backups with configurable timing
✅ Intelligent cleanup - Automatic removal of old backups
✅ Multiple destinations - Local filesystem or S3-compatible storage
✅ Email notifications - Alerts for backup success/failure

Quick Start: Local Backups

Get basic backup protection in 5 minutes.

For Docker Installations

1. Create backup directory:

mkdir ./backups
chmod 0766 ./backups

2. Edit docker-compose.yml:

Uncomment the backup volume line:

services:
  app:
    volumes:
      - ./.env:/app/.env
      - ./backups:/app/storage/app/backups  # Remove the # at start of line

3. Enable backups in .env:

BACKUP_ENABLED=true
BACKUP_DISK=local_backups
BACKUP_NOTIFICATION_EMAIL=your@email.com

4. Restart:

docker compose restart

✅ Done! Backups will run daily at 2:00 AM.

For Non-Docker Installations

1. Ensure storage is writable:

cd /path/to/linkace
chmod -R 0766 storage/app/backups

2. Enable in .env:

BACKUP_ENABLED=true
BACKUP_DISK=local_backups
BACKUP_NOTIFICATION_EMAIL=your@email.com

3. Clear cache:

php artisan config:clear

✅ Done! Backups will run daily at 2:00 AM.

Configuration Options

All backup settings go in your .env file.

Basic Settings

Scheduling

Examples:

BACKUP_RUN_HOUR=03:00      # Run at 3:00 AM
BACKUP_CLEAN_HOUR=02:30    # Clean at 2:30 AM

Retention & Size

Example:

BACKUP_MAX_SIZE=1024  # Allow up to 1GB of backups

How cleanup works:

• When total size exceeds BACKUP_MAX_SIZE, oldest backups are deleted first
• The package keeps a smart mix of recent and historical backups
• See Spatie cleanup strategy  for details

Security

Example:

BACKUP_ARCHIVE_PASSWORD=MySecurePassword123!

⚠️ Important: Store this password securely! You’ll need it to restore backups.

Cloud Backups (S3)

Back up to Amazon S3 or any S3-compatible service.

Supported Services

• Amazon AWS S3
• Backblaze B2
• DigitalOcean Spaces
• Wasabi
• Minio (self-hosted)
• Any S3-compatible service

Amazon AWS S3 Setup

1. Create S3 bucket:

• Log into AWS Console
• Create new S3 bucket
• Note the bucket name and region

2. Create IAM user:

• Create IAM user with programmatic access
• Attach policy with S3 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

• Save Access Key ID and Secret Access Key

3. Configure .env:

BACKUP_ENABLED=true
BACKUP_DISK=s3
BACKUP_NOTIFICATION_EMAIL=your@email.com

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name

4. Restart:

# Docker
docker compose restart
 
# Non-Docker
php artisan config:clear

S3-Compatible Services

For non-AWS services (Backblaze, Minio, etc.):

1. Configure .env:

BACKUP_ENABLED=true
BACKUP_DISK=s3

# Service credentials
AWS_ACCESS_KEY_ID=your-key-id
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name

# Service-specific endpoint
AWS_ENDPOINT=https://s3.us-west-001.backblazeb2.com
AWS_USE_PATH_STYLE_ENDPOINT=true

Service-specific endpoints:

2. Set path-style endpoint (if needed):

Some services require path-style URLs:

AWS_USE_PATH_STYLE_ENDPOINT=true

This changes URL format from:

• Virtual-hosted: https://bucket-name.s3.region.amazonaws.com/file
• Path-style: https://s3.region.amazonaws.com/bucket-name/file

Manual Backups

Create backups on-demand instead of waiting for the schedule.

Run Manual Backup

Docker:

docker exec linkace-app-1 php artisan backup:run

Non-Docker:

cd /path/to/linkace
php artisan backup:run

Output example:

Starting backup...
Dumping database...
Adding files to backup...
Zipping backup...
Backup completed successfully!
Backup size: 45.2 MB
Backup location: /app/storage/app/backups/2024-01-15-14-30-45.zip

List Backups

Docker:

docker exec linkace-app-1 php artisan backup:list

Non-Docker:

php artisan backup:list

Output example:

+----------------------------+----------+--------+
| Name                       | Disk     | Size   |
+----------------------------+----------+--------+
| 2024-01-15-14-30-45.zip   | local    | 45 MB  |
| 2024-01-14-02-00-12.zip   | local    | 44 MB  |
| 2024-01-13-02-00-08.zip   | local    | 43 MB  |
+----------------------------+----------+--------+

Clean Old Backups

Docker:

docker exec linkace-app-1 php artisan backup:clean

Non-Docker:

php artisan backup:clean

Restoring Backups

What’s Included in a Backup

Each backup contains:

• Complete database dump - All links, lists, tags, users, settings
• Uploaded files - User avatars, custom assets
• Application files - (Optional, depending on configuration)

Not included:

• .env file (contains secrets)
• Docker volumes (database, Redis)
• Application code (re-download from releases)

Restoration Process

Step 1: Prepare Clean Installation

Option A: Fresh installation

1. Follow Installation Guide
2. Complete initial setup
3. Stop the application

Option B: Existing installation

1. Stop LinkAce
2. Backup current .env file
3. Clear current database (optional, for clean restore)

Step 2: Extract Backup

1. Download backup file:

Local backups:

# Docker
cp ./backups/2024-01-15-14-30-45.zip /tmp/
 
# Non-Docker
cp storage/app/backups/2024-01-15-14-30-45.zip /tmp/

S3 backups:

• Download from AWS Console, or
• Use AWS CLI:

aws s3 cp s3://your-bucket/backups/2024-01-15-14-30-45.zip /tmp/

2. Extract backup:

cd /tmp
unzip 2024-01-15-14-30-45.zip

If password-protected:

unzip -P YourPassword 2024-01-15-14-30-45.zip

Step 3: Restore Database

Docker with MySQL:

# Find database dump file
ls -la /tmp/db-dumps/
 
# Restore to database
docker exec -i linkace-db-1 mysql -u linkace -p linkace < /tmp/db-dumps/mysql-linkace.sql

Enter database password when prompted (from .env).

Docker with PostgreSQL:

docker exec -i linkace-db-1 psql -U linkace linkace < /tmp/db-dumps/pgsql-linkace.sql

Non-Docker with MySQL:

mysql -u linkace -p linkace < /tmp/db-dumps/mysql-linkace.sql

Non-Docker with PostgreSQL:

psql -U linkace linkace < /tmp/db-dumps/pgsql-linkace.sql

Step 4: Restore Files

Docker:

# Copy uploaded files
docker cp /tmp/storage/app/public/. linkace-app-1:/app/storage/app/public/
 
# Fix permissions
docker exec linkace-app-1 chown -R www-data:www-data /app/storage

Non-Docker:

# Copy uploaded files
cp -r /tmp/storage/app/public/* /path/to/linkace/storage/app/public/
 
# Fix permissions
chmod -R 0766 /path/to/linkace/storage

Step 5: Clear Caches

Docker:

docker exec linkace-app-1 php artisan cache:clear
docker exec linkace-app-1 php artisan config:clear
docker exec linkace-app-1 php artisan view:clear

Non-Docker:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

Step 6: Start and Verify

Docker:

docker compose up -d

Non-Docker:

# Restart web server (nginx/apache)
sudo systemctl restart nginx

Verify restoration:

1. Open LinkAce in browser
2. Log in with your credentials
3. Check that links, lists, and tags are present
4. Verify user accounts exist
5. Test creating a new link

Email Notifications

Get notified about backup success and failures.

Configure Email

1. Set up email in .env:

# Backup notifications
BACKUP_NOTIFICATIONS_ENABLED=true
BACKUP_NOTIFICATION_EMAIL=admin@example.com

# SMTP configuration
MAIL_FROM_ADDRESS=linkace@example.com
MAIL_FROM_NAME=LinkAce
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls

2. Restart:

# Docker
docker compose restart
 
# Non-Docker
php artisan config:clear

For complete email setup, see Email Configuration.

Notification Types

You’ll receive emails for:

✅ Backup succeeded - Confirmation with size and location
❌ Backup failed - Error details and troubleshooting
🗑️ Cleanup completed - Old backups removed
⚠️ Backup unhealthy - Backup is too old or corrupted

Disable Notifications

To disable email alerts:

BACKUP_NOTIFICATIONS_ENABLED=false

⚠️ Not recommended - You won’t know if backups fail!

Backup Best Practices

Storage Strategy

✅ Use cloud storage - Local backups can be lost with server failure
✅ 3-2-1 rule - 3 copies, 2 different media, 1 offsite
✅ Encrypt backups - Use BACKUP_ARCHIVE_PASSWORD
✅ Test restores - Verify backups work before you need them

Scheduling

✅ Daily backups - Default schedule is good for most users
✅ Off-peak hours - Run at 2-3 AM when traffic is low
✅ Stagger tasks - Clean at 1 AM, backup at 2 AM

Retention

✅ Keep multiple versions - Don’t rely on single backup
✅ Monitor size - Adjust BACKUP_MAX_SIZE as collection grows
✅ Archive important backups - Download and store separately

Monitoring

✅ Enable email notifications - Know when backups fail
✅ Check backup size - Sudden changes indicate problems
✅ Verify backup location - Ensure backups are being created
✅ Test restoration - Do a test restore every few months

Troubleshooting

Backups Not Running

Problem: No backups are being created.

Solutions:

1. Check cron is configured:

   • Go to System Settings
   • Verify “System Cron” shows recent run
   • See Post-Installation Setup

2. Verify backup is enabled:

   grep BACKUP_ENABLED .env
   # Should show: BACKUP_ENABLED=true

3. Check permissions:

   # Docker
   docker exec linkace-app-1 ls -la /app/storage/app/backups
    
   # Non-Docker
   ls -la storage/app/backups

   Directory should be writable.

4. Run manual backup to see errors:

   docker exec linkace-app-1 php artisan backup:run

Backup Fails with “Disk Full”

Problem: Backup fails due to insufficient space.

Solutions:

1. Increase disk space on server
2. Reduce backup size:

   BACKUP_MAX_SIZE=256  # Reduce from 512

3. Clean old backups:

   docker exec linkace-app-1 php artisan backup:clean

4. Use cloud storage instead of local

S3 Upload Fails

Problem: Backups fail when uploading to S3.

Solutions:

1. Verify credentials:

   # Test AWS CLI
   aws s3 ls s3://your-bucket --profile linkace

2. Check endpoint:

   # For non-AWS services, ensure endpoint is set
   AWS_ENDPOINT=https://your-service-endpoint.com

3. Verify IAM permissions:

   • User needs s3:PutObject, s3:GetObject, s3:DeleteObject
   • Bucket policy allows access

4. Check region:

   AWS_DEFAULT_REGION=us-east-1  # Must match bucket region

Restore Fails

Problem: Database restore produces errors.

Solutions:

1. Check database version compatibility

   • MySQL dump from 8.0 may not work on 5.7
   • Use same database version as backup source

2. Verify database is empty:

   # Drop and recreate database
   docker exec linkace-db-1 mysql -u root -p -e "DROP DATABASE linkace; CREATE DATABASE linkace;"

3. Check for corruption:

   # Verify backup file is valid
   unzip -t backup-file.zip

4. Review error messages:

   • SQL syntax errors indicate version mismatch
   • Permission errors indicate user access issues

Email Notifications Not Received

Problem: No backup notification emails.

Solutions:

1. Verify email is configured:

   grep MAIL_ .env

2. Test email:

   docker exec linkace-app-1 php artisan linkace:test-email your@email.com

3. Check spam folder

4. Verify notification email is set:

   BACKUP_NOTIFICATION_EMAIL=your@email.com
   BACKUP_NOTIFICATIONS_ENABLED=true

Advanced Configuration

Custom Backup Schedule

For more control, edit the backup schedule directly.

Not recommended for most users - use BACKUP_RUN_HOUR instead.

See Spatie documentation  for advanced scheduling.

Exclude Files from Backup

Reduce backup size by excluding certain files.

Edit config/backup.php (advanced users only):

'exclude' => [
    'storage/logs',
    'storage/framework/cache',
],

Multiple Backup Destinations

Back up to both local and S3 simultaneously.

Edit config/backup.php (advanced users only):

'destination' => [
    'disks' => [
        'local_backups',
        's3',
    ],
],

Next Steps

Essential Reading

• Post-Installation Setup - Configure cron for automated backups
• Email Configuration - Set up notifications
• Environment Variables - Advanced configuration

Related Topics

• Troubleshooting - Common issues
• Upgrading LinkAce - Update procedures
• CLI Commands - Command-line tools

Protect your bookmarks - set up backups today! 📦