{"id":15115350,"url":"https://github.com/bitvora/haven","last_synced_at":"2026-02-17T02:41:48.269Z","repository":{"id":257800071,"uuid":"861510952","full_name":"bitvora/haven","owner":"bitvora","description":"High Availability Vault for Events on Nostr","archived":false,"fork":false,"pushed_at":"2025-11-25T18:45:45.000Z","size":11754,"stargazers_count":151,"open_issues_count":9,"forks_count":35,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-12-03T12:26:38.767Z","etag":null,"topics":["blossom","blossom-server","go","nostr","nostr-relay","relay","self-hosted","social-media"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitvora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-23T03:27:40.000Z","updated_at":"2025-12-01T09:40:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"aaedc851-456b-416c-b52c-152e670f70bb","html_url":"https://github.com/bitvora/haven","commit_stats":null,"previous_names":["bitvora/haven"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bitvora/haven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitvora%2Fhaven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitvora%2Fhaven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitvora%2Fhaven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitvora%2Fhaven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitvora","download_url":"https://codeload.github.com/bitvora/haven/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitvora%2Fhaven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28330137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blossom","blossom-server","go","nostr","nostr-relay","relay","self-hosted","social-media"],"created_at":"2024-09-26T01:43:47.223Z","updated_at":"2026-02-17T02:41:48.258Z","avatar_url":"https://github.com/bitvora.png","language":"Go","funding_links":[],"categories":["Go","Relays"],"sub_categories":["Implementations"],"readme":"# HAVEN\n\n[![Go version](https://img.shields.io/github/go-mod/go-version/bitvora/haven?logo=go)](./go.mod#L3)\n[![GitHub Release](https://img.shields.io/github/v/release/bitvora/haven?link=https%3A%2F%2Fgithub.com%2Fbitvora%2Fhaven%2Freleases%2Flatest)](https://github.com/bitvora/haven/releases/latest)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n[![CI](https://github.com/bitvora/haven/actions/workflows/lint.yml/badge.svg)](https://github.com/bitvora/haven/actions/workflows/lint.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bitvora/haven)](https://goreportcard.com/report/github.com/bitvora/haven)\n\nHAVEN (High Availability Vault for Events on Nostr) is the most sovereign personal relay for the Nostr protocol, for storing and backing up sensitive notes like eCash, private chats and drafts. It is a relay that is not so dumb, with features like web of trust, inbox relay, cloud backups, blastr and the ability to import old notes. It even includes it's own blossom media server!\n\n## Four Relays in One + Blossom Media Server\n\n**Private Relay**: This relay is only accessible by the owner of the relay. It is used for drafts, ecash and other private notes that nobody can read or write to. It is protected by Auth.\n\n**Chat Relay**: This relay is used to contact the owner by DM. Only people in the web of trust can interact with this relay, protected by Auth. It only accepts encrypted DMs and group chat kinds.\n\n**Inbox Relay**: This relay is where the owner of the relay reads from. Send your zaps, reactions and replies to this relay when you're tagging the owner. You can also pull notes from this relay if you want notes where the owner is tagged. This relay automatically pulls notes from other relays. Only notes where the owner is tagged will be accepted to this relay.\n\n**Outbox Relay**: This relay is where the owner's notes all live and are publicly accessible. You can import all your old notes to this relay. All notes sent to this relay are blasted to other relays. Only the owner can send to this relay, but anyone can read.\n\n**Blossom Media Server**: This relay also includes a media server for hosting images and videos. You can upload images and videos to this relay and get a link to share them. Only the relay owner can upload to this relay, but anyone can view the images and videos.\n\n## Not So Dumb Relay Features\n\n**Web of Trust**: Protected from DM and Inbox spam by using a Web of Trust (WoT). See the [Web of Trust Documentation](docs/wot.md) for more details.\n\n**Inbox Relay**: Notes are pulled from other relays and stored in the inbox relay.\n\n**Blastr**: Notes sent to the outbox are also blasted to other relays.\n\n**Import Old Notes**: Import your old notes and notes you're tagged in from other relays.\n\n**Backup/Recover**: It is your data, manually export or import data JSONL at any time. Set periodic backups to the cloud for easy recovery if the relay is lost. See [Backup Documentation](docs/backup.md) for more details.\n\n## Installation\n\n### Option 1: Download Pre-built Binaries (Recommended)\n\nThe easiest way to get started with Haven is to download pre-built binaries from our GitHub releases page:\n\n**[Download Haven Releases](https://github.com/bitvora/haven/releases/)**\n\n#### Installation Steps:\n\n1. **Download the appropriate binary** for your system from the releases page\n2. **Verify the download (optional)**: See our [Verification Documentation](docs/verify.md) for \ninstructions on how to verify the authenticity of the binaries using GPG signatures and checksums.\n3. **Create a haven directory** and extract the downloaded file:\n   ```bash\n   mkdir haven\n   # For Linux/macOS:\n   tar -xzf haven_[Platform]_[Architecture].tar.gz -C haven\n   # For Windows: extract the .zip file to this directory\n   ```\n### Option 2: Build from Source\n\nIf you prefer to build Haven from source or need to customize the build, please see the [Build Documentation](docs/build.md).\n\n## Setup Instructions\n\nFollow these steps to get the Haven Relay running on your local machine (after installing via binary download or building from source):\n\n### 1. Copy `.env.example` to `.env`\n\nYou'll need to create an `.env` file based on the example provided.\n\n```bash\ncp .env.example .env\n```\n\n### 2. Set your environment variables\n\nOpen the `.env` file and set the necessary environment variables.\n\n### 3. Create the relays JSON files\n\nCopy the example relays JSON files for your seed and blastr relays:\n\n```bash\ncp relays_import.example.json relays_import.json\n```\n\n```bash\ncp relays_blastr.example.json relays_blastr.json\n```\n\nThe JSON should contain an array of relay URLs, which default to wss:// if you don't explicitly specify the protocol.\n\n### 4. Create the Whitelisted npubs JSON file (optional)\n\nIf you want to whitelist additional pubkeys to have the same permissions as the relay owner (private relay access, \noutbox publishing, writing to blossom, etc.), create a `whitelisted_npubs.json` file:\n\n```bash\ncp whitelisted_npubs.example.json whitelisted_npubs.json\n```\n\n\u003e [!NOTE]\n\u003e The relay owner pubkey is automatically added to the whitelist, there is no need to repeat it in the whitelist file.\n\n### 5. Run on System Startup\n\n### Linux - Create a Systemd Service\nTo have the relay run as a service, create a systemd unit file. Make sure to limit the memory usage to less than your system's total memory to prevent the relay from crashing the system.\nReplace the values for `ExecStart` and `WorkingDirectory` with the actual paths where you installed Haven and stored the `.env` file.\n\n\n1. Create the file:\n\n```bash\nsudo nano /etc/systemd/system/haven.service\n```\n\n2. Add the following contents:\n\n```ini\n[Unit]\nDescription=Haven Relay\nAfter=network.target\n\n[Service]\nExecStart=/home/ubuntu/haven/haven #Edit path to point to where you installed Haven\nWorkingDirectory=/home/ubuntu/haven #Edit path to point to where you installed Haven\nMemoryMax=1000M  # Example, Limit memory usage to 1000 MB | Edit this to fit your machine\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\n\n3. Reload systemd to recognize the new service:\n\n```bash\nsudo systemctl daemon-reload\n```\n\n4. Start the service:\n\n```bash\nsudo systemctl start haven\n```\n\n5. (Optional) Enable the service to start on boot:\n\n```bash\nsudo systemctl enable haven\n```\n\n### MacOS - Create a login item App\nTo have the relay run on boot, create a script that will open terminal and run the haven binary, the termainal will remain open and the relay running with it. Be sure the download /haven directory is locacted in the MacOS home folder ~/\n\n1. Create the App: Open Script Editor\n\n2. Add the following contents:\n\n```ini\ntell application \"Terminal\"\n  activate\n  do script \"cd \\\"$HOME/haven\\\"; ./haven; exec $SHELL\"\nend tell\n```\n3. Save in Applications folder\n\n4. Open System Settings - General - Login Items\n   Hit the plus, add run_haven from Applications folder\n\n5. Reboot - On initial restart and terminal auto-open choose “allow”\n\n6. Reboot again to test login item\n\n### 5. Serving over nginx or apache (optional)\n\nTo have a domain name (example: relay.domain.com) point to your machine, you will need to setup an nginx.\n\n1. Install nginx on your relay:\n\n```bash\nsudo apt-get update \nsudo apt-get install nginx\n```\n\n2. Remove default config: `sudo rm -rf /etc/nginx/sites-available/default`\n\n3. Create new default config: `sudo nano /etc/nginx/sites-available/default` \n\n4. Add new reverse proxy config by adding the following configuration to your nginx configuration file:\n\n```nginx\nserver {\n    listen 80;\n    server_name yourdomain.com;\n    client_max_body_size 100m;\n\n    location / {\n        proxy_pass http://localhost:3355;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n    }\n}\n```\n\nOr apache configuration file:\n```apache\n\u003cVirtualHost *:80\u003e\n        ServerName yourdomain.com\n\n        RewriteEngine On\n        RewriteCond %{HTTP:Upgrade} websocket [NC]\n        RewriteCond %{HTTP:Connection} upgrade [NC]\n        RewriteRule ^/?(.*) \"ws://localhost:3355/$1\" [P,L]\n\n        # Proxy for HTTP traffic (NIP-11 relay info page)\n        ProxyPass / http://localhost:3355/\n        ProxyPassReverse / http://localhost:3355/\n\n        # Optional: Add HSTS header for enhanced security\n        Header always set Strict-Transport-Security \"max-age=63072000; includeSubDomains; preload\"\n\n        # Optional: Set appropriate WebSocket headers\n        RequestHeader set Upgrade \"websocket\"\n        RequestHeader set Connection \"Upgrade\"\n\u003c/VirtualHost\u003e\n```\n\nReplace `yourdomain.com` with your actual domain name.\n\n\u003e [!NOTE]\n\u003e [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) is set to 100m\n\u003e to allow for larger media files to be uploaded to Blossom. `0` can be used to allow for unlimited file sizes. If you are \n\u003e using Cloudflare proxy, be mindful of [upload limits](https://community.cloudflare.com/t/maximum-upload-size-is-limit/418490/2).\n\nAfter adding the configuration, restart nginx:\n\n```bash\nsudo systemctl restart nginx\n```\n\nApache:\n```bash\nsudo systemctl restart httpd\n```\n\n### Alternative: Serving over Caddy\n\u003cdetails\u003e\u003csummary\u003eClick here to view the installation routine for Caddy\u003c/summary\u003e\n\u003cp\u003e\n\nPreparation: Set the A record (for your domain) to point to the server's IP address.\n\n1. Install caddy:\n\n```bash\nsudo apt install -y debian-keyring debian-archive-keyring apt-transport-https\ncurl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg\ncurl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list\nsudo apt update\nsudo apt install caddy\n```\n\n2. Open Caddyfile:\n\n```bash\nsudo nano /etc/caddy/Caddyfile\n```\n\n3. Add configuration:\n\n```bash\n# Configuration for HAVEN Relay\nyourdomain.com {\n    reverse_proxy localhost:3355 {\n        header_up Host {host}\n        header_up X-Real-IP {remote_host}\n        header_up X-Forwarded-For {remote_host}\n        header_up X-Forwarded-Proto {scheme}\n        transport http {\n            versions 1.1\n        }\n    }\n    request_body {\n        max_size 100MB\n    }\n}\n```\n\n4. Reload Caddy:\n\n```bash\nsudo systemctl reload caddy\n```\n\n5. Check status logs:\n\n```bash\nsudo systemctl status caddy\nsudo journalctl -u caddy -f --since \"2 hour ago\"\n```\n\n**Note:** Caddy automatically manages certificates and WebSocket connections. Certbot is not required.\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### 7. Install Certbot (optional)\n\nIf you want to serve the relay over HTTPS, you can use Certbot to generate an SSL certificate.\n\n```bash\nsudo apt-get update\nsudo apt-get install certbot python3-certbot-nginx\n```\n\nAfter installing Certbot, run the following command to generate an SSL certificate:\n\n```bash\nsudo certbot --nginx\n```\n\nApache:\n\n```bash\nsudo certbot --apache\n```\n\nFollow the instructions to generate the certificate.\n\nNote: Command will fail if the Domain you added to nginx is not yet pointing at your machine's IP address. \nThis is done by adding an A record subdomain pointing to your IP address through your DNS recrods Manager.\n\n### 8. Run The Import (optional)\n\nIf you want to import your old notes and notes you're tagged in from other relays, run the following command:\n\n```bash\nsudo systemctl stop haven\n./haven import\nsudo systemctl start haven\n```\n\n### 9. Access the relay\n\nOnce everything is set up, the relay will be running on `localhost:3355` with the following endpoints:\n\n- `localhost:3355` (outbox and Blossom server)\n- `localhost:3355/private`\n- `localhost:3355/chat`\n- `localhost:3355/inbox`\n\n## Database\n\nHaven currently supports [BadgerDB](https://github.com/dgraph-io/badger) and [LMDB](https://www.symas.com/mdb) as embedded\ndatabases, meaning no external database is required.\n\nBy default, Haven uses BadgerDB. To switch to LMDB, set the `DB_ENGINE` environment variable to `lmdb` in the `.env` file.\n\nLMDB can be faster than BadgerDB but performs best with NVMe drives and may require fine-tuning based on factors such as\ndatabase size, operating system, file system, and hardware.\n\n### LMDB Map Size\n\nThere is no one-size-fits-all value for LMDB’s map size. Windows and macOS users, in particular, may need\nto adjust the `LMDB_MAPSIZE` environment variable to a value lower than the available free disk space if the default\nvalue of 273 GB is too high. Otherwise, Haven will fail to bootstrap. Users with large databases may also need to\nincrease the `LMDB_MAPSIZE` value above the default. On most systems, the default value should work fine.\n\nDespite the large default value, on most modern systems LMDB will only use the disk space it needs. The map size simply\ndefines an upper limit for the database size. For more information about LMDB’s map size, refer to the\n[LMDB documentation](http://www.lmdb.tech/doc/group__mdb.html#gaa2506ec8dab3d969b0e609cd82e619e5).\n\n### Migrating from databases created in older versions of Haven\n\nHaven uses [Khatru's event store](https://github.com/fiatjaf/eventstore) to store notes. The way events are stored evolves \nover time, and occasionally this introduces breaking changes.\n\nAs a precaution, before upgrading to a newer version of Haven, you should back up the `db` folder.\n\nHaven versions 1.0.3 and earlier did not replace outdated notes. While this does not affect the relay's core\nfunctionality, it can result in a bloated database, reduced performance, and bugs in some clients. For this reason, it\nis recommended to delete old databases and start fresh.\n\nBadgerDB users upgrading from Haven version 1.0.5 or earlier may encounter a critical error when starting the relay:\n\n```\nerror running migrations: failed to delete index key xxxx: Txn is too big to fit into one request\n```\n\nAs a workaround, you can delete the `db` folder and start fresh, optionally [re-importing](#8-run-the-import-optional)\nprevious notes.\n\n## Blossom Media Server\n\nThe outbox relay also functions as a media server for hosting images and videos. You can upload media files to the relay and obtain a shareable link.  \nOnly the relay owner has upload permissions to the media server, but anyone can view the hosted images and videos.\n\nMedia files are stored in the file system based on the `BLOSSOM_PATH` environment variable set in the `.env` file. The default path is `./blossom`.\n\n## Cloud Backups\n\nThe relay automatically backs up your database to a cloud provider of your choice. See [Backup Documentation](docs/backup.md#periodic-cloud-backups) for more details.\n\n## License\n\nThis project is licensed under the [MIT](./LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitvora%2Fhaven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitvora%2Fhaven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitvora%2Fhaven/lists"}