KeyWave - Self-Hosted Password Sharing Platform

A secure, self-hosted password sharing platform that allows teams to safely share credentials with customers and partners.

Features

• 🔐 Secure vault-based password storage with per-vault encryption
• 👥 Team collaboration with role-based access control
• 🔗 Secure password sharing via encrypted links with optional PIN protection
• 📝 Customizable password templates
• 📊 Comprehensive audit logging
• 🚀 Easy deployment with Docker Compose

Quick Start

Prerequisites

• Docker and Docker Compose installed
• A domain name (for production deployment)
• (Optional) SMTP credentials for email features

Installation

1. Clone this repository with submodules:

git clone --recurse-submodules https://github.com/YOUR_USERNAME/keywave.git
cd keywave

2. Copy the environment example:

cp .env.example .env

3. Edit .env with your configuration:

• Set a secure SECRET_KEY
• Configure your domain in SERVICE_DOMAIN
• Set database credentials
• (Optional) Configure SMTP settings
• (Optional) Set initial admin credentials

4. Start the services:

docker-compose up -d

5. Access KeyWave at your configured domain (default: http://localhost)

Configuration

Required Environment Variables

• SECRET_KEY: A secure random string for JWT signing
• SERVICE_DOMAIN: Your domain name (e.g., keywave.example.com)
• DB_PASSWORD: Database password

Optional Environment Variables

• ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME: Create initial admin user
• SMTP_*: Configure email service for notifications and MFA

Architecture

The platform consists of three services:

1. Caddy - Reverse proxy and automatic HTTPS
2. Frontend - Next.js application
3. Backend - FastAPI application with PostgreSQL

┌─────────────┐
│   Caddy     │
│  (Port 80)  │
│  (Port 443) │
└──────┬──────┘
       │
   ┌───┴────┐
   │        │
   ▼        ▼
┌──────┐ ┌────────┐     ┌──────────┐
│ Next │ │FastAPI │────▶│PostgreSQL│
│ :3000│ │ :8000  │     └──────────┘
└──────┘ └────────┘

Development

For development, you can work on the submodules independently:

Backend Development

cd backend
docker-compose up -d  # Start PostgreSQL
uv run uvicorn app.main:app --reload

Frontend Development

cd frontend
yarn dev

Updating

To update KeyWave:

# Pull latest changes
git pull --recurse-submodules

# Rebuild and restart
docker-compose build
docker-compose up -d

Backup

Important data to backup:

• PostgreSQL database
• Vault encryption keys (stored in vault_keys volume)
• .env file

Security Considerations

• Always use HTTPS in production (Caddy handles this automatically)
• Keep your SECRET_KEY secure and never commit it
• Regularly backup your data
• Monitor audit logs for suspicious activity

License

[Your License Here]