Requirements & setup

Server requirements

Whichever path you pick -- the Docker image already bundles these, a manual install needs them installed yourself.

Option A: Manual (Apache + PHP + MySQL)

Full control over the server, no Docker involved -- a typical Ubuntu + Apache setup takes about 15-45 minutes end to end.

Install the packages, point a vhost at public/, run the setup wizard, create your master admin account. The full step-by-step guide -- exact commands, MySQL user setup, HTTPS via Certbot, troubleshooting -- is bundled with the download as install/INSTALL.md.

Option B: Docker, straight from Docker Hub

No source download at all -- just a compose file and the public image. Good for a quick look, or a server where you'd rather not unzip anything.

1. Create a project folder and a config subfolder -- the app writes its own config here once the setup wizard runs, and it needs to exist first.

mkdir -p keylair/config && cd keylair

2. Create docker-compose.yml with this content (paste the whole block, including the cat/YAML lines, into your terminal):

cat > docker-compose.yml <<'YAML'
services:
  app:
    image: secretitemgames/keylair:latest
    ports:
      - "8080:80"
    environment:
      - DB_HOST=db
      - DB_NAME=keylair
      - DB_USER=keylair
      - DB_PASSWORD=CHANGE_ME
      - MAIL_HOSTNAME=YOURDOMAIN.COM
      # Optional: route outbound mail through an existing SMTP provider
      # instead of sending directly -- see step 3 below.
      - SMTP_RELAY_HOST=
      - SMTP_RELAY_PORT=587
      - SMTP_RELAY_USER=
      - SMTP_RELAY_PASSWORD=
    volumes:
      - ./config:/var/www/html/config
      - uploads:/var/www/html/public/uploads
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: mysql:8.0
    environment:
      - MYSQL_DATABASE=keylair
      - MYSQL_USER=keylair
      - MYSQL_PASSWORD=CHANGE_ME
      - MYSQL_ROOT_PASSWORD=CHANGE_ME_TOO
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped
volumes:
  db-data:
  uploads:
YAML

3. Change the database passwords and the mail hostname in the file you just created (CHANGE_ME / CHANGE_ME_TOO / YOURDOMAIN.COM) before going any further -- the passwords end up as real MySQL credentials, and MAIL_HOSTNAME needs to be this install's real public domain or outgoing mail (password resets, 2FA codes) will be rejected by every real mail server. A brand-new server's own IP has zero sending reputation and often no reverse-DNS (PTR) record either, which real mail servers can reject outright even with MAIL_HOSTNAME set correctly -- if that happens, the SMTP_RELAY_HOST/SMTP_RELAY_PORT/SMTP_RELAY_USER/SMTP_RELAY_PASSWORD lines are entirely optional: fill them in with the SMTP details of a mailbox or SMTP provider you already have (your own hosting SMTP, Gmail, Office 365, SendGrid, ...) to send through it instead of directly, or just leave them blank (the default) to keep sending directly.

4. Make the config folder writable -- the config folder from step 1 was created by you (likely as root), but the web server inside the container runs as www-data and needs to write config/config.php there once the setup wizard finishes:

chmod 777 config

5. Start it -- this pulls secretitemgames/keylair:latest automatically, no separate docker pull needed:

docker compose up -d

6. Open the setup wizard at http://localhost:8080/setup.php (or your server's address instead of localhost) and follow it through. Use exactly the values from your compose file above: database host db (not localhost or 127.0.0.1 -- that's the app container itself, not the database one), database name/username/password matching MYSQL_DATABASE/MYSQL_USER/MYSQL_PASSWORD. config/ and the uploads volume survive a restart or image update.

Option C: Docker, from the downloaded release

The downloaded release includes a Dockerfile and docker-compose.yml already filled in -- no compose file to write yourself.

unzip keylair-*.zip
cd key-lair-*
chmod 777 config
docker compose up -d

Before starting, edit the bundled docker-compose.yml: set MAIL_HOSTNAME to this install's real public domain (the default has no DNS records, so real mail servers reject any outgoing mail from it) and change the database passwords. The bundled SMTP_RELAY_HOST/-PORT/-USER/-PASSWORD lines are entirely optional and blank by default (sends directly); only fill them in if outgoing mail still gets rejected once MAIL_HOSTNAME is set (a brand-new server's own IP often has no reverse-DNS record either) -- point them at a mailbox or SMTP provider you already have to relay through it instead. Then open http://localhost:8080/setup.php and follow the wizard -- database host is db, everything else matches a manual install. config/ and public/uploads/ are mounted as volumes so they survive a rebuild. (The chmod is only needed if you unzipped as root or a different user than the one that ends up owning the folder -- Apache inside the container runs as www-data and needs to write config/config.php once the wizard finishes.)