Quick Start

This guide walks you through getting a lnkify instance running on your own server using Docker Compose.

Prerequisites

• Docker and Docker Compose installed on your server (Docker 20.10+, Compose v2).
• A domain name with DNS pointing to your server's IP address.
• Ports 80 and 443 open on your server's firewall.

Step 1: Clone the Repository

git clone https://github.com/lnkify/lnkify-app.git
cd lnkify-app

Step 2: Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Open .env and set the required variables. At minimum, you need:

JWT_SECRET=<a long random string, at least 32 characters>
APIKEY_PEPPER=<another long random string, at least 32 characters>

Generate secure random values:

openssl rand -hex 32  # for JWT_SECRET
openssl rand -hex 32  # for APIKEY_PEPPER

Optional Variables

• IPREGISTRY_API_KEY — Set this to enable geolocation data in click analytics. Obtain a free key from ipregistry.co.
• PORT — Defaults to 4000. Change if there's a port conflict within Docker.
• MCP_ENABLED — Set to "false" to disable the MCP server.

See Configuration for the full list of environment variables.

Step 3: Start the Services

docker compose up --build -d

This builds the server, app, and docs images, then starts all six services. The first build may take a few minutes. Subsequent starts will be faster.

Step 4: Access the Application

• Main app: http://localhost (or https://<your-domain> once DNS and TLS are configured)
• Sign up: Navigate to /auth/signup to create your admin account.
• Docs: http://localhost on the docs port if configured, or https://docs.<your-domain>

What Happens on First Boot

1. db — PostgreSQL initializes, creates the database and user from .env credentials.
2. server — Waits for the database healthcheck to pass, then automatically applies any pending Prisma migrations (prisma migrate deploy) before starting Express. A fresh database is fully initialized with no manual step.
3. caddy — Starts serving. Attempts to obtain TLS certificates from Let's Encrypt. This requires your domain DNS to be resolvable. If DNS is not yet set up, Caddy will serve over HTTP on port 80.
4. app — nginx starts serving the React SPA dashboard immediately.
5. docs — nginx starts serving the documentation site immediately.
6. redis — Starts and passes its healthcheck (the server waits for both db and redis to be healthy).

Database Schema

The schema is applied automatically: the server container runs prisma migrate deploy on startup, creating the tables from the committed migrations. You do not need to run anything by hand on first boot.

If you ever need to apply migrations manually (for example against an external database before starting the app):

docker compose run --rm server pnpm run db-init

See Database for the full migration workflow.

Verify Everything is Running

docker compose ps

All six services should show Up status. Check logs if any service is restarting or unhealthy:

docker compose logs -f

DNS & TLS Setup

Once your domain DNS is pointed to the server, Caddy will automatically obtain TLS certificates. See DNS & TLS for detailed setup instructions.

Next: Configuration