# 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

```bash
mkdir keywarden && cd keywarden
```

## 2. Create Environment File

Create a `.env` file with at minimum these settings:

Generate two separate, cryptographically secure random strings (minimum 32 characters each):

```bash
# Linux / macOS
openssl rand -base64 48

# Alternative without OpenSSL
head -c 48 /dev/urandom | base64

# Windows (PowerShell)
[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Max 256 }) -as [byte[]])
```

Each command produces a 64-character Base64 string. Run it **twice** — once for each key — and paste the values below:

```env
# REQUIRED: Change these for security!
KEYWARDEN_SESSION_KEY=<first generated string>
KEYWARDEN_ENCRYPTION_KEY=<second generated string>

# Optional: Owner credentials (defaults: admin / auto-generated password)
KEYWARDEN_OWNER_USER=admin
KEYWARDEN_OWNER_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

```yaml
services:
  keywarden:
    image: git.techniverse.net/scriptos/keywarden:latest
    container_name: keywarden
    restart: unless-stopped
    ports:
      - "${KEYWARDEN_PORT:-8080}:${KEYWARDEN_PORT:-8080}"
    volumes:
      - ./data:/data
    env_file:
      - .env
    networks:
      keywarden_net:
        ipv4_address: 172.23.64.10
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${KEYWARDEN_PORT:-8080}/api/health"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

networks:
  keywarden_net:
    name: keywarden.dockernetwork.local
    driver: bridge
    ipam:
      config:
        - subnet: 172.23.64.0/24
          gateway: 172.23.64.1
          ip_range: 172.23.64.128/25
```

## 4. Start Keywarden

```bash
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:

```bash
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.

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

## What's Next?

- [Full Deployment Guide](deployment.md) — Production setup with HTTPS and reverse proxy
- [User Guide](user-guide.md) — How to manage SSH keys
- [Admin Guide](admin-guide.md) — How to manage servers and access assignments
- [Environment Variables](environment-variables.md) — All configuration options