Skip to Content
MaintenanceUpgrading LinkAce

Last Updated: 3/9/2026

Upgrading LinkAce

This guide covers upgrading LinkAce to newer versions. Always back up your data before upgrading.

Before You Upgrade

1. Create a Backup

⚠️ CRITICAL: Always back up your LinkAce installation and database before upgrading.

What to back up:

  • Database: Full database dump (MySQL, PostgreSQL, or SQLite file)
  • .env file: Your configuration
  • Uploaded files: Any custom uploads or backups in storage/app

Docker backup:

# Stop containers
docker compose down
 
# Backup database (MySQL example)
docker compose exec db mysqldump -u linkace -p linkace > linkace-backup-$(date +%Y%m%d).sql
 
# Backup .env file
cp .env .env.backup
 
# Backup volumes (optional)
docker run --rm -v linkace_linkace-db:/data -v $(pwd):/backup ubuntu tar czf /backup/linkace-db-backup.tar.gz /data

Non-Docker backup:

# Backup database
mysqldump -u linkace -p linkace > linkace-backup-$(date +%Y%m%d).sql
 
# Backup files
cp -r /path/to/linkace /path/to/linkace-backup

2. Check the Release Notes

Always read the release notes before upgrading:

👉 LinkAce Releases

Look for:

  • Breaking changes: Configuration changes, removed features
  • Migration notes: Special upgrade steps
  • New requirements: PHP version, database version, etc.

3. Check Your Current Version

Find your current version:

  • In LinkAce: System Settings → Update Checks
  • Docker: Check your docker-compose.yml image tag
  • Non-Docker: Check composer.json or run php artisan --version

Upgrading Docker Installations

Standard Upgrade Process

  1. Stop the containers:

    docker compose down

  2. Pull the latest image:

    docker pull linkace/linkace:latest

    Or, for a specific version:

    docker pull linkace/linkace:2.5.0

  3. Start the containers:

    docker compose up -d

  4. Run database migrations:

    docker compose exec app php artisan migrate

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

  5. Clear caches:

    docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear

  6. Verify the upgrade:

    • Open LinkAce in your browser
    • Check System Settings → Update Checks for the new version
    • Test core functionality (add a link, search, etc.)

Using the Update Script (Optional)

LinkAce provides an automated update script:

  1. Download the script:

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

  2. Run the script:

    ./update-docker.sh

The script will:

  • Stop containers
  • Pull the latest image
  • Restart containers
  • Run migrations
  • Clear caches

Pinning to a Specific Version

To avoid automatic upgrades, pin your Docker image to a specific version in docker-compose.yml:

services:
  app:
    image: docker.io/linkace/linkace:2.5.0  # Pin to specific version

Recommendation: Use specific versions for production deployments.

Upgrading Non-Docker Installations

Standard Upgrade Process

  1. Download the latest release: 👉 LinkAce Releases

  2. Extract to a NEW directory (do not overwrite):

    unzip linkace-v2.5.0.zip -d /path/to/linkace-new

  3. Copy your .env file:

    cp /path/to/linkace-old/.env /path/to/linkace-new/.env

  4. Copy uploaded files (if any):

    cp -r /path/to/linkace-old/storage/app/* /path/to/linkace-new/storage/app/

  5. Run database migrations:

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

    Type yes to confirm.

  6. Clear caches:

    php artisan cache:clear
php artisan config:clear

  7. Update your web server to point to the new directory:

    • Nginx: Update root directive to /path/to/linkace-new/public
    • Apache: Update DocumentRoot to /path/to/linkace-new/public

  8. Reload your web server:

    # Nginx
sudo systemctl reload nginx
 
# Apache
sudo systemctl reload apache2

  9. Verify the upgrade:

    • Open LinkAce in your browser
    • Check System Settings → Update Checks
    • Test core functionality

  10. Remove the old directory (after confirming everything works):

    rm -rf /path/to/linkace-old

Upgrading from LinkAce v1 to v2

LinkAce v2 is a major release with breaking changes. See the dedicated v1 to v2 upgrade guide below.

Version-Specific Upgrade Notes

Upgrading to v2.5.0+

  • PHP 8.1 support dropped: Requires PHP 8.2 to 8.5
  • Action: Update your PHP version before upgrading

Upgrading to v2.4.0+

  • Security patches: Update as soon as possible
  • No breaking changes

Upgrading to v2.0.0+

  • Major release: See v1 to v2 upgrade guide
  • Breaking changes: Docker image renamed, multi-user support, API v2

Upgrading from v1 to v2 (Detailed)

Breaking Changes

  1. Docker image renamed: linkace/linkace:simple or linkace/linkace:php-nginx → linkace/linkace
  2. Multi-user support: New visibility system (Public, Internal, Private)
  3. API v2: Existing integrations must be updated
  4. Mail configuration: MAIL_DRIVER → MAIL_MAILER

Preparation

  1. Back up everything (database, .env, files)
  2. Enable Guest Mode (optional):
    • If enabled before upgrade: Public links stay public
    • If disabled: Public links become Internal
  3. Note your current setup:
    • Docker Compose or manual Docker?
    • Which image are you using?

Docker Compose Upgrade

1. Stop containers

docker compose down

2. Update docker-compose.yml

Change the image name:

Old:

image: linkace/linkace:simple

New:

image: linkace/linkace:latest

The internal port stays at 80 (do not change).

Optional: Download the latest docker-compose.yml and .env templates:

Do NOT overwrite your existing .env file — merge changes manually.

3. Update .env file

Change MAIL_DRIVER to MAIL_MAILER:

Old:

MAIL_DRIVER=smtp

New:

MAIL_MAILER=smtp

4. Start containers

docker compose up -d

5. Run migrations

docker compose exec app php artisan migrate
docker compose exec app php artisan cache:clear

Type yes to confirm. This may take several minutes depending on your link count.

6. Verify

  • Log in and check your links
  • Verify visibility settings (Public/Internal/Private)
  • Test core functionality

Manual Docker Upgrade

If you used docker run or a custom setup:

  1. Change the image name from linkace/linkace:simple or linkace/linkace:php-nginx to linkace/linkace
  2. Update your Docker command or configuration
  3. Run migrations inside the container: 
    docker exec -it linkace-container php artisan migrate
docker exec -it linkace-container php artisan cache:clear

Non-Docker Upgrade

  1. Download LinkAce v2: Releases 
  2. Extract to a NEW directory
  3. Copy .env file and update MAIL_DRIVER → MAIL_MAILER
  4. Run migrations: 
    php artisan migrate
php artisan cache:clear
  5. Update web server to point to the new directory

HTTPS Configuration Changes

If you used LinkAce directly with SSL certificates:

Post-Upgrade

  1. Review visibility settings:
    • Private links remain private
    • Public links: Stay public if Guest Mode was enabled, become Internal if disabled
  2. Update API integrations to use API v2: API Documentation 
  3. Invite users (optional): System Settings → User Management
  4. Configure SSO (optional): Single Sign-On

Troubleshooting Upgrades

Migration Errors

Error: SQLSTATE[42S01]: Base table or view already exists

Solution:

  • Your database is already up to date
  • Run php artisan cache:clear and try again

Error: SQLSTATE[HY000]: General error: 1364 Field 'xxx' doesn't have a default value

Solution:

Docker Image Not Pulling

Error: Error response from daemon: manifest for linkace/linkace:latest not found

Solution:

  • Check your internet connection
  • Try pulling from GitHub Container Registry: 
    image: ghcr.io/kovah/linkace:latest

Containers Not Starting

  1. Check logs:

    docker compose logs -f app

  2. Verify .env permissions:

    chmod 666 .env

  3. Check database connection:

    • Verify DB_PASSWORD matches in .env and docker-compose.yml

  1. Clear all caches:

    docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
docker compose exec app php artisan view:clear

  2. Restart containers:

    docker compose restart

  3. Check logs: System Logs → look for errors

Visibility Issues After v1 → v2 Upgrade

Problem: Links that were public are now internal

Cause: Guest Mode was disabled before the upgrade

Solution:

  • Enable Guest Mode in System Settings
  • Or, manually change link visibility to Public

Watchtower Broke My Installation

Problem: Watchtower auto-upgraded LinkAce and it’s not working

Solution:

  1. Restore from backup
  2. Exclude LinkAce from Watchtower: 
    services:
  app:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
  3. Upgrade manually following this guide

For more help, see the Troubleshooting guide or GitHub Discussions .

Best Practices

1. Test Upgrades First

  • Use a staging environment if possible
  • Test with a copy of your production database
  • Verify all features work before upgrading production

2. Schedule Downtime

  • Announce upgrades to your users (if multi-user)
  • Upgrade during low-traffic periods
  • Plan for rollback if something goes wrong

3. Keep Backups

  • Automated backups: Configure Application Backups
  • Pre-upgrade backups: Always back up before upgrading
  • Test restores: Verify your backups work

4. Pin Versions in Production

  • Use specific image tags: linkace/linkace:2.5.0 instead of :latest
  • Control upgrades: Upgrade intentionally, not automatically
  • Review release notes: Understand what’s changing

5. Monitor After Upgrade

  • Check System Logs: Look for errors
  • Test core features: Add links, search, edit
  • Monitor performance: Watch for slowdowns or errors
  • Check cron: Verify automation is still working

Rollback Procedure

If an upgrade fails, you can roll back:

Docker Rollback

  1. Stop containers:

    docker compose down

  2. Restore database:

    docker compose exec db mysql -u linkace -p linkace < linkace-backup.sql

  3. Change image tag in docker-compose.yml to previous version:

    image: linkace/linkace:2.4.0  # Previous working version

  4. Restore .env file:

    cp .env.backup .env

  5. Start containers:

    docker compose up -d

Non-Docker Rollback

  1. Restore database:

    mysql -u linkace -p linkace < linkace-backup.sql

  2. Restore files:

    rm -rf /path/to/linkace-new
mv /path/to/linkace-backup /path/to/linkace

  3. Update web server to point to the old directory

  4. Reload web server:

    sudo systemctl reload nginx

Next Steps

  • Review release notes: LinkAce Changelog
  • Check for configuration changes: Environment Variables
  • Test new features: Explore what’s new in the latest version
  • Update documentation: Inform your team about changes

For ongoing maintenance, see:

Troubleshooting