From 6a605b76576a8eb0bd02985f8f2c1cf406b53eba Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 25 Jul 2025 15:06:43 -0700 Subject: [PATCH 01/27] fix: rename howtos/index.html to index.md --- src/pages/resources/howtos/index.html | 9 --------- src/pages/resources/howtos/index.md | 9 +++++++++ 2 files changed, 9 insertions(+), 9 deletions(-) delete mode 100644 src/pages/resources/howtos/index.html create mode 100644 src/pages/resources/howtos/index.md diff --git a/src/pages/resources/howtos/index.html b/src/pages/resources/howtos/index.html deleted file mode 100644 index 292ca1ed3..000000000 --- a/src/pages/resources/howtos/index.html +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Howtos ---- - -::: intro -Instructions for common practical tasks -::: - -* [Debugging a Running Holochain Conductor](/resources/howtos/debugging/) \ No newline at end of file diff --git a/src/pages/resources/howtos/index.md b/src/pages/resources/howtos/index.md new file mode 100644 index 000000000..7b0cba45e --- /dev/null +++ b/src/pages/resources/howtos/index.md @@ -0,0 +1,9 @@ +--- +title: Howtos +--- + +::: intro +Instructions for common practical tasks +::: + +* [**Debugging a Running Holochain Conductor**](/resources/howtos/debugging/) --- tips on enabling and disabling log messages and interpreting what you see From e897be72049b209fc3efccf38b6814e1be61a5f5 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 25 Jul 2025 15:07:09 -0700 Subject: [PATCH 02/27] feat: draft copy for running network infrastructure --- .../howtos/running-network-infrastructure.md | 207 ++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 src/pages/resources/howtos/running-network-infrastructure.md diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md new file mode 100644 index 000000000..dcca9ba43 --- /dev/null +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -0,0 +1,207 @@ +--- +title: Running Network Infrastructure +--- + +::: intro +This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other over the public internet, and it also provides a relay fallback for peers who can't create a direct WebRTC connection. +::: + +The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: + +* Peer discovery on the public internet +* WebRTC signalling between peers +* Optionally, a WebSocket-based fallback relay server for peers who can't establish a direct WebRTC connection + +A hApp that's meant to connect peers on the public internet will most likely need these services in order to operate. + +!!! info Public server +Holochain does provide a public bootstrap and relay server at `https://dev-test-bootstrap2.holochain.org/`, but we recommend against using it for production hApps because it's low-bandwidth and has no guaranteed uptime. However, you're welcome to use it for testing. +!!! + +## Requirements + +* A server or cloud instance + * TODO: specs? +* Docker with docker-compose v2 installed on the server +* TLS certificate and key files for your server's domain name stored in the server's filesystem + +## Create a Docker compose file + +Create a `docker-compose.yaml` file in an appropriate place in your server's filesystem, then open it for editing. Here we'll be storing the file in `/var/kitsune2-bootstrap` and opening it in Visual Studio Code: + +```bash +sudo mkdir -p /var/kitsune2-bootstrap +``` +```bash +sudo cd /var/kitsune2-bootstrap +``` +```bash +sudo code docker-compose.yaml +``` + +Copy this code into the file, edit the locations of your TLS certificate and key files, and save it. + + +```yaml +services: + bootstrap: + image: ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 + command: + - kitsune2-bootstrap-srv + - --production + - --listen + - "[::]:443" + # Replace these with actual paths to your cert and key files, + # relative to the local volume mount point you specify further down. + - --tls-cert + - /etc/letsencrypt/live/bootstrap.example.org/fullchain.pem + - --tls-key + - /etc/letsencrypt/live/bootstrap.example.org/privkey.pem + # You can change this value to limit relay server bandwidth. + - --sbd-limit-ip-kbps + - "100000" + # You can also specify a burst rate in kilobytes per second. + - --sbd-limit-ip-byte-burst + - "26000000" + environment: + - RUST_LOG=info + network_mode: host + volumes: + # Replace this with the path to the TLS certificate files on the host + # and your desired mount point inside the container, in this format: + # : + - /etc/letsencrypt/:/etc/letsencrypt/ + restart: unless-stopped +``` + +!!! info Tuning the bootstrap server's performance +There are other parameters you can pass to `kitsune2-bootstrap-srv` to configure it and tune its performance. Download the bootstrap server Docker image and run the following command to see them all: + + +```bash +docker pull ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 +``` +```bash +sudo docker run -it ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 kitsune2-bootstrap-srv --help +``` +!!! + +## Run the container + +Test the configuration: + +```bash +sudo docker compose up +``` + +You should see a lot of log messages, ending with this line: + +::: output-block +```text +bootstrap-1 | #kitsune2_bootstrap_srv#listening#[::]:443# +``` +::: + +If you see this, you know your server is running and should be able to respond to requests from Holochain conductors. + +## Configure your hApp to use your bootstrap server + + + +To use your server in testing, and to test that the server is running and accessible, open your project's `package.json` file and edit the following line: + + + +```diff:json + { + "name": "my_app-dev", + "private": true, + "workspaces": [ + "ui", + "tests" + ], + "scripts": { + "start": "AGENTS=${AGENTS:-3} BOOTSTRAP_PORT=$(get-port) npm run network", + "network": "hc sandbox clean && npm run build:happ && UI_PORT=$(get-port) concurrently \"npm run start --workspace ui\" \"npm run launch:happ\" \"hc playground\"", + "test": "npm run build:zomes && hc app pack workdir --recursive && npm run test --workspace tests", + // Replace the hApp bundle name and URLs with your actual values. +- "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT workdir/my_app.happ", ++ "launch:happ": "hc-spin -n $AGENTS --ui-port --bootstrap-url "https://bootstrap.example.org" --signaling-url "wss://bootstrap.example.org" $UI_PORT workdir/my_app.happ", + // If you use the Tauri-based launcher, you can also make the following + // edits. +- "start:tauri": "AGENTS=${AGENTS:-2} BOOTSTRAP_PORT=$(get-port) npm run network:tauri", ++ "start:tauri": "AGENTS=${AGENTS:-2} npm run network:tauri", + "network:tauri": "hc sandbox clean && npm run build:happ && UI_PORT=$(get-port) concurrently \"npm run start --workspace ui\" \"npm run launch:tauri\" \"hc playground\"", +- "launch:tauri": "concurrently \"kitsune2-bootstrap-srv --listen \"127.0.0.1:$BOOTSTRAP_PORT\"\" \"echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/my_forum_app.happ --ui-port $UI_PORT network --bootstrap http://127.0.0.1:\"$BOOTSTRAP_PORT\" webrtc ws://127.0.0.1:\"$BOOTSTRAP_PORT\"\"", ++ "launch:tauri": "echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/my_forum_app.happ --ui-port $UI_PORT network --bootstrap \"https://bootstrap.example.org\" webrtc \"wss://bootstrap.example.org\"", + "package": "npm run build:happ && npm run package --workspace ui && hc web-app pack workdir --recursive", + "build:happ": "npm run build:zomes && hc app pack workdir --recursive", + "build:zomes": "cargo build --release --target wasm32-unknown-unknown" + }, + "devDependencies": { + "@holochain/hc-spin": "^0.500.0", + "concurrently": "^6.5.1", + "get-port-cli": "^3.0.0" + }, + "engines": { + "node": ">=16.0.0" + }, + "hcScaffold": { + "template": "svelte" + } + } +``` + +If you're using [Kangaroo](https://github.com/holochain/kangaroo-electron) to build an Electron-based app, open up your project's `kangaroo.config.ts` file, then edit the following lines: + + + +```diff:typescript + import { defineConfig } from './src/main/defineConfig'; + export default defineConfig({ + appId: 'org.holochain.kangaroo-electron', + productName: 'Holochain Kangaroo Electron', + version: '0.1.0', + macOSCodeSigning: false, + windowsEVCodeSigning: false, + fallbackToIndexHtml: true, + autoUpdates: true, + systray: true, + passwordMode: 'password-optional', + // Use your actual domain name here. +- bootstrapUrl: 'https://dev-test-bootstrap2.holochain.org/', ++ bootstrapUrl: 'https://bootstrap.example.org/', +- signalUrl: 'wss://dev-test-bootstrap2.holochain.org/', ++ signalUrl: 'wss://bootstrap.example.org/', + iceUrls: ['stun:stun.l.google.com:19302','stun:stun.cloudflare.com:3478'], + bins: { + holochain: { + version: '0.5.3', + sha256: { + 'x86_64-unknown-linux-gnu': + '1165646324ad6ebd60fe8063a91ec4981dd1d7da64375603560fcc6b7ef511f7', + 'x86_64-pc-windows-msvc.exe': + '143791e1c59dd718c5b60face20792a85b752ac3bba0e58b57469690c4be6a19', + 'x86_64-apple-darwin': '540ef02bcfce6c91379e07df03d51afedc73a1f13df74e0cb9da6be58e147878', + 'aarch64-apple-darwin': 'a42edb4e8580456c95f8c91ab0699d2b5fd1f73a5df0bdb9e4f20a102de0e988', + }, + }, + lair: { + sha256: { + 'x86_64-unknown-linux-gnu': + 'x86_64-pc-windows-msvc.exe': + version: '0.6.2', + sha256: { + 'x86_64-unknown-linux-gnu': + '3c9ea3dbfc0853743dad3874856fdcfe391dca1769a6a81fc91b7578c73e92a7', + 'x86_64-pc-windows-msvc.exe': + '6392ce85e985483d43fa01709bfd518f8f67aed8ddfa5950591b4ed51d226b8e', + 'x86_64-apple-darwin': '746403e5d1655ecf14d95bccaeef11ad1abfc923e428c2f3d87c683edb6fdcdc', + 'aarch64-apple-darwin': '05c7270749bb1a5cf61b0eb344a7d7a562da34090d5ea81b4c5b6cf040dd32e8', + }, + }, + }, + }); +``` + + \ No newline at end of file From e547cc2d6b1912c03fa730fda95ca7f654880f32 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 25 Jul 2025 15:07:32 -0700 Subject: [PATCH 03/27] chore: add running network infrastructure to all the navs --- src/pages/_data/navigation/mainNav.json5 | 1 + src/pages/resources/howtos/index.md | 1 + src/pages/resources/index.md | 3 ++- 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/pages/_data/navigation/mainNav.json5 b/src/pages/_data/navigation/mainNav.json5 index 96a7ce6c1..83ce682fd 100644 --- a/src/pages/_data/navigation/mainNav.json5 +++ b/src/pages/_data/navigation/mainNav.json5 @@ -65,6 +65,7 @@ { title: "Upgrade Guides", url: "/resources/upgrade/" }, { title: "Howtos", url: "/resources/howtos/", children: [ { title: "Debugging a Running Holochain Conductor", url: "/resources/howtos/debugging/" }, + { title: "Running Network Infrastructure", url: "/resources/howtos/running-network-infrastructure/" }, ]}, { title: "HDK", url: "https://docs.rs/hdk", external: true }, { title: "HDI", url: "https://docs.rs/hdi", external: true }, diff --git a/src/pages/resources/howtos/index.md b/src/pages/resources/howtos/index.md index 7b0cba45e..1f3fa6a29 100644 --- a/src/pages/resources/howtos/index.md +++ b/src/pages/resources/howtos/index.md @@ -7,3 +7,4 @@ Instructions for common practical tasks ::: * [**Debugging a Running Holochain Conductor**](/resources/howtos/debugging/) --- tips on enabling and disabling log messages and interpreting what you see +* [**Running Network Infrastructure**](/resources/howtos/running-network-infrastructure/) --- instructions on using Docker to run a bootstrap and relay server for testing or production \ No newline at end of file diff --git a/src/pages/resources/index.md b/src/pages/resources/index.md index bdbff85e7..c6b382145 100644 --- a/src/pages/resources/index.md +++ b/src/pages/resources/index.md @@ -23,7 +23,8 @@ If you're upgrading your hApp to a newer version of Holochain, we have some [upg ## Howtos -* [Debugging a running Holochain conductor](/resources/howtos/debugging/) +* [**Debugging a Running Holochain Conductor**](/resources/howtos/debugging/) --- tips on enabling and disabling log messages and interpreting what you see +* [**Running Network Infrastructure**](/resources/howtos/running-network-infrastructure/) --- instructions on using Docker to run a bootstrap and relay server for testing or production ## HDK and HDI From bc9b012dfb326556d9f2736973af80e24daa1a30 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 28 Jul 2025 14:44:50 -0700 Subject: [PATCH 04/27] edit: more server reqs, warnings about running prod server --- .../howtos/running-network-infrastructure.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index dcca9ba43..fef169d79 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -3,27 +3,26 @@ title: Running Network Infrastructure --- ::: intro -This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other over the public internet, and it also provides a relay fallback for peers who can't create a direct WebRTC connection. +This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other over the public internet and establish a peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a WebRTC session can't be established. ::: The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: * Peer discovery on the public internet * WebRTC signalling between peers -* Optionally, a WebSocket-based fallback relay server for peers who can't establish a direct WebRTC connection +* Optionally, a WebSocket-based fallback relay server for peers who can't establish a direct WebRTC connection in the signalling step -A hApp that's meant to connect peers on the public internet will most likely need these services in order to operate. +A hApp that's meant for use on the public internet will need these services in order to operate. !!! info Public server -Holochain does provide a public bootstrap and relay server at `https://dev-test-bootstrap2.holochain.org/`, but we recommend against using it for production hApps because it's low-bandwidth and has no guaranteed uptime. However, you're welcome to use it for testing. +The Holochain Foundation provides a public bootstrap and relay server at `https://dev-test-bootstrap2.holochain.org/` that you're welcome to use for testing. It's not appropriate for production hApps, though, because it's low-bandwidth and has no uptime guarantees. !!! ## Requirements -* A server or cloud instance - * TODO: specs? +* A Linux server or cloud instance * Docker with docker-compose v2 installed on the server -* TLS certificate and key files for your server's domain name stored in the server's filesystem +* TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format -- we recommend using Let's Encrypt [certbot](https://certbot.eff.org/). ## Create a Docker compose file @@ -104,6 +103,14 @@ bootstrap-1 | #kitsune2_bootstrap_srv#listening#[::]:443# If you see this, you know your server is running and should be able to respond to requests from Holochain conductors. +!!! info Running a production server +At this point your bootstrap server is ready for testing, but it probably isn't ready for production use. Operating a secured, highly-available service is outside of the scope of this documentation. Here are things to know: + +* A DHT must be served by only one server, and the server's database is in-memory, so it can't be made high-availability via redundancy. +* The Docker compose file above configures the server as an open relay without authentication; we plan to write instructions for configuring authentication once this feature is more fully tested. +* You'll need to size your server instance for your expected peak level of usage --- it may be helpful to simulate this using a multi-conductor [Tryorama](/build/testing-with-tryorama/) test or real humans. +!!! + ## Configure your hApp to use your bootstrap server From bfc6837d86c215c384b63e4e735a9c5e74b0eceb Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 28 Jul 2025 14:46:56 -0700 Subject: [PATCH 05/27] fix: missing dict items --- .cspell/custom-words.txt | 4 ++++ .cspell/words-that-should-exist.txt | 1 + 2 files changed, 5 insertions(+) diff --git a/.cspell/custom-words.txt b/.cspell/custom-words.txt index 3ff9b2ba1..5a1a66477 100644 --- a/.cspell/custom-words.txt +++ b/.cspell/custom-words.txt @@ -13,11 +13,13 @@ Brisebois Burmeister Cachix cdylib +certbot CRDT d'Aoust Diffie ECDH fixt +fullchain gnused Hellerstein imdb @@ -30,6 +32,7 @@ IPFS keccak keypair Kleppmann +letsencrypt libasound libatk libcups @@ -46,6 +49,7 @@ NixOS nixpkgs pkgs POSIX +privkey pubkey QUIC rustc diff --git a/.cspell/words-that-should-exist.txt b/.cspell/words-that-should-exist.txt index 99b004e66..40c70dd59 100644 --- a/.cspell/words-that-should-exist.txt +++ b/.cspell/words-that-should-exist.txt @@ -18,6 +18,7 @@ howto howtos ified interoperating +kbps lifecycle lifecycles passcode From e6eb4d3e99cd647f31b2c66110525a9770367513 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 28 Jul 2025 15:07:01 -0700 Subject: [PATCH 06/27] fix: accept suggestions from coderabbit review --- .../resources/howtos/running-network-infrastructure.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index fef169d79..5e58fde76 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -32,7 +32,7 @@ Create a `docker-compose.yaml` file in an appropriate place in your server's fil sudo mkdir -p /var/kitsune2-bootstrap ``` ```bash -sudo cd /var/kitsune2-bootstrap +cd /var/kitsune2-bootstrap ``` ```bash sudo code docker-compose.yaml @@ -101,7 +101,11 @@ bootstrap-1 | #kitsune2_bootstrap_srv#listening#[::]:443# ``` ::: -If you see this, you know your server is running and should be able to respond to requests from Holochain conductors. +If you see this, you know your server is running and should be able to respond to requests from Holochain conductors. You can now run the container in detached/daemon mode: + +```bash +sudo docker compose up -d +``` !!! info Running a production server At this point your bootstrap server is ready for testing, but it probably isn't ready for production use. Operating a secured, highly-available service is outside of the scope of this documentation. Here are things to know: @@ -133,7 +137,7 @@ To use your server in testing, and to test that the server is running and access "test": "npm run build:zomes && hc app pack workdir --recursive && npm run test --workspace tests", // Replace the hApp bundle name and URLs with your actual values. - "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT workdir/my_app.happ", -+ "launch:happ": "hc-spin -n $AGENTS --ui-port --bootstrap-url "https://bootstrap.example.org" --signaling-url "wss://bootstrap.example.org" $UI_PORT workdir/my_app.happ", ++ "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT --bootstrap-url \"https://bootstrap.example.org\" --signaling-url \"wss://bootstrap.example.org\" workdir/my_app.happ", // If you use the Tauri-based launcher, you can also make the following // edits. - "start:tauri": "AGENTS=${AGENTS:-2} BOOTSTRAP_PORT=$(get-port) npm run network:tauri", From f6e095e53c6a00e9e8c5b5c31fc69229e12d89e7 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 10:19:23 -0700 Subject: [PATCH 07/27] fix: accept coderabbit suggestion --- src/pages/resources/howtos/running-network-infrastructure.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 5e58fde76..81a063d89 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -132,7 +132,8 @@ To use your server in testing, and to test that the server is running and access "tests" ], "scripts": { - "start": "AGENTS=${AGENTS:-3} BOOTSTRAP_PORT=$(get-port) npm run network", +- "start": "AGENTS=${AGENTS:-3} BOOTSTRAP_PORT=$(get-port) npm run network", ++ "start": "AGENTS=${AGENTS:-3} npm run network", "network": "hc sandbox clean && npm run build:happ && UI_PORT=$(get-port) concurrently \"npm run start --workspace ui\" \"npm run launch:happ\" \"hc playground\"", "test": "npm run build:zomes && hc app pack workdir --recursive && npm run test --workspace tests", // Replace the hApp bundle name and URLs with your actual values. From 99f9a27fe383a98221e56436b06d7f969aed806e Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 10:19:45 -0700 Subject: [PATCH 08/27] edit: be agnostic to container management tools --- src/pages/resources/howtos/running-network-infrastructure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 81a063d89..ed381424f 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -21,7 +21,7 @@ The Holochain Foundation provides a public bootstrap and relay server at `https: ## Requirements * A Linux server or cloud instance -* Docker with docker-compose v2 installed on the server +* A container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) * TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format -- we recommend using Let's Encrypt [certbot](https://certbot.eff.org/). ## Create a Docker compose file From 1915db8157c2d91f2745a62b25126e7d09e0bf0e Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 10:22:31 -0700 Subject: [PATCH 09/27] fix: even LAN hApps need discovery services --- .../resources/howtos/running-network-infrastructure.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index ed381424f..9c809df87 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -3,16 +3,16 @@ title: Running Network Infrastructure --- ::: intro -This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other over the public internet and establish a peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a WebRTC session can't be established. +This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other and establish a peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a WebRTC session can't be established. ::: The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: -* Peer discovery on the public internet +* Peer discovery * WebRTC signalling between peers * Optionally, a WebSocket-based fallback relay server for peers who can't establish a direct WebRTC connection in the signalling step -A hApp that's meant for use on the public internet will need these services in order to operate. +Any user-friendly hApp will need these services in order to operate. !!! info Public server The Holochain Foundation provides a public bootstrap and relay server at `https://dev-test-bootstrap2.holochain.org/` that you're welcome to use for testing. It's not appropriate for production hApps, though, because it's low-bandwidth and has no uptime guarantees. From 7c9f085e0ec73e0d7087f4a9a3216709df47c22b Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 10:26:35 -0700 Subject: [PATCH 10/27] fix: correct the language around bootstrap, signal, and relay --- .../resources/howtos/running-network-infrastructure.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 9c809df87..902fc0b0b 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -3,19 +3,19 @@ title: Running Network Infrastructure --- ::: intro -This howto will walk you through downloading, configuring and running a Docker setup that provides a bootstrap, signal, and relay server for a Holochain application. This server is necessary to help peers discover each other and establish a peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a WebRTC session can't be established. +This howto will walk you through downloading, configuring and running a containerized setup that provides a bootstrap and signal/relay server for a Holochain application. This server is necessary to help peers discover each other and establish a direct peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a direct connection can't be established. ::: The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: * Peer discovery -* WebRTC signalling between peers -* Optionally, a WebSocket-based fallback relay server for peers who can't establish a direct WebRTC connection in the signalling step +* WebSocket-based signalling for WebRTC connection setup between peers +* Optionally, the same WebSocket protocol can be used as a relay by peers who can't establish a direct connection to each other in the signalling step Any user-friendly hApp will need these services in order to operate. !!! info Public server -The Holochain Foundation provides a public bootstrap and relay server at `https://dev-test-bootstrap2.holochain.org/` that you're welcome to use for testing. It's not appropriate for production hApps, though, because it's low-bandwidth and has no uptime guarantees. +The Holochain Foundation provides a public bootstrap server at `https://dev-test-bootstrap2.holochain.org/` that you're welcome to use for testing. It's not appropriate for production hApps, though, because it's low-bandwidth and has no uptime guarantees. !!! ## Requirements From 939c2114b2070c43fb02ac233fce0f09850a44a1 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 10:29:03 -0700 Subject: [PATCH 11/27] edit/fix: even more container-tool-agnostic, remove sudo, full arg names --- .../resources/howtos/running-network-infrastructure.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 902fc0b0b..0c4f9eea7 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -21,7 +21,7 @@ The Holochain Foundation provides a public bootstrap server at `https://dev-test ## Requirements * A Linux server or cloud instance -* A container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) +* A container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) (our examples will use the `docker` command) * TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format -- we recommend using Let's Encrypt [certbot](https://certbot.eff.org/). ## Create a Docker compose file @@ -74,14 +74,14 @@ services: ``` !!! info Tuning the bootstrap server's performance -There are other parameters you can pass to `kitsune2-bootstrap-srv` to configure it and tune its performance. Download the bootstrap server Docker image and run the following command to see them all: +There are other parameters you can pass to `kitsune2-bootstrap-srv` to configure it and tune its performance. Download the bootstrap server Docker image and run the following command to see them all. ```bash docker pull ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 ``` ```bash -sudo docker run -it ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 kitsune2-bootstrap-srv --help +docker run -it ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 kitsune2-bootstrap-srv --help ``` !!! @@ -90,7 +90,7 @@ sudo docker run -it ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 kitsune2-bo Test the configuration: ```bash -sudo docker compose up +docker compose up ``` You should see a lot of log messages, ending with this line: @@ -104,7 +104,7 @@ bootstrap-1 | #kitsune2_bootstrap_srv#listening#[::]:443# If you see this, you know your server is running and should be able to respond to requests from Holochain conductors. You can now run the container in detached/daemon mode: ```bash -sudo docker compose up -d +docker compose up --detach ``` !!! info Running a production server From 723a732b37e0f72aacc0636a604f2dc27f845a5c Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 12:08:29 -0700 Subject: [PATCH 12/27] edit: more complete recommendations on running production server --- .../howtos/running-network-infrastructure.md | 60 ++++++------------- 1 file changed, 18 insertions(+), 42 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 0c4f9eea7..79803b099 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -108,11 +108,14 @@ docker compose up --detach ``` !!! info Running a production server -At this point your bootstrap server is ready for testing, but it probably isn't ready for production use. Operating a secured, highly-available service is outside of the scope of this documentation. Here are things to know: - -* A DHT must be served by only one server, and the server's database is in-memory, so it can't be made high-availability via redundancy. -* The Docker compose file above configures the server as an open relay without authentication; we plan to write instructions for configuring authentication once this feature is more fully tested. -* You'll need to size your server instance for your expected peak level of usage --- it may be helpful to simulate this using a multi-conductor [Tryorama](/build/testing-with-tryorama/) test or real humans. +At this point your bootstrap server is ready for testing, but it probably isn't ready for production use. Operating a production server is outside of the scope of this documentation, and will require thinking about things like securing the server, denial-of-service protection, handling container or server failures, monitoring, logging, etc. Here are things to know about the bootstrap server: + +* Even though the server keeps its own state, this state is ephemeral and can safely be disposed of (e.g., in case of a server crash and failover to another instance) with only temporary disruptions to service as peers re-announce themselves to the new server. This disruption will mostly be felt by newcomers and peers using the relay fallback. +* The state can't be shared among instances of the bootstrap server for load-sharing. +* One instance can be used as a bootstrap server while another can be used as a signal/relay server to spread the load; the only configuration necessary is to specify different URLs in your conductor configuration (see the next section). +* The Docker compose file above configures the server as an open relay without authentication; we're still working on making it easy to build authentication appropriate for your hApp. +* You'll need to size your server instance for your expected peak level of usage --- it may be helpful to simulate this using a multi-conductor [Tryorama](/build/testing-with-tryorama/) test or real humans. Our public test server currently uses a 512mb / 1 CPU virtual instance and serves an average of 50 peers without trouble, and the server binary can theoretically scale to support thousands of concurrent peers with a couple hundred using relayed connections. +* The server hasn't been tested extensively with Holochain in high-load or failure scenarios. !!! ## Configure your hApp to use your bootstrap server @@ -171,49 +174,22 @@ If you're using [Kangaroo](https://github.com/holochain/kangaroo-electron) to bu ```diff:typescript import { defineConfig } from './src/main/defineConfig'; export default defineConfig({ - appId: 'org.holochain.kangaroo-electron', - productName: 'Holochain Kangaroo Electron', - version: '0.1.0', - macOSCodeSigning: false, - windowsEVCodeSigning: false, - fallbackToIndexHtml: true, - autoUpdates: true, - systray: true, - passwordMode: 'password-optional', + // ... skipping some lines ... // Use your actual domain name here. - bootstrapUrl: 'https://dev-test-bootstrap2.holochain.org/', + bootstrapUrl: 'https://bootstrap.example.org/', - signalUrl: 'wss://dev-test-bootstrap2.holochain.org/', + signalUrl: 'wss://bootstrap.example.org/', iceUrls: ['stun:stun.l.google.com:19302','stun:stun.cloudflare.com:3478'], - bins: { - holochain: { - version: '0.5.3', - sha256: { - 'x86_64-unknown-linux-gnu': - '1165646324ad6ebd60fe8063a91ec4981dd1d7da64375603560fcc6b7ef511f7', - 'x86_64-pc-windows-msvc.exe': - '143791e1c59dd718c5b60face20792a85b752ac3bba0e58b57469690c4be6a19', - 'x86_64-apple-darwin': '540ef02bcfce6c91379e07df03d51afedc73a1f13df74e0cb9da6be58e147878', - 'aarch64-apple-darwin': 'a42edb4e8580456c95f8c91ab0699d2b5fd1f73a5df0bdb9e4f20a102de0e988', - }, - }, - lair: { - sha256: { - 'x86_64-unknown-linux-gnu': - 'x86_64-pc-windows-msvc.exe': - version: '0.6.2', - sha256: { - 'x86_64-unknown-linux-gnu': - '3c9ea3dbfc0853743dad3874856fdcfe391dca1769a6a81fc91b7578c73e92a7', - 'x86_64-pc-windows-msvc.exe': - '6392ce85e985483d43fa01709bfd518f8f67aed8ddfa5950591b4ed51d226b8e', - 'x86_64-apple-darwin': '746403e5d1655ecf14d95bccaeef11ad1abfc923e428c2f3d87c683edb6fdcdc', - 'aarch64-apple-darwin': '05c7270749bb1a5cf61b0eb344a7d7a562da34090d5ea81b4c5b6cf040dd32e8', - }, - }, - }, + // ... }); ``` - \ No newline at end of file +!!! info Hardening your server against unintended use +We've shown how to configure the server without authentication. In a production scenario, you'll likely want to authenticate incoming connections to the server because: + +* Unauthorized requests to the bootstrap endpoint could leak details about what devices are running what hApps, and +* Unauthorized requests to the signal/relay endpoint allow users of other hApps to freeload on your server's bandwidth. + +We plan to discuss authentication options more fully once the server's authentication feature has been fully built and tested. +!!! \ No newline at end of file From d3bd862e3b9f3b0fdc3e76b5c0833e926215a1f5 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 12:08:41 -0700 Subject: [PATCH 13/27] edit: remove superfluous lines in diff --- .../howtos/running-network-infrastructure.md | 21 ++----------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 79803b099..ef11963ec 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -127,13 +127,7 @@ To use your server in testing, and to test that the server is running and access ```diff:json - { - "name": "my_app-dev", - "private": true, - "workspaces": [ - "ui", - "tests" - ], + ... skipping some lines "scripts": { - "start": "AGENTS=${AGENTS:-3} BOOTSTRAP_PORT=$(get-port) npm run network", + "start": "AGENTS=${AGENTS:-3} npm run network", @@ -153,18 +147,7 @@ To use your server in testing, and to test that the server is running and access "build:happ": "npm run build:zomes && hc app pack workdir --recursive", "build:zomes": "cargo build --release --target wasm32-unknown-unknown" }, - "devDependencies": { - "@holochain/hc-spin": "^0.500.0", - "concurrently": "^6.5.1", - "get-port-cli": "^3.0.0" - }, - "engines": { - "node": ">=16.0.0" - }, - "hcScaffold": { - "template": "svelte" - } - } + ... ``` If you're using [Kangaroo](https://github.com/holochain/kangaroo-electron) to build an Electron-based app, open up your project's `kangaroo.config.ts` file, then edit the following lines: From f3dcc70e9ce9cc4764e70624431c139df5d55170 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 12:15:12 -0700 Subject: [PATCH 14/27] Edit: clarify certbot / Let's Encrypt Co-authored-by: ThetaSinner --- src/pages/resources/howtos/running-network-infrastructure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index ef11963ec..e6712935c 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -22,7 +22,7 @@ The Holochain Foundation provides a public bootstrap server at `https://dev-test * A Linux server or cloud instance * A container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) (our examples will use the `docker` command) -* TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format -- we recommend using Let's Encrypt [certbot](https://certbot.eff.org/). +* TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. In this guide we're using certificates issued by Let's Encrypt and managed by [certbot](https://certbot.eff.org/). You can choose any other method of issuing certificates, as long as the certificates will be trusted by your users. ## Create a Docker compose file From 32d5155ae7e40386453b8ed08cb3302669fdcada Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 12:15:49 -0700 Subject: [PATCH 15/27] edit: make the server OS agnostic --- src/pages/resources/howtos/running-network-infrastructure.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index ef11963ec..74671a06a 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -20,8 +20,7 @@ The Holochain Foundation provides a public bootstrap server at `https://dev-test ## Requirements -* A Linux server or cloud instance -* A container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) (our examples will use the `docker` command) +* A server with a container management tool that can use [OCI containers](https://opencontainers.org/) and understands docker-compose v2 files (e.g., [Docker](https://www.docker.com/) or [Podman](https://podman.io/)) (our examples will use the `docker` command). In our examples we'll be using Linux-specific commands and paths. * TLS certificate and key files for your server's domain name stored in the server's filesystem in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format -- we recommend using Let's Encrypt [certbot](https://certbot.eff.org/). ## Create a Docker compose file From ce751241234eb1576e1408384fa12572cd46cfbd Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 13:29:34 -0700 Subject: [PATCH 16/27] edit: better / even more agnostic paths and commands --- .../resources/howtos/running-network-infrastructure.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 74671a06a..543e406fd 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -25,16 +25,16 @@ The Holochain Foundation provides a public bootstrap server at `https://dev-test ## Create a Docker compose file -Create a `docker-compose.yaml` file in an appropriate place in your server's filesystem, then open it for editing. Here we'll be storing the file in `/var/kitsune2-bootstrap` and opening it in Visual Studio Code: +Create a `docker-compose.yaml` file in an appropriate place in your server's filesystem, then open it for editing. Here we'll be storing the file in `/opt/kitsune2-bootstrap` and editing it in Vim: ```bash -sudo mkdir -p /var/kitsune2-bootstrap +sudo mkdir -p /opt/kitsune2-bootstrap ``` ```bash -cd /var/kitsune2-bootstrap +cd /opt/kitsune2-bootstrap ``` ```bash -sudo code docker-compose.yaml +sudo vim docker-compose.yaml ``` Copy this code into the file, edit the locations of your TLS certificate and key files, and save it. From 9541d5affa7bc915b3194bc5a08895a6aac9d5af Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 13:29:59 -0700 Subject: [PATCH 17/27] edit: improve documentation of sbd params --- .../howtos/running-network-infrastructure.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 543e406fd..991f4be62 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -55,12 +55,6 @@ services: - /etc/letsencrypt/live/bootstrap.example.org/fullchain.pem - --tls-key - /etc/letsencrypt/live/bootstrap.example.org/privkey.pem - # You can change this value to limit relay server bandwidth. - - --sbd-limit-ip-kbps - - "100000" - # You can also specify a burst rate in kilobytes per second. - - --sbd-limit-ip-byte-burst - - "26000000" environment: - RUST_LOG=info network_mode: host @@ -73,14 +67,15 @@ services: ``` !!! info Tuning the bootstrap server's performance -There are other parameters you can pass to `kitsune2-bootstrap-srv` to configure it and tune its performance. Download the bootstrap server Docker image and run the following command to see them all. +You can pass various parameters to `kitsune2-bootstrap-srv` to tune the relay performance. The [`sbd_server` crate documentation](https://docs.rs/sbd-server/latest/sbd_server/struct.Config.html#structfield.limit_clients) shows the data structure; the tuning parameters are `limit_clients` onward. To pass them as arguments to the Docker container, prefix them with `sbd` and convert them to hyphen-case, like this: - -```bash -docker pull ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 -``` -```bash -docker run -it ghcr.io/holochain/kitsune2_bootstrap_srv:v0.2.11 kitsune2-bootstrap-srv --help +```yaml +# ... + command: + - kitsune2-bootstrap-srv + - --sbd-limit-clients + - 50 +# ... ``` !!! From f98ad6da39683a8665a8c5f634253bffaa1aa5d5 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 13:30:24 -0700 Subject: [PATCH 18/27] edit: improve documentation of server sizing and authentication --- .../resources/howtos/running-network-infrastructure.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 991f4be62..7585bd819 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -107,8 +107,8 @@ At this point your bootstrap server is ready for testing, but it probably isn't * Even though the server keeps its own state, this state is ephemeral and can safely be disposed of (e.g., in case of a server crash and failover to another instance) with only temporary disruptions to service as peers re-announce themselves to the new server. This disruption will mostly be felt by newcomers and peers using the relay fallback. * The state can't be shared among instances of the bootstrap server for load-sharing. * One instance can be used as a bootstrap server while another can be used as a signal/relay server to spread the load; the only configuration necessary is to specify different URLs in your conductor configuration (see the next section). -* The Docker compose file above configures the server as an open relay without authentication; we're still working on making it easy to build authentication appropriate for your hApp. -* You'll need to size your server instance for your expected peak level of usage --- it may be helpful to simulate this using a multi-conductor [Tryorama](/build/testing-with-tryorama/) test or real humans. Our public test server currently uses a 512mb / 1 CPU virtual instance and serves an average of 50 peers without trouble, and the server binary can theoretically scale to support thousands of concurrent peers with a couple hundred using relayed connections. +* The Docker compose file above configures the server as an open relay without authentication; we're working on making it easier to [build authentication](https://github.com/holochain/sbd/blob/main/spec-auth.md) appropriate for your hApp. +* You'll need to size your server instance for your expected peak level of usage --- it may be helpful to simulate this using a multi-conductor [Tryorama](/build/testing-with-tryorama/) test or real humans. Depending on your server specs and bandwidth, the server binary can theoretically scale to support thousands of concurrent peers, with a couple hundred using relayed connections. * The server hasn't been tested extensively with Holochain in high-load or failure scenarios. !!! @@ -168,5 +168,5 @@ We've shown how to configure the server without authentication. In a production * Unauthorized requests to the bootstrap endpoint could leak details about what devices are running what hApps, and * Unauthorized requests to the signal/relay endpoint allow users of other hApps to freeload on your server's bandwidth. -We plan to discuss authentication options more fully once the server's authentication feature has been fully built and tested. +We plan to discuss [authentication options](https://github.com/holochain/sbd/blob/main/spec-auth.md) in the future. !!! \ No newline at end of file From f6cbeea2b9a936bb7e940b9a590c4350f5bc43ce Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 13:30:37 -0700 Subject: [PATCH 19/27] edit: comments --- src/pages/resources/howtos/running-network-infrastructure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 7585bd819..4593f9c8d 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -121,7 +121,7 @@ To use your server in testing, and to test that the server is running and access ```diff:json - ... skipping some lines + ... "scripts": { - "start": "AGENTS=${AGENTS:-3} BOOTSTRAP_PORT=$(get-port) npm run network", + "start": "AGENTS=${AGENTS:-3} npm run network", @@ -151,7 +151,7 @@ If you're using [Kangaroo](https://github.com/holochain/kangaroo-electron) to bu ```diff:typescript import { defineConfig } from './src/main/defineConfig'; export default defineConfig({ - // ... skipping some lines ... + // ... // Use your actual domain name here. - bootstrapUrl: 'https://dev-test-bootstrap2.holochain.org/', + bootstrapUrl: 'https://bootstrap.example.org/', From 832008ac9e8f028b7da22926f76c1a7dff73c12c Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 30 Jul 2025 13:54:39 -0700 Subject: [PATCH 20/27] edit: less root please --- .../resources/howtos/running-network-infrastructure.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index e8dc622a5..0b3d84c4a 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -31,10 +31,12 @@ Create a `docker-compose.yaml` file in an appropriate place in your server's fil sudo mkdir -p /opt/kitsune2-bootstrap ``` ```bash -cd /opt/kitsune2-bootstrap +sudo touch /opt/kitsune2-bootstrap/docker-compose.yaml ``` ```bash -sudo vim docker-compose.yaml +sudo chown $(whoami) /opt/kitsune2-bootstrap/docker-compose.yaml +```bash +vim /opt/kitsune2-bootstrap/docker-compose.yaml ``` Copy this code into the file, edit the locations of your TLS certificate and key files, and save it. From 9fe853c7ae425eef4cca7a2b34357ccbae0d5541 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 08:01:35 -0700 Subject: [PATCH 21/27] fix: unclosed code block --- src/pages/resources/howtos/running-network-infrastructure.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 0b3d84c4a..64b0ce21e 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -35,6 +35,7 @@ sudo touch /opt/kitsune2-bootstrap/docker-compose.yaml ``` ```bash sudo chown $(whoami) /opt/kitsune2-bootstrap/docker-compose.yaml +``` ```bash vim /opt/kitsune2-bootstrap/docker-compose.yaml ``` From 6b4cf6e77cb5d94786cf21ca74bc5a3f010cb28d Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 08:12:13 -0700 Subject: [PATCH 22/27] edit: mention network seed for bootstrap servers that are used for both test and production --- .../howtos/running-network-infrastructure.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 64b0ce21e..05af82c25 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -119,7 +119,13 @@ At this point your bootstrap server is ready for testing, but it probably isn't -To use your server in testing, and to test that the server is running and accessible, open your project's `package.json` file and edit the following line: +### Testing + +To use your server in testing, and to test that the server is running and accessible, open your project's `package.json` file and edit the following lines. + +!!! Use a network seed during testing +If you use the same server for production and testing, you might end up writing test data to a production DHT. The example below adds a [network seed](/build/cloning/#network-seed) for test runs so that test data ends up in its own DHT. +!!! @@ -132,14 +138,15 @@ To use your server in testing, and to test that the server is running and access "test": "npm run build:zomes && hc app pack workdir --recursive && npm run test --workspace tests", // Replace the hApp bundle name and URLs with your actual values. - "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT workdir/my_app.happ", -+ "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT --bootstrap-url \"https://bootstrap.example.org\" --signaling-url \"wss://bootstrap.example.org\" workdir/my_app.happ", ++ // Use bootstrap server ++ "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT --bootstrap-url \"https://bootstrap.example.org\" --signaling-url \"wss://bootstrap.example.org\" --network-seed \"bootstrap-testing-network-only\" workdir/my_app.happ", // If you use the Tauri-based launcher, you can also make the following // edits. - "start:tauri": "AGENTS=${AGENTS:-2} BOOTSTRAP_PORT=$(get-port) npm run network:tauri", + "start:tauri": "AGENTS=${AGENTS:-2} npm run network:tauri", "network:tauri": "hc sandbox clean && npm run build:happ && UI_PORT=$(get-port) concurrently \"npm run start --workspace ui\" \"npm run launch:tauri\" \"hc playground\"", - "launch:tauri": "concurrently \"kitsune2-bootstrap-srv --listen \"127.0.0.1:$BOOTSTRAP_PORT\"\" \"echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/my_forum_app.happ --ui-port $UI_PORT network --bootstrap http://127.0.0.1:\"$BOOTSTRAP_PORT\" webrtc ws://127.0.0.1:\"$BOOTSTRAP_PORT\"\"", -+ "launch:tauri": "echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/my_forum_app.happ --ui-port $UI_PORT network --bootstrap \"https://bootstrap.example.org\" webrtc \"wss://bootstrap.example.org\"", ++ "launch:tauri": "echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/my_forum_app.happ --ui-port $UI_PORT --network-seed \"bootstrap-testing-network-only\" network --bootstrap \"https://bootstrap.example.org\" webrtc \"wss://bootstrap.example.org\"", "package": "npm run build:happ && npm run package --workspace ui && hc web-app pack workdir --recursive", "build:happ": "npm run build:zomes && hc app pack workdir --recursive", "build:zomes": "cargo build --release --target wasm32-unknown-unknown" @@ -147,6 +154,8 @@ To use your server in testing, and to test that the server is running and access ... ``` +### Production + If you're using [Kangaroo](https://github.com/holochain/kangaroo-electron) to build an Electron-based app, open up your project's `kangaroo.config.ts` file, then edit the following lines: From c3816f16f6a0b00433368aa22dcaf3d58b935a46 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 08:19:01 -0700 Subject: [PATCH 23/27] fix: Oxford comma --- src/pages/resources/howtos/running-network-infrastructure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 05af82c25..a0aaf5a25 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -3,7 +3,7 @@ title: Running Network Infrastructure --- ::: intro -This howto will walk you through downloading, configuring and running a containerized setup that provides a bootstrap and signal/relay server for a Holochain application. This server is necessary to help peers discover each other and establish a direct peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a direct connection can't be established. +This howto will walk you through downloading, configuring, and running a containerized setup that provides a bootstrap and signal/relay server for a Holochain application. This server is necessary to help peers discover each other and establish a direct peer-to-peer WebRTC connection, and it also provides a message relay service as a fallback in case a direct connection can't be established. ::: The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: From 583a072e0754d1c1b80ca39bba76ada7c0a46490 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 09:24:57 -0700 Subject: [PATCH 24/27] fix: use American spelling of signalling --- src/pages/resources/howtos/running-network-infrastructure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index a0aaf5a25..c47273d10 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -9,8 +9,8 @@ This howto will walk you through downloading, configuring, and running a contain The [kitsune2 bootstrap server](https://github.com/holochain/kitsune2/tree/main/crates/bootstrap_srv) provides: * Peer discovery -* WebSocket-based signalling for WebRTC connection setup between peers -* Optionally, the same WebSocket protocol can be used as a relay by peers who can't establish a direct connection to each other in the signalling step +* WebSocket-based signaling for WebRTC connection setup between peers +* Optionally, the same WebSocket protocol can be used as a relay by peers who can't establish a direct connection to each other in the signaling step Any user-friendly hApp will need these services in order to operate. From 22c3c5eef131d6dca363ed7191651711accdc9bb Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 09:25:10 -0700 Subject: [PATCH 25/27] fix: untagged admonition --- src/pages/resources/howtos/running-network-infrastructure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index c47273d10..a805f8ba7 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -123,7 +123,7 @@ At this point your bootstrap server is ready for testing, but it probably isn't To use your server in testing, and to test that the server is running and accessible, open your project's `package.json` file and edit the following lines. -!!! Use a network seed during testing +!!! info Use a network seed during testing If you use the same server for production and testing, you might end up writing test data to a production DHT. The example below adds a [network seed](/build/cloning/#network-seed) for test runs so that test data ends up in its own DHT. !!! From 02c8e9306417ba50d1437d4d394edb13d16f5f0a Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 09:34:29 -0700 Subject: [PATCH 26/27] fix: mount letsencrypt read-only --- src/pages/resources/howtos/running-network-infrastructure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index a805f8ba7..5c301765e 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -65,7 +65,7 @@ services: # Replace this with the path to the TLS certificate files on the host # and your desired mount point inside the container, in this format: # : - - /etc/letsencrypt/:/etc/letsencrypt/ + - /etc/letsencrypt/:/etc/letsencrypt/:ro restart: unless-stopped ``` From 400e7fb86315d229553596a483126345d4bbfabb Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 31 Jul 2025 09:57:36 -0700 Subject: [PATCH 27/27] fix: lower networking privileges for docker container --- src/pages/resources/howtos/running-network-infrastructure.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/pages/resources/howtos/running-network-infrastructure.md b/src/pages/resources/howtos/running-network-infrastructure.md index 5c301765e..2c8b5f319 100644 --- a/src/pages/resources/howtos/running-network-infrastructure.md +++ b/src/pages/resources/howtos/running-network-infrastructure.md @@ -60,7 +60,8 @@ services: - /etc/letsencrypt/live/bootstrap.example.org/privkey.pem environment: - RUST_LOG=info - network_mode: host + ports: + - "443:443" volumes: # Replace this with the path to the TLS certificate files on the host # and your desired mount point inside the container, in this format: