bitcoin-dev-project · pinheadmz · Apr 24, 2026
diff --git a/docs/admin.md b/docs/admin.md
@@ -59,11 +59,57 @@ $ warnet auth alice-wargames-red-team-kubeconfig
 ### Set up a network for your users
 Before letting the users into your cluster, make sure to create a network of tanks for them to view.
 
-
 ```shell
 $ warnet deploy networks/mynet --to-all-users
 ```
 
 Observe that the *wargames-red-team* namespace now has tanks in it.
 
-**TODO**: What's the logging approach here?
+### User roles in `namespace-defaults.yaml`
+
+The `namespace-defaults.yaml` file controls what permissions are granted to users within each wargame namespace. The `roles` list under each user entry maps to Kubernetes RBAC roles created by the namespaces Helm chart:
+
+```yaml
+users:
+  - name: warnet-user
+    roles:
+      - pod-viewer            # read pod logs and status
+      - pod-manager           # exec into pods and manage lifecycle
+      - ingress-viewer        # view ingress resources
+      - ingress-controller-viewer  # view ingress controller resources
+```
+
+| Role | Grants |
+|------|--------|
+| `pod-viewer` | Read pod logs, status, and descriptions |
+| `pod-manager` | Exec into pods, port-forward, and manage pod lifecycle |
+| `ingress-viewer` | View ingress resources in the namespace |
+| `ingress-controller-viewer` | View ingress controller resources |
+
+## Managing namespaces
+
+List all active wargame namespaces (those with the `wargames-` prefix):
+
+```shell
+$ warnet admin namespaces list
+```
+
+Destroy a specific namespace or all wargame namespaces:
+
+```shell
+# Destroy a single namespace
+$ warnet admin namespaces destroy wargames-red-team
+
+# Destroy all wargames- prefixed namespaces
+$ warnet admin namespaces destroy --all
+```
+
+## Reverting authentication
+
+To revert to the previous kubeconfig context after switching to a user context with `warnet auth`:
+
+```shell
+$ warnet auth --revert
+```
+
+This restores the kubeconfig that was in place before the most recent `warnet auth` call.
diff --git a/docs/circuit-breaker.md b/docs/circuit-breaker.md
@@ -39,8 +39,11 @@ nodes:
 
 ### Configuration Options
 
-- `enabled`: Set to `true` to enable Circuit Breaker for the node
-- `httpPort`: Override the default HTTP port (9235) for the web UI (optional)
+| Option | Description |
+|--------|-------------|
+| `enabled` | Set to `true` to enable Circuit Breaker for the node |
+| `httpPort` | Override the default HTTP port (`9235`) for the web UI (optional) |
+| `image` | Override the Circuit Breaker Docker image (e.g. `"bitcoindevproject/circuitbreaker:v0.5.0"`) |
 
 ### Complete Example
 

diff --git a/docs/config.md b/docs/config.md
@@ -59,3 +59,171 @@ graph TD
 ```
 
 Users should only concern themselves therefore with setting configuration in the `<network_name>/[network|node-defaults].yaml` files.
+
+## Network file reference
+
+The top-level keys recognised in `network.yaml` are:
+
+| Key | Description |
+|-----|-------------|
+| `nodes:` | List of node definitions (see below) |
+| `caddy:` | `enabled: true` to deploy the Caddy reverse-proxy dashboard |
+| `fork_observer:` | `enabled: true` to deploy Fork Observer |
+| `services:` | Extra services to register on the Caddy dashboard (see below) |
+| `plugins:` | Plugin hooks (`preDeploy`, `postDeploy`, `preNode`, `postNode`, `preNetwork`, `postNetwork`) |
+| `warnet:` | Deployment label/identifier string (e.g. `"my_network"`) |
+
+### `services:` — extra dashboard entries
+
+Any additional web services running inside the cluster (e.g. a Lightning-network visualiser) can be surfaced on the Caddy dashboard alongside the built-in Grafana and Fork Observer entries:
+
+```yaml
+services:
+  - title: LN Visualizer Web UI
+    path: /lnvisualizer/
+    host: lnvisualizer.default
+    port: 80
+```
+
+Each entry supports the following fields:
+
+| Field | Description |
+|-------|-------------|
+| `title` | Display name shown on the dashboard landing page |
+| `path` | URL path prefix that Caddy will proxy to this service |
+| `host` | Kubernetes service hostname (use the `.default` suffix for cluster-internal hostnames) |
+| `port` | Port the service listens on |
+
+## Node configuration reference
+
+Each entry in the `nodes:` list is a Bitcoin Core tank. To add a Lightning node to a tank, two sibling keys work together: `ln:` enables the implementation, and `lnd:` or `cln:` holds its configuration.
+
+### Adding a Lightning node
+
+Enable LND or CLN with the `ln:` key, then configure it with a matching sibling key at the same level:
+
+```yaml
+nodes:
+  - name: tank-0000
+    ln:
+      lnd: true     # enable LND — use cln: true for Core Lightning instead
+    lnd:            # LND configuration (sibling of ln:, not nested inside it)
+      config: |
+        color=#3399FF
+      channels:
+        - id:
+            block: 500
+            index: 1
+          target: tank-0001-ln
+          capacity: 1000000
+```
+
+The `ln:` key is the on/off switch. The `lnd:` (or `cln:`) key is the configuration object. They are always at the same indentation level inside the node entry — `lnd:` is **not** nested inside `ln:`.
+
+Only one implementation may be active per node:
+
+| To enable | Set | Then configure with |
+|-----------|-----|---------------------|
+| LND | `ln.lnd: true` | `lnd:` sibling key |
+| Core Lightning | `ln.cln: true` | `cln:` sibling key |
+
+See [LN Options](ln-options.md) for the full reference of everything that goes under `lnd:` and `cln:`.
+
+---
+
+The remaining keys in this section apply to the Bitcoin Core container itself.
+
+### `global:` — chain and RPC password shorthand
+
+Sets `chain` and `rpcpassword` at the node level. These values are propagated into the Helm chart's `global` sub-object, which is also shared with LND sub-charts:
+
+```yaml
+nodes:
+  - name: tank-0000
+    global:
+      chain: signet
+      rpcpassword: mysecretpassword
+```
+
+Without `global.chain`, the default is `regtest`.
+
+### `resources:` — Kubernetes resource limits
+
+Standard Kubernetes [resource requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for the Bitcoin Core container:
+
+```yaml
+nodes:
+  - name: tank-0000
+    resources:
+      limits:
+        cpu: 4000m
+        memory: 1000Mi
+      requests:
+        cpu: 100m
+        memory: 200Mi
+```
+
+### `startupProbe:` — startup probe override
+
+Override the default Kubernetes startup probe for a node. Useful when a node requires custom initialisation before it is considered ready (e.g. importing a wallet or descriptor on first boot):
+
+```yaml
+nodes:
+  - name: miner
+    startupProbe:
+      exec:
+        command:
+          - /bin/sh
+          - -c
+          - bitcoin-cli createwallet miner
+      failureThreshold: 10
+      periodSeconds: 30
+      successThreshold: 1
+      timeoutSeconds: 60
+```
+
+### `restartPolicy:` — pod restart policy
+
+Sets the Kubernetes [restart policy](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy) for the node pod. Defaults to `Never` for Bitcoin Core nodes and `Always` for LND nodes.
+
+```yaml
+nodes:
+  - name: tank-0000
+    restartPolicy: Never
+```
+
+### `collectLogs:` and `metricsExport:`
+
+See [Logging and Monitoring](logging_monitoring.md) for details on enabling log collection and Prometheus metrics export per node.
+
+### `extraContainers:` — sidecar containers
+
+Add arbitrary sidecar containers to the Bitcoin Core pod. This is the same mechanism used to attach the `bitcoin-exporter` Prometheus sidecar. Each entry is a full Kubernetes container spec:
+
+```yaml
+nodes:
+  - name: tank-0000
+    extraContainers:
+      - name: my-sidecar
+        image: myrepo/my-sidecar:latest
+        ports:
+          - containerPort: 8080
+            name: web
+            protocol: TCP
+```
+
+## Lightning node configuration reference
+
+For the full reference of all `lnd:` and `cln:` configuration keys — including `channels`, `macaroonRootKey`, `adminMacaroon`, `resources`, `restartPolicy`, `persistence`, `metricsExport`, `extraContainers`, `circuitbreaker`, and more — see [LN Options](ln-options.md).
+
+## `node-defaults.yaml` reference
+
+The `node-defaults.yaml` file accepts the same node-level keys as `network.yaml` and applies them as defaults to every node. It additionally supports:
+
+### `warnet:` — deployment label
+
+A string identifier for the deployment, used as a label on Kubernetes resources:
+
+```yaml
+warnet: my_signet_network
+```
diff --git a/docs/connecting-local-nodes.md b/docs/connecting-local-nodes.md
@@ -70,9 +70,9 @@ telepresence intercept local-bitcoind --port 18444 -- bitcoind --regtest --datad
 ### Connect to local bitcoind from cluster
 
 ```shell
-warnet bitcoin rpc 0 addnode "local-bitcoind:18444" "onetry"
+warnet bitcoin rpc tank-0000 addnode "local-bitcoind:18444" "onetry"
 # Check that the local node was added
-warnet bitcoin rpc 0 getpeerinfo
+warnet bitcoin rpc tank-0000 getpeerinfo
 ```
 
 ### Disconnect and remove Telepresence
@@ -81,7 +81,7 @@ warnet bitcoin rpc 0 getpeerinfo
 # Disconnect from the cluster
 telepresence quit -s
 # Remove Telepresence from the cluster
-telepresent helm uninstall
+telepresence helm uninstall
 # Remove Telepresence from your computer
 sudo rm /usr/local/bin/telepresence
 ```