Skip to content
Loomkeep Docs

Installation

  1. Get the compose files. They live in the repository, next to the example configuration:

    Terminal window
    git clone https://github.com/Logan2234/loomkeep.git
    cd loomkeep
    cp .env.example .env

  2. Fill in .env. At least:

    Variable Value
    POSTGRES_USER, POSTGRES_DB Any name, e.g. loomkeep.
    POSTGRES_PASSWORD A long random password.
    JWT_ACCESS_SECRET, JWT_REFRESH_SECRET Two different values from openssl rand -hex 32.
    MFA_ENCRYPTION_KEY openssl rand -base64 32. Needed in production, and never to be changed once someone uses two-factor authentication.
    TMDB_API_TOKEN Your TMDB token: see Catalogue keys.
    BACKUP_ENCRYPTION_PUBLIC_KEY The public key backups are encrypted for: see Backups.
    ADMIN_EMAIL The email you will sign up with: that account becomes the administrator.

    Every other variable is optional: see Configuration.

  3. Start it. Always from the repository’s root:

    Terminal window
    docker compose -f docker/docker-compose.yml pull
    docker compose -f docker/docker-compose.yml up -d

    The API applies its database migrations on its own as it starts.

  4. Create your account. Open http://localhost:8080 and sign up with ADMIN_EMAIL: Admin appears in your menu.

Ports

Section titled “Ports”

The base setup publishes the web app on port 8080 and the API on 3000, both over plain HTTP. That’s fine on a home network; for anything reachable from the internet, or to install the app on a phone, use a domain with HTTPS instead, which publishes only 80 and 443.

Adding overrides

Section titled “Adding overrides”

Every optional piece (HTTPS, monitoring…) is one more compose file. Rather than chaining -f flags, list them in COMPOSE_FILE in .env, separated by colons:

Terminal window
COMPOSE_FILE=docker/docker-compose.yml:docker/docker-compose.prod.yml

Compose reads it on its own, so from then on the commands are just:

Terminal window
docker compose pull
docker compose up -d

Next

Section titled “Next”