Quick Start Guide

Get Keywarden running in under 5 minutes using Docker Compose.

Prerequisites

Docker and Docker Compose installed
A Linux host (or any system that runs Docker)

1. Create Project Directory

mkdir keywarden && cd keywarden

2. Create Environment File

Create a .env file with at minimum these settings:

# REQUIRED: Change these for security!
KEYWARDEN_SESSION_KEY=your-random-session-key-at-least-32-characters
KEYWARDEN_ENCRYPTION_KEY=your-random-encryption-key-at-least-32-chars

# Optional: Admin credentials (defaults: admin / auto-generated password)
KEYWARDEN_ADMIN_USER=admin
KEYWARDEN_ADMIN_EMAIL=admin@example.com

# Optional: Port (default: 8080)
KEYWARDEN_PORT=8080

Important: The KEYWARDEN_ENCRYPTION_KEY is used to encrypt all private keys at rest. If you lose this key, stored private keys cannot be decrypted. Keep it safe!

3. Create docker-compose.yml

services:
  keywarden:
    image: git.techniverse.net/scriptos/keywarden:latest
    container_name: keywarden
    restart: unless-stopped
    ports:
      - "${KEYWARDEN_PORT:-8080}:${KEYWARDEN_PORT:-8080}"
    volumes:
      - keywarden_data:/data
    env_file:
      - .env

volumes:
  keywarden_data:
    driver: local

Or, to build from source:

services:
  keywarden:
    build: .
    container_name: keywarden
    restart: unless-stopped
    ports:
      - "${KEYWARDEN_PORT:-8080}:${KEYWARDEN_PORT:-8080}"
    volumes:
      - keywarden_data:/data
    env_file:
      - .env

volumes:
  keywarden_data:
    driver: local

4. Start Keywarden

docker compose up -d

5. Get the Initial Password

On first startup, Keywarden creates an owner account and generates a secure random password. Check the logs:

docker compose logs keywarden

Look for output like:

════════════════════════════════════════════════════════════
  Initial owner account created
  Username: admin
  Password: AbCdEf1234567890XyZw
  Please change this password after first login!
════════════════════════════════════════════════════════════

6. Log In

Open your browser and navigate to http://your-host:8080, then log in with the credentials from the logs.

You will be prompted to change the initial password on first login.

7. Deploy the Master Key

After login, Keywarden displays the system master key (an Ed25519 public key). This key must be placed in the ~/.ssh/authorized_keys file of the admin/root user on every server you want to manage.

The master key is shown on the Admin Settings page and in the startup logs.

# On each target server, as root:
echo "ssh-ed25519 AAAA... keywarden-system-master" >> ~/.ssh/authorized_keys

What's Next?

Full Deployment Guide — Production setup with HTTPS and reverse proxy
User Guide — How to manage SSH keys
Admin Guide — How to manage servers and access assignments
Environment Variables — All configuration options

3.2 KiB Raw Permalink Blame History