HAVEN Kit

Simple configuration tool to set up a HAVEN Nostr relay with Docker or Podman with just a few clicks.

Quick Start: Install on Umbrel | Using Docker | Using Podman

What is Haven?

Haven (High Availability Vault for Events on Nostr) is designed for storing and backing up sensitive notes like eCash, private chats, and drafts.

Four Relays + Media Server

Haven operates as four specialized relays in one application:

1. Private Relay - Restricted to the owner for drafts and sensitive content
2. Chat Relay - For direct messages with web-of-trust filtering
3. Inbox Relay - Aggregates notes where the owner is mentioned
4. Outbox Relay - Publicly accessible storage for owner's posts
5. Blossom Media Server - Hosts images and videos for sharing

Features

• Simple & Full Configuration Modes - Choose quick setup or advanced customization
• Web-based configuration interface (no CLI needed)
• Direct .env file editing for advanced users
• Optional relay configuration for:
  • Blastr relays: Publish your outbox notes to additional relays
  • Import relays: Import your historical notes and tagged content
• One-click note import from configured relays
• One-click restart functionality
• Real-time status monitoring
• BadgerDB or LMDB database support
• Optional S3-compatible cloud backups
• Docker and Podman support

Screenshots

Haven Kit Information

Configuration Interface

Installation on Umbrel

Option 1: Through Umbrel App Store (Coming Soon)

1. Open your Umbrel dashboard
2. Navigate to the App Store
3. Search for "Haven Kit"
4. Click Install

Option 2: Install from Community App Store

Prerequisites: umbrelOS 1.0 or later

Step 1: Add the Haven Kit Community Store

1. Open your Umbrel dashboard
2. Navigate to the App Store
3. Click the three-dot menu (⋮) in the top right corner
4. Select "Community App Stores"
5. Paste this repository URL:

   https://github.com/Letdown2491/haven-kit-umbrel
   

6. Click "Add"

Step 2: Install Haven Kit

1. Return to the App Store
2. Find "Haven Kit" in your community store section
3. Click Install
4. Wait for the installation to complete

Note: Community app stores are not verified by Umbrel. This store is maintained by the Haven Kit community.

Configuration

After installation, access the Haven configuration UI through your Umbrel dashboard.

Environment Variables (.env)

Configure the following settings through the web interface:

Database Settings

• DB_ENGINE - Choose between badger (default) or lmdb
• LMDB_MAPSIZE - Maximum database size in bytes (default: 273000000000 / 273GB)

Backup Configuration

• BACKUP_PROVIDER - Set to s3 for cloud backups or none to disable
• BACKUP_INTERVAL_HOURS - How often to backup (default: 24)

S3 Cloud Backup (Optional)

• S3_ACCESS_KEY_ID - Your S3-compatible storage access key
• S3_SECRET_KEY - Your S3-compatible storage secret key
• S3_ENDPOINT - Storage provider endpoint URL
• S3_REGION - Geographic region for your bucket
• S3_BUCKET_NAME - Name of your storage bucket

Media Storage

• BLOSSOM_PATH - Directory for media files (default: /haven/blossom)

Relay Configuration

Blastr Relays (relays_blastr.json)

Add relay URLs where your outbox posts will be automatically broadcasted. This helps distribute your content across the Nostr network.

Example:

[
  "wss://relay.damus.io",
  "wss://relay.nostr.band",
  "wss://nos.lol"
]

Import Relays (relays_import.json)

Add relay URLs from which Haven should import your old notes and tagged content.

Example:

[
  "wss://relay.damus.io",
  "wss://nostr.wine"
]

Accessing Your Relays

After configuration, your relays will be available at:

• Outbox Relay: ws://[server-ip]:3355
• Private Relay: ws://[umbrel-ip]:3355/private
• Chat Relay: ws://[umbrel-ip]:3355/chat
• Inbox Relay: ws://[umbrel-ip]:3355/inbox
• Blossom Media Server: http://[umbrel-ip]:3355

Architecture

This Umbrel app consists of two services:

1. haven_relay - The Haven relay server (port 3355)
2. config_ui - Web-based configuration interface (port 8080)

File Structure

haven-kit/
├── docker-compose.yml          # Orchestrates both services
├── umbrel-app.yml              # Umbrel app manifest
├── exports.sh                  # Environment variable exports
├── haven-relay/
│   └── Dockerfile              # Builds Haven from source
├── config-ui/
│   ├── Dockerfile              # Flask web UI container
│   ├── app.py                  # Configuration backend
│   ├── requirements.txt        # Python dependencies
│   ├── templates/
│   │   └── index.html          # Web interface
│   └── static/
│       ├── style.css           # Styling
│       └── script.js           # Client-side logic
└── data/                       # Persistent data (created at runtime)
    ├── config/                 # Configuration files
    ├── blossom/                # Media storage
    ├── db/                     # Database files
    └── templates/              # Custom templates

Data Persistence

All Haven data is stored in volumes managed by Umbrel:

• Configuration files: ${APP_DATA_DIR}/config/
• Database: ${APP_DATA_DIR}/db/
• Media files: ${APP_DATA_DIR}/blossom/
• Templates: ${APP_DATA_DIR}/templates/

Your data persists across container restarts and app updates.

Installation on local machine or VPS

Note: This section is for local development and testing using Docker or Podman on your computer. This is NOT for installing on Umbrel. For Umbrel installation, see the Installation on Umbrel section above.

Building Locally

The project supports both Docker and Podman. The configuration UI automatically detects which container runtime you're using.

Quick Setup (Recommended)

Use the provided setup script to automatically configure your environment:

# Run the setup script
./setup-env.sh

# The script will:
# - Detect Docker or Podman
# - Set up the correct socket path
# - Create necessary directories
# - Generate .env file

# Then start the services
docker-compose up -d   # for Docker
# OR
podman-compose up -d   # for Podman

Using Docker

# Build both services
docker-compose build

# Start the services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the services
docker-compose down

Using Podman

# Set the socket path environment variable
export DOCKER_SOCK=/run/user/$UID/podman/podman.sock

# Or for rootful Podman:
# export DOCKER_SOCK=/run/podman/podman.sock

# Build both services
podman-compose build

# Start the services
podman-compose up -d

# View logs
podman-compose logs -f

# Stop the services
podman-compose down

Note: The config UI will automatically detect whether you're using Docker or Podman and use the appropriate commands for container management (restart, status checks, etc.).

Updating Haven Version

To use a specific version of Haven, edit haven-relay/Dockerfile and change the HAVEN_VERSION argument:

ARG HAVEN_VERSION=v1.2.3  # Change to desired version/tag

Proxy Configuration

If you want a simple drop-in Nginx configuration for your containers to access the relay publicly, you can copy the Nginx configuration down below.

# /etc/nginx/sites-available/default

# 1) Plain HTTP: only to issue/renew certs & redirect to HTTPS
server {
  listen 80;
  listen [::]:80;
  server_name YOUR_PUBLIC_URL_HERE;

  # This will cap your Blossom upload size to 100MB so feel free to edit. Use 0 for no caps.
  client_max_body_size 100m;

  # ACME challenge path for Certbot (webroot method fallback)
  location /.well-known/acme-challenge/ { root /var/www/html; }

  # Redirect everything else to HTTPS
  location / { return 301 https://$host$request_uri; }
}

# 2) HTTPS: reverse proxy to HAVEN Relay on localhost:3355
server {
  listen 443 ssl;
  listen [::]:443 ssl;
  http2 on;
  server_name YOUR_PUBLIC_URL_HERE; # For example, relay.myhavenrelay.com. No need for http or https here.

  # SSL Certificates using Let's Encrypt
  ssl_certificate     /etc/letsencrypt/live/YOUR_PUBLIC_URL_HERE/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/YOUR_PUBLIC_URL_HERE/privkey.pem;

  client_max_body_size 100m;

  # (Optional but useful for long-lived WS/uploads)
  proxy_read_timeout  3600s;
  proxy_send_timeout  3600s;
  proxy_buffering     off;

  location / {
    proxy_pass http://127.0.0.1:3355;   # This will prevent yoour relay from being accessed via the public IP address and only internally on your machine for added security.

    # keep your relay headers exactly as recommended
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket upgrade
    proxy_http_version 1.1;
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        "upgrade";
  }
}

Troubleshooting

Haven won't start

• Check the configuration UI for status
• Review logs: docker-compose logs haven_relay
• Ensure .env file has valid configuration
• Check database size doesn't exceed available disk space

Configuration UI not accessible

• Verify port 8080 is not in use
• Check logs: docker-compose logs config_ui or podman-compose logs config_ui
• Ensure Docker/Podman socket is accessible
• For Podman users: Set DOCKER_SOCK environment variable to your Podman socket path
  • Rootless Podman: export DOCKER_SOCK=/run/user/$UID/podman/podman.sock
  • Rootful Podman: export DOCKER_SOCK=/run/podman/podman.sock

Relay not accepting connections

• Verify port 3355 is exposed correctly
• Check firewall settings on your Umbrel
• Review Haven logs for authentication/configuration issues

Development & Releases

Creating a New Release

This project uses GitHub Actions to automatically build and push Docker images when a new release is created.

To create a release:

1. Update version numbers if needed (in umbrel-app.yml, etc.)
2. Commit your changes
3. Create a new tag:

   git tag v1.0.0
   git push origin v1.0.0

4. Create a GitHub release from the tag
5. GitHub Actions will automatically:
   • Build both haven-relay and haven-config-ui images
   • Push to Docker Hub with tags latest and v1.0.0
   • Build for multiple platforms (amd64, arm64)

Manual trigger: You can also manually trigger the workflow from the GitHub Actions tab and specify a tag.

Prerequisites: Set up these GitHub repository secrets:

• DOCKER_USERNAME - Your Docker Hub username
• DOCKER_PASSWORD - Your Docker Hub password or access token

Support

• HAVEN Kit: https://github.com/Letdown2491/haven-kit
• HAVEN Project: https://github.com/bitvora/haven
• Umbrel Community: https://community.umbrel.com
• Issues: https://github.com/Letdown2491/haven-kit/issues

License

• HAVEN Kit is licensed under the MIT License. See LICENSE file for details.
• HAVEN Project is licensed under the MIT License by Bitvora.

Credits

• Haven Project: Created by Bitvora
• HAVEN Kit Configuration Tool: Created by the HAVEN Kit contributors