Skip to Content
MaintenanceUpgrading

Last Updated: 3/10/2026

Upgrading LinkAce

Keep your LinkAce installation up-to-date with the latest features, security patches, and bug fixes. This guide covers upgrade procedures for both Docker and non-Docker installations.

Before You Upgrade

Backup First!

⚠️ Always backup before upgrading. Even though upgrades are usually smooth, backups protect you from unexpected issues.

Quick backup:

# Docker
docker exec linkace-app-1 php artisan backup:run
 
# Non-Docker
php artisan backup:run

For complete backup setup, see Backup & Restore.

Check Requirements

Verify your system meets the requirements for the new version:

  • PHP version - Check release notes for minimum version
  • Database version - Ensure compatibility
  • Docker version - For Docker installations
  • Disk space - Ensure sufficient space for upgrade

Read Release Notes

Always review the release notes  before upgrading:

  • Breaking changes - Changes that require action
  • New features - What’s new in this version
  • Bug fixes - Issues resolved
  • Upgrade notes - Version-specific instructions

Docker Upgrade

Recommended method for Docker installations.

Automated Upgrade Script

LinkAce provides an automated upgrade script that handles the entire process.

1. Download the script:

wget https://github.com/Kovah/LinkAce/raw/2.x/update-docker.sh
chmod +x update-docker.sh

2. Run the script:

./update-docker.sh

The script will:

  1. Stop containers
  2. Backup the database
  3. Pull the latest image
  4. Remove old app volume
  5. Start containers
  6. Run database migrations
  7. Clear caches

3. Verify the upgrade:

# Check container status
docker compose ps
 
# Check application logs
docker compose logs -f app

Manual Docker Upgrade

If you prefer manual control or have a custom setup:

1. Stop containers:

docker compose down

2. Backup database (optional but recommended):

# Create backup directory
mkdir -p ./backups/pre-upgrade
 
# Backup database
docker compose up -d db
docker exec linkace-db-1 mysqldump -u linkace -p linkace > ./backups/pre-upgrade/database-$(date +%Y%m%d).sql
docker compose down

3. Remove old app volume:

⚠️ Important: This step is required for the advanced setup method.

# Find your volume name
docker volume ls | grep linkace
 
# Remove app volume (e.g., linkace_linkace_app)
docker volume rm linkace_linkace_app

Note: This doesn’t delete your data - database and backups are in separate volumes.

4. Pull latest image:

docker compose pull

5. Start containers:

docker compose up -d

6. Run migrations:

docker exec linkace-app-1 php artisan migrate --force

You may see a warning about running migrations in production. Type yes to confirm.

7. Clear caches:

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 settings:clear-cache

8. Verify upgrade:

# Check version
docker exec linkace-app-1 php artisan --version
 
# Check application health
docker compose logs -f app

Open LinkAce in your browser and verify everything works.

Non-Docker Upgrade

For traditional PHP installations.

Upgrade Process

1. Backup everything:

cd /path/to/linkace
 
# Backup database
php artisan backup:run
 
# Backup .env file
cp .env .env.backup
 
# Backup files (optional)
tar -czf linkace-backup-$(date +%Y%m%d).tar.gz .

2. Download latest release:

Visit the releases page  and download the .zip package.

wget https://github.com/Kovah/LinkAce/releases/download/vX.X.X/linkace-vX.X.X.zip
unzip linkace-vX.X.X.zip -d linkace-new

3. Replace files:

⚠️ Important: Keep your .env file and storage/ directory.

# Copy new files (excluding storage and .env)
rsync -av --exclude='.env' --exclude='storage/logs' linkace-new/ /path/to/linkace/
 
# Or manually:
# - Copy all files from linkace-new/ to your LinkAce directory
# - DO NOT overwrite .env
# - DO NOT overwrite storage/logs (optional: keep your logs)

4. Run migrations:

cd /path/to/linkace
php artisan migrate --force

5. Clear caches:

php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan settings:clear-cache

6. Update dependencies (if needed):

Some updates may require dependency updates:

composer install --no-dev --optimize-autoloader
npm install
npm run production

7. Fix permissions:

# For nginx
sudo chown -R www-data:www-data storage/
sudo chown -R www-data:www-data bootstrap/cache/
 
# For Apache
sudo chown -R apache:apache storage/
sudo chown -R apache:apache bootstrap/cache/
 
chmod -R 0766 storage/
chmod -R 0766 bootstrap/cache/

8. Restart web server:

# Nginx
sudo systemctl restart nginx
 
# Apache
sudo systemctl restart apache2
 
# PHP-FPM (if used)
sudo systemctl restart php8.2-fpm

9. Verify upgrade:

php artisan --version

Open LinkAce in your browser and test functionality.

Version-Specific Upgrades

Upgrading to LinkAce 2.x

If you’re upgrading from LinkAce 1.x, see the dedicated guide:

👉 Upgrade from LinkAce v1

Key changes in v2:

  • Multi-user support
  • New user management system
  • Updated API (v2 endpoints)
  • Privacy controls (Public/Internal/Private)
  • Guest mode
  • Improved performance

Current Version-Specific Notes

At the moment, no specific steps are required to upgrade between LinkAce 2.x versions.

Always check the release notes  for version-specific instructions.

Troubleshooting Upgrades

White Screen After Upgrade

Problem: Blank page or 500 error.

Solutions:

  1. Clear all 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

  2. Check logs:

    # Docker
docker compose logs app
 
# Non-Docker
tail -f storage/logs/laravel.log

  3. Run migrations:

    php artisan migrate --force

  4. Check permissions:

    # Non-Docker
chmod -R 0766 storage/
chmod -R 0766 bootstrap/cache/

Database Migration Errors

Problem: Migration fails with SQL errors.

Solutions:

  1. Check database version:

    # Docker MySQL
docker exec linkace-db-1 mysql --version
 
# Non-Docker
mysql --version

    Ensure compatibility with LinkAce requirements.

  2. Review migration error:

    • Read the error message carefully
    • Check if table already exists
    • Check for column conflicts

  3. Rollback and retry:

    php artisan migrate:rollback
php artisan migrate --force

  4. Force migration (last resort):

    php artisan migrate:fresh --force

    ⚠️ Warning: This drops all tables and recreates them. Only use with a backup!

Container Won’t Start

Problem: Docker container exits immediately.

Solutions:

  1. Check logs:

    docker compose logs app

  2. Verify image:

    docker images | grep linkace

    Ensure latest image is pulled.

  3. Remove and recreate:

    docker compose down
docker compose up -d

  4. Check .env file:

    docker exec linkace-app-1 cat .env

    Verify APP_KEY is set.

Missing Features After Upgrade

Problem: New features don’t appear.

Solutions:

  1. Clear browser cache:

    • Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
    • Clear cookies and cache

  2. Clear application cache:

    php artisan cache:clear
php artisan view:clear

  3. Check version:

    php artisan --version

    Verify you’re running the expected version.

  4. Check release notes:

    • Feature may require configuration
    • Feature may be admin-only

Downgrading

⚠️ Downgrading is not officially supported and may cause data loss.

If you must downgrade:

Docker Downgrade

1. Stop containers:

docker compose down

2. Edit docker-compose.yml:

services:
  app:
    image: linkace/linkace:vX.X.X  # Specify older version

3. Restore database backup:

docker compose up -d db
docker exec -i linkace-db-1 mysql -u linkace -p linkace < backup.sql

4. Start containers:

docker compose up -d

5. Run migrations (may fail):

docker exec linkace-app-1 php artisan migrate --force

Non-Docker Downgrade

1. Restore files:

tar -xzf linkace-backup-YYYYMMDD.tar.gz -C /path/to/linkace/

2. Restore database:

mysql -u linkace -p linkace < backup.sql

3. Clear caches:

php artisan cache:clear
php artisan config:clear

Best Practices

Before Every Upgrade

✅ Read release notes - Check for breaking changes
✅ Backup everything - Database, files, .env
✅ Test in staging - If possible, test upgrade on copy first
✅ Schedule downtime - For production systems
✅ Verify requirements - PHP, database versions

During Upgrade

✅ Follow instructions - Don’t skip steps
✅ Read error messages - They contain important info
✅ Check logs - Review application and container logs
✅ Be patient - Migrations can take time on large databases

After Upgrade

✅ Test functionality - Add a link, search, check settings
✅ Verify cron - Check System Settings → System Cron
✅ Check backups - Ensure automated backups still work
✅ Monitor logs - Watch for errors in first few days
✅ Update documentation - Note your version and upgrade date

Staying Up-to-Date

Release Notifications

Get notified about new releases:

  1. Watch on GitHub:

  2. Follow on social media:

  3. RSS feed:

Update Frequency

Security updates: Apply immediately
Feature updates: Apply within 1-2 weeks
Minor updates: Apply within a month

Recommendation: Check for updates monthly.

Watchtower Warning

⚠️ Do NOT use Watchtower with LinkAce!

Several users reported broken installations after Watchtower ran automatic updates.

Why? Watchtower doesn’t:

  • Run database migrations
  • Clear caches
  • Handle version-specific upgrade steps

Exclude LinkAce from Watchtower:

services:
  app:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Always upgrade manually following this guide.

Version History

LinkAce follows Semantic Versioning :

  • Major version (2.0.0) - Breaking changes, major features
  • Minor version (2.1.0) - New features, backward compatible
  • Patch version (2.0.1) - Bug fixes, backward compatible

Current Versions

  • LinkAce 2.x - Current stable version (multi-user, modern features)
  • LinkAce 1.x - Legacy version (deprecated, no longer maintained)

Support Policy

  • Current major version - Full support
  • Previous major version - Security updates for 6 months after new major release
  • Older versions - No support

Recommendation: Always run the latest stable version.

Next Steps

After Upgrading

Maintenance

Getting Help

Keep LinkAce updated for the best experience! 🚀

Backup RestoreTroubleshooting