Last Updated: 3/10/2026

Installation with Docker

Docker is the recommended way to install and run LinkAce. This guide covers everything from a quick test setup to a production-ready installation with SSL support.

Before You Begin

Requirements

Docker version 19 or greater
Docker Compose supporting compose version 3 or later
Command-line access to your server
Basic familiarity with Docker and the command line

Docker Images

LinkAce images are available on:

All images support amd64, arm64, and armv7 architectures.

Quick Test Setup (2 Minutes)

Try LinkAce with SQLite in under 2 minutes. Perfect for testing, but not recommended for production.


touch database.sqlite
chmod 0766 database.sqlite
docker run -p "8080:80" -v "./database.sqlite:/app/database/database.sqlite" linkace/linkace

Open http://localhost:8080 and follow the setup wizard.

Port conflict? If port 8080 is in use:


docker run -p "8080:8080" -e "PORT=8080" -v "./database.sqlite:/app/database/database.sqlite" linkace/linkace

Note: This test setup uses SQLite and doesn’t include Redis caching. Migrating to a production database later is not supported.

Production Setup

This is the recommended, fully-supported installation method for Docker.

Step 1: Download the Setup Files

Download the Docker setup package:

👉 Download linkace-docker.zip

Extract to your desired directory:


unzip linkace-docker.zip
cd linkace

Your directory structure:


linkace/
├── .env                  # Environment configuration
├── docker-compose.yml    # Docker services definition
├── LICENSE.md
└── README.md

Alternative: View the files directly on GitHub:

Step 2: Configure Security Settings

Open the .env file and set secure passwords:


nano .env

Required changes:


# Database password (use a strong, unique password)
DB_PASSWORD=ChangeThisToASecurePassword!

# Redis password (use a different strong password)
REDIS_PASSWORD=ChangeThisToAnotherSecurePassword!

Permissions: If you’re unsure whether Docker can write to .env, make it writable:


chmod 666 .env

You can revert to read-only after setup:


chmod 644 .env

Step 3: Start the Application

Start all containers:


docker compose up -d

Docker will:

Pull the LinkAce image (if not already downloaded)
Start the database (MariaDB)
Start Redis cache
Start the LinkAce application

This takes 1-2 minutes on the first run.

Check status:


docker compose ps

All containers should show “Up” status.

Step 4: Complete the Setup Wizard

Open LinkAce in your browser:

Local: http://localhost
Server: http://your-server-ip or http://your-domain.com

The setup wizard will guide you through:

Database Configuration
- Pre-filled from your .env file
- Click “Test Connection” to verify
- Click “Next”
Admin Account Creation
- Enter your name
- Enter your email
- Set a strong password
- Click “Create Account”
Setup Complete
- Click “Go to LinkAce”

🎉 Installation complete! Now follow the Post-Installation Setup to enable all features.

Advanced Configuration

Using Environment Variables Instead of .env

You can move configuration from .env to docker-compose.yml or your Docker setup.

Important: You must generate your own application key:


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

Output example:


base64:Il/5KRDENz2TiCYjKweDAkI93Q4D5ZWmP3AORXgReNo=

Add to your docker-compose.yml:


services:
  app:
    image: docker.io/linkace/linkace:latest
    environment:
      APP_KEY: "base64:Il/5KRDENz2TiCYjKweDAkI93Q4D5ZWmP3AORXgReNo="
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: 3306
      DB_DATABASE: linkace
      DB_USERNAME: linkace
      DB_PASSWORD: "YourSecurePassword"
      REDIS_HOST: redis
      REDIS_PASSWORD: "YourRedisPassword"
      REDIS_PORT: 6379
      # ... other environment variables

Running Behind a Proxy or Load Balancer

If using a reverse proxy with HTTPS, ensure it sends these headers:

Nginx configuration:


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

Apache configuration:


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

Custom Port: LinkAce 2 accepts a PORT environment variable:


environment:
  PORT: 8080

Running with SSL (Direct HTTPS)

Configure LinkAce to handle SSL directly without a reverse proxy.

Prerequisites:

Domain name pointing to your server
Ports 80 and 443 accessible from the internet

Steps:

Stop LinkAce:
```
docker compose down
```

Download SSL configuration:


wget https://github.com/Kovah/LinkAce/raw/2.x/resources/docker/ssl.Caddyfile

Edit docker-compose.yml:

Add your domain:


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

Enable HTTPS port:


    ports:
      - "0.0.0.0:80:80"
      - "0.0.0.0:443:443"  # Remove the # at the start

Enable SSL volumes:


    volumes:
      - ./.env:/app/.env
      - ./backups:/app/storage/app/backups
      - ./caddy-data:/home/www-data/.local/share/caddy      # Remove the #
      - ./ssl.Caddyfile:/etc/caddy/Caddyfile                # Remove the #

Start LinkAce:
```
docker compose up -d
```
Check SSL certificate:
```
docker compose logs -f app
```
Look for messages about certificate acquisition. After 1-2 minutes, access your site at https://your-domain.com.

Troubleshooting: If SSL doesn’t work, check:

Domain DNS is correct and propagated
Ports 80 and 443 are open in your firewall
No other service is using ports 80 or 443

Command-Line Setup (Alternative)

If the web-based setup fails, complete installation via command line:

Configure database in .env first

Run migrations:


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

Complete setup:


docker exec -it linkace-app-1 php artisan setup:complete

Create admin user:
```
docker exec -it linkace-app-1 php artisan registeruser --admin
```
Follow the prompts to enter your name, email, and password.
Login: Open http://localhost or your domain and log in with your credentials.

Managing Your Installation

Starting and Stopping

Stop LinkAce:


docker compose down

Start LinkAce:


docker compose up -d

Restart LinkAce:


docker compose restart

Viewing Logs

All containers:


docker compose logs -f

LinkAce app only:


docker compose logs -f app

Last 100 lines:


docker compose logs --tail=100

Accessing the Container

Open a shell:


docker exec -it linkace-app-1 sh

Run artisan commands:


docker exec -it linkace-app-1 php artisan [command]

Compatibility Notes

Watchtower

⚠️ Warning: Several users reported broken installations after Watchtower ran automatic updates.

Recommendation: Exclude LinkAce from Watchtower and update manually following the Upgrade Guide.

Watchtower exclusion:


services:
  app:
    image: linkace/linkace:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Next Steps

Essential Configuration

Post-Installation Setup - Enable cron, backups, and monitoring
User Settings - Configure your preferences
System Settings - Configure system-wide options

Advanced Setup

Application Backups - Automated backup configuration
Email Configuration - Set up email notifications
Environment Variables - Complete configuration reference

Getting Started

Core Concepts - Understanding Links, Lists, and Tags
Managing Your Links - Complete workflow guide
Quick Start Guide - Fast overview for new users

Troubleshooting

If you encounter issues, see the Troubleshooting Guide or visit GitHub Discussions .