Skip to main content

Installation

Gatwy is distributed as a Docker image on GitHub Container Registry. Everything — app, database, and TLS — is included in a single ~150 MB container.

Prerequisites​

  • Docker Engine 20.10+ or Docker Desktop
  • Docker Compose v2 (for the Compose method)

Step 1 — Generate an Encryption Key​

Gatwy encrypts all stored credentials, MFA secrets, and session recordings using AES-256. You must provide a 64-character hex key (32 bytes) via the GATWY_ENCRYPTION_KEY environment variable.

Without this key, anyone who gains access to your data directory can decrypt all stored secrets and recordings. It takes one command to generate a secure key — do it now and keep it safe:

openssl rand -hex 32

Copy the output. You will use it in the next step.

warning

Never store the encryption key inside the data volume. If you lose the key, you cannot decrypt your credentials or recordings — and restoring from backup requires the key that was active when the backup was created.

Step 2 — Docker Compose (Recommended)​

Create a docker-compose.yml file and paste your generated key:

services:
  gatwy:
    image: ghcr.io/kotoxie/gatwy:latest
    container_name: gatwy
    restart: unless-stopped
    ports:
      - '7443:7443'
    volumes:
      - ./data:/app/data
    environment:
      - GATWY_ENCRYPTION_KEY=<your-key-from-step-1>

Start it:

docker compose up -d

Then open https://<YOUR_IP>:7443 in your browser.

First Launch

On first launch you'll be prompted to create an admin account. The browser will warn about the self-signed certificate — accept the exception to proceed, or mount your own certificate.

Step 2 (Alternative) — Docker Run​

docker run -d \
  --name gatwy \
  --restart unless-stopped \
  -p 7443:7443 \
  -v ./data:/app/data \
  -e GATWY_ENCRYPTION_KEY=<your-key-from-step-1> \
  ghcr.io/kotoxie/gatwy:latest

Step 3 — Verify​

curl -k https://localhost:7443/health

Should return a 200 OK response.

Next Steps​