Last Updated: 3/9/2026

Installation with Docker

Docker is the recommended installation method for LinkAce. This guide covers a stable, production-ready setup using Docker Compose with MySQL and Redis.

Prerequisites

Docker 19+ installed on your server
Docker Compose with support for compose version 3
Command-line access to your server
Domain name (optional, but recommended for HTTPS)

Supported Architectures

LinkAce Docker images are available on Docker Hub and GitHub Container Registry , supporting:

amd64 (x86_64)
arm64 (ARM 64-bit)
arm/v7 (ARM 32-bit)

Installation Steps

1. Download the Setup Package

Get the latest Docker setup package from the LinkAce releases page:

👉 linkace-docker.zip

Alternatively, you can view the files directly and adapt them to your setup:

2. Extract the Files

Extract the ZIP file to your desired location. Your directory should look like this:


linkace/
├╴ .env
├╴ docker-compose.yml
├╴ LICENSE.md
└╴ README.md

3. Configure Environment Variables

Open the .env file and change the following required settings:


# Database password (REQUIRED: change this!)
DB_PASSWORD=YourSecurePasswordHere

# Redis password (REQUIRED: change this!)
REDIS_PASSWORD=AnotherSecurePasswordHere

Important: If the .env file is not writable inside Docker during setup, make it writable:


chmod 666 .env

You can revert to read-only after the setup completes:


chmod 644 .env

4. Start the Containers

Run Docker Compose to start all services:


docker compose up -d

This will start:

app: LinkAce application (Caddy web server + PHP)
db: MySQL database
redis: Redis cache

5. Complete the Web Setup

Open your browser and navigate to:

http://localhost (if running locally)
http://your-server-ip (if running on a remote server)
http://your-domain.com (if you’ve configured a domain)

The built-in setup wizard will guide you through:

Database configuration (pre-filled from .env)
Admin account creation (username, email, password)
Initial preferences (timezone, language)

After setup, you’ll be redirected to the LinkAce dashboard.

6. Enable Automation (Critical)

To enable link health checks, Wayback Machine archiving, and automated backups, you must configure the cron job. See the Post-Installation guide for detailed instructions.

Alternative: Command-Line Setup

If the web setup doesn’t work, you can complete the installation via the command line.

Steps

Follow steps 1-4 above to start the containers.

Run database migrations:


docker compose exec app php artisan migrate

Mark setup as complete:


docker compose exec app php artisan setup:complete

Create an admin user:
```
docker compose exec app php artisan registeruser --admin
```
Follow the prompts to enter username, email, and password.
Log in: Navigate to http://localhost and log in with your credentials.

Advanced Configuration

Using Environment Variables Instead of .env

You can move configuration from the .env file into your docker-compose.yml file. If you do this, you must generate your own application key.

Generate an app key:


docker run --rm -it linkace/linkace php artisan key:generate --show

Output example:


base64:Il/5KRDENz2TiCYjKweDAkI93Q4D5ZWmP3AORXgReNo=

Add to docker-compose.yml:


services:
  app:
    image: docker.io/linkace/linkace:latest
    environment:
      APP_KEY: base64:Il/5KRDENz2TiCYjKweDAkI93Q4D5ZWmP3AORXgReNo=
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_DATABASE: linkace
      DB_USERNAME: linkace
      DB_PASSWORD: YourSecurePasswordHere
      REDIS_HOST: redis
      REDIS_PASSWORD: AnotherSecurePasswordHere
      # ... other environment variables

Running Behind a Proxy or Load Balancer

If you use a reverse proxy (Nginx, Apache, Traefik) or load balancer with HTTPS, ensure it forwards these headers:

Nginx example:


proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;

Apache example:


ProxyPreserveHost on
RequestHeader set X-Forwarded-Port "443"
RequestHeader set X-Forwarded-Proto "https"

Without these headers, LinkAce cannot generate correct URLs.

Running LinkAce Directly with SSL

If you want to run LinkAce with HTTPS without a reverse proxy, you can configure the built-in Caddy web server.

Prerequisites

A publicly accessible domain pointing to your server
Ports 80 and 443 open and accessible from the internet

Steps

Stop your containers:
```
docker compose down
```
Download the SSL Caddyfile:
👉 ssl.Caddyfile

Place it next to your docker-compose.yml file.

Edit docker-compose.yml:

Add these environment variables under app:


services:
  app:
    image: docker.io/linkace/linkace:latest
    environment:
      LINKACE_DOMAIN: "your-domain.com"  # Replace with your domain
      PORT: 443

Uncomment these lines:


ports:
  - "0.0.0.0:80:80"
  - "0.0.0.0:443:443"  # Uncomment this line
volumes:
  - ./.env:/app/.env
  - ./backups:/app/storage/app/backups
  - ./caddy-data:/home/www-data/.local/share/caddy  # Uncomment this line
  - ./ssl.Caddyfile:/etc/caddy/Caddyfile  # Uncomment this line

Start the containers:
```
docker compose up -d
```
Wait for SSL certificate:
Caddy will automatically request a Let’s Encrypt certificate. Check the logs:
```
docker compose logs -f app
```
After a minute or two, you should be able to access LinkAce at https://your-domain.com.

Changing the Internal Port

LinkAce v2 accepts a PORT environment variable to listen on a specific port. This is useful for restricted Docker hosting environments like Heroku.


environment:
  PORT: 8080

Compatibility Notes

Watchtower

Several users have reported broken LinkAce installations after Watchtower ran automatic updates.

Recommendation: Exclude LinkAce from Watchtower and only update manually to ensure all update steps (migrations, cache clearing) run correctly.

Troubleshooting

Container Won’t Start

Check logs:
```
docker compose logs -f app
```
Verify .env permissions:
```
chmod 666 .env
```
Check Docker version:
```
docker --version
docker compose version
```

Database Connection Errors

Verify passwords match in .env and docker-compose.yml
Check database is running:
```
docker compose ps
```
View database logs:
```
docker compose logs -f db
```

Permission Errors

The storage directory must be writable:


docker compose exec app chmod -R 0766 ./storage

For more troubleshooting, see the Troubleshooting guide.

Next Steps

Enable automation: Follow the Post-Installation guide to set up the cron job.
Configure system settings: Visit System Settings to enable guest access, configure notifications, and set automation preferences.
Import bookmarks: Import existing bookmarks from HTML files.
Set up SSO (optional): Configure Single Sign-On for multi-user deployments.
Enable backups: Set up automated backups to S3-compatible storage.

Updating LinkAce

To update LinkAce to a newer version, see the Upgrading LinkAce guide.