update docs to reflect new usage

willcl-ark · willcl-ark · commit 322ed31d9328 · 2024-09-02T16:23:09.000+01:00
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ Monitor and analyze the emergent behaviors of Bitcoin networks.
 - [Quick Run](/docs/quickrun.md)
 - [Running Warnet](/docs/running.md)
 - [Network Topology](/docs/graph.md)
-- [CLI Commands](/docs/warcli.md)
+- [CLI Commands](/docs/warnet.md)
 - [Scenarios](/docs/scenarios.md)
 - [Monitoring](/docs/logging_monitoring.md)
 - [Lightning Network](/docs/lightning.md)
diff --git a/docs/developer-notes.md b/docs/developer-notes.md
@@ -1,21 +1,8 @@
 # Developer notes
 
-## Kubernetes
+This project primarily uses the `uv` python packaging tool: https://docs.astral.sh/uv/ along with the sister formatter/linter `ruff` https://docs.astral.sh/ruff/
 
-Kubernetes is running the RPC server as a `statefulSet` which is pulled from a
-container image on a registry. This means that (local) changes to the RPC
-server are **not** reflected on the RPC server when running in Kubernetes,
-unless you **also** push an updated image to a registry and update the
-Kubernetes config files.
+With `uv` installed you can add/remove dependencies using `uv add <dep>` or `uv remove <dep>.
+This will update the [`uv.lock`](https://docs.astral.sh/uv/guides/projects/#uvlock) file automatically.
 
-To help with this a helper script is provided: [build-k8s-rpc.sh](../scripts/build-k8s-rpc.sh).
-
-This script can be run in the following way:
-
-```bash
-DOCKER_REGISTRY=bitcoindevproject/warnet-rpc TAG=0.1 ./scripts/build-k8s-rpc.sh Dockerfile_prod
-```
-
-You can optionally specify `LATEST=1` to also include the `latest` tag on docker hub.
-
-Once a new image has been pushed, it should be referenced in manifests/warnet-rpc-statefulset.yaml in the `image` field.
+`uv` can also run tools (like `ruff`) without external installation, simply run `uvx ruff check .` or `uvx ruff format .` to use a uv-managed format/lint on the project.
diff --git a/docs/install.md b/docs/install.md
@@ -46,6 +46,11 @@ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin
 If you have never used Docker before you may need to take a few more steps to run the Docker daemon on your system.
 The Docker daemon MUST be running before stating Warnet.
 
+#### Managing Kubernetes cluster
+
+The use of a k8s cluster management tool is highly recommended.
+We like to use `k9s`: https://k9scli.io/
+
 ##### Linux
 
 - [Check Docker user/group permissions](https://stackoverflow.com/a/48957722/1653320)
diff --git a/docs/logging_monitoring.md b/docs/logging_monitoring.md
@@ -16,7 +16,7 @@ Examples of information provided:
 
 Commands: `warnet network logs` or `warnet network logs --follow`.
 
-See more details in [warcli](/docs/warcli.md#warcli-network-logs)
+See more details in [warnet](/docs/warnet.md#warnet-network-logs)
 
 ### Bitcoin Core logs
 
@@ -54,7 +54,7 @@ warnet_test_uhynisdj_tank_000007: 2023-10-11T17:44:52.173199Z [validation] Enque
 ... (etc)
 ```
 
-See more details in [warcli](/docs/warcli.md#warcli-bitcoin-grep-logs)
+See more details in [warnet](/docs/warnet.md#warnet-bitcoin-grep-logs)
 
 ## Monitoring and Metrics
 
diff --git a/docs/quickrun.md b/docs/quickrun.md
@@ -28,39 +28,10 @@ pip install -e .
 
 ## Running
 
-> [!TIP]
-> When developing locally add the `--dev` flag to `warnet cluster deploy` to enable dev mode with hot-reloading server.
-
-### Using minikube
-
-To run a local cluster using minikube:
-
-```bash
-warnet cluster setup-minikube
-
-warnet cluster deploy
-```
-
-### Other cluster types
-
-If not using minikube (e.g. using Docker Desktop or a managed cluster), `warnet` commands will operate natively on the current Kubernetes context, so you can simply run:
+To get started simply run:
 
 ```bash
-warnet cluster deploy
+warnet quickstart
 ```
 
-...to deploy warnet to your cluster.
-
-`warnet cluster deploy` also automatically configures port forwarding to the Server in the cluster.
-
-## Stopping
-
-To tear down the cluster:
-
-```bash
-warnet cluster teardown
-```
-
-## Log location
-
-If the `$XDG_STATE_HOME` environment variable is set, the server will log to a file `$XDG_STATE_HOME/warnet/warnet.log`, otherwise it will use `$HOME/.warnet/warnet.log`.
+This will check you have the required dependencies and guide you through setting up and deploying your first network.
diff --git a/docs/running.md b/docs/running.md
@@ -3,7 +3,7 @@
 Warnet runs a server which can be used to manage multiple networks. On Kubernetes
 this runs as a `statefulSet` in the cluster.
 
-See more details in [warcli](/docs/warcli.md), examples:
+See more details in [warnet](/docs/warnet.md), examples:
 
 To start the server run:
 
diff --git a/docs/scaling.md b/docs/scaling.md
@@ -1,5 +1,8 @@
 # Running large networks
 
+> [NOTE]
+> These changes are not required on multi-host/managed clusters
+
 When running a large number of containers on a single host machine, the system may run out of various resources.
 We recommend setting the following values in /etc/sysctl.conf:
 
diff --git a/docs/scenarios.md b/docs/scenarios.md
@@ -5,50 +5,67 @@ with some modifications: most notably that `self.nodes[]` represents an array of
 containerized `bitcoind` nodes ("tanks"). Scenario files are run with a python interpreter
 inside the server and can control many nodes in the network simultaneously.
 
-See [`src/warnet/scenarios`](../src/warnet/scenarios) for examples of how these can be written.
+See [`resources/scenarios/`](../resources/scenarios/) for examples of how these can be written.
+When creating a new network default scenarios will be copied into your project directory for convenience.
 
-To see available scenarios (loaded from the default directory):
+A scenario can be run with `warnet run <path_to_scenario_file> [optional_params]`.
 
-```bash
-warnet scenarios available
-```
-
-Once a scenario is selected it can be run with `warnet scenarios run [--network=warnet] <scenario_name> [scenario_params]`.
-
-The [`miner_std`](../src/warnet/scenarios/miner_std.py) scenario is a good one to start with as it automates block generation:
+The [`miner_std`](../resources/scenarios/miner_std.py) scenario is a good one to start with as it automates block generation:
 
 ```bash
-# Have all nodes generate a block 5 seconds apart in a round-robin
-warnet scenarios run miner_std --allnodes --interval=5
-```
-
-This will run the scenario in a background thread on the server until it exits or is stopped by the user.
-
-Active scenarios can be listed and terminated by PID:
-
-```bash
-$ warnet scenarios available
-miner_std      Generate blocks over time. Options: [--allnodes | --interval=<number> | --mature]
-sens_relay     Send a transaction using sensitive relay
-tx_flood       Generate 100 blocks with 100 TXs each
-
-$ warnet scenarios run tx_flood
-Running scenario tx_flood with PID 14683 in the background...
-
-$ warnet scenarios active
-      ┃ Active ┃ Cmd       ┃ Network ┃ Pid   ┃ Return_code ┃
-      ┡━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━┩
-      │ True   │ tx_flood  │ warnet  │ 14683 │ None        ┃
-
-$ warnet scenarios stop 14683
-Stopped scenario with PID 14683.
+₿ warnet run build55/scenarios/miner_std.py  --allnodes --interval=10
+configmap/warnetjson configured
+configmap/scenariopy configured
+pod/commander-minerstd-1724708498 created
+Successfully started scenario: miner_std
+Commander pod name: commander-minerstd-1724708498
+
+₿ warnet status
+╭──────────────────── Warnet Overview ────────────────────╮
+│                                                         │
+│                      Warnet Status                      │
+│ ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ │
+│ ┃ Component ┃ Name                          ┃ Status  ┃ │
+│ ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │
+│ │ Tank      │ tank-0001                     │ running │ │
+│ │ Tank      │ tank-0002                     │ running │ │
+│ │ Tank      │ tank-0003                     │ running │ │
+│ │ Tank      │ tank-0004                     │ running │ │
+│ │ Tank      │ tank-0005                     │ running │ │
+│ │ Tank      │ tank-0006                     │ running │ │
+│ │           │                               │         │ │
+│ │ Scenario  │ commander-minerstd-1724708498 │ pending │ │
+│ └───────────┴───────────────────────────────┴─────────┘ │
+│                                                         │
+╰─────────────────────────────────────────────────────────╯
+
+Total Tanks: 6 | Active Scenarios: 1
+
+₿ warnet stop commander-minerstd-1724708498
+pod "commander-minerstd-1724708498" deleted
+Successfully stopped scenario: commander-minerstd-1724708498
+
+₿ warnet status
+╭─────────────── Warnet Overview ───────────────╮
+│                                               │
+│                 Warnet Status                 │
+│ ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ │
+│ ┃ Component ┃ Name                ┃ Status  ┃ │
+│ ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │
+│ │ Tank      │ tank-0001           │ running │ │
+│ │ Tank      │ tank-0002           │ running │ │
+│ │ Tank      │ tank-0003           │ running │ │
+│ │ Tank      │ tank-0004           │ running │ │
+│ │ Tank      │ tank-0005           │ running │ │
+│ │ Tank      │ tank-0006           │ running │ │
+│ │ Scenario  │ No active scenarios │         │ │
+│ └───────────┴─────────────────────┴─────────┘ │
+│                                               │
+╰───────────────────────────────────────────────╯
+
+Total Tanks: 6 | Active Scenarios: 0
 ```
 
 ## Running a custom scenario
 
-You can write your own scenario file locally and upload it to the server with
-the [run-file](/docs/warcli.md#warcli-scenarios-run-file) command (example):
-
-```bash
-warnet scenarios run-file /home/me/bitcoin_attack.py
-```
+You can write your own scenario file and run it in the same way.
diff --git a/docs/warnet.md b/docs/warnet.md
@@ -4,11 +4,7 @@ The command-line interface tool for Warnet.
 
 Once `warnet` is running it can be interacted with using the cli tool `warnet`.
 
-Most `warnet` commands accept a `--network` option, which allows you to specify
-the network you want to control. This is set by default to `--network="warnet"`
-to simplify default operation.
-
-Execute `warnet --help` or `warnet help` to see a list of command categories.
+Execute `warnet --help` to see a list of command categories.
 
 Help text is provided, with optional parameters in [square brackets] and required
 parameters in <angle brackets>.
diff --git a/resources/scripts/apidocs.py b/resources/scripts/apidocs.py
@@ -9,7 +9,7 @@
 
 from warnet.main import cli
 
-file_path = Path(os.path.dirname(os.path.abspath(__file__))) / ".." / ".." / "docs" / "warcli.md"
+file_path = Path(os.path.dirname(os.path.abspath(__file__))) / ".." / ".." / "docs" / "warnet.md"
 
 doc = ""
 
