Skip to content

Commit 322ed31

Browse files
willcl-arkwillcl-ark
committed
update docs to reflect new usage
1 parent 05da76d commit 322ed31

File tree

10 files changed

+77
-98
lines changed

10 files changed

+77
-98
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Monitor and analyze the emergent behaviors of Bitcoin networks.
1919
- [Quick Run](/docs/quickrun.md)
2020
- [Running Warnet](/docs/running.md)
2121
- [Network Topology](/docs/graph.md)
22-
- [CLI Commands](/docs/warcli.md)
22+
- [CLI Commands](/docs/warnet.md)
2323
- [Scenarios](/docs/scenarios.md)
2424
- [Monitoring](/docs/logging_monitoring.md)
2525
- [Lightning Network](/docs/lightning.md)

‎docs/developer-notes.md

Lines changed: 4 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,8 @@
11
# Developer notes
22

3-
## Kubernetes
3+
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/
44

5-
Kubernetes is running the RPC server as a `statefulSet` which is pulled from a
6-
container image on a registry. This means that (local) changes to the RPC
7-
server are **not** reflected on the RPC server when running in Kubernetes,
8-
unless you **also** push an updated image to a registry and update the
9-
Kubernetes config files.
5+
With `uv` installed you can add/remove dependencies using `uv add <dep>` or `uv remove <dep>.
6+
This will update the [`uv.lock`](https://docs.astral.sh/uv/guides/projects/#uvlock) file automatically.
107

11-
To help with this a helper script is provided: [build-k8s-rpc.sh](../scripts/build-k8s-rpc.sh).
12-
13-
This script can be run in the following way:
14-
15-
```bash
16-
DOCKER_REGISTRY=bitcoindevproject/warnet-rpc TAG=0.1 ./scripts/build-k8s-rpc.sh Dockerfile_prod
17-
```
18-
19-
You can optionally specify `LATEST=1` to also include the `latest` tag on docker hub.
20-
21-
Once a new image has been pushed, it should be referenced in manifests/warnet-rpc-statefulset.yaml in the `image` field.
8+
`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.

‎docs/install.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,11 @@ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin
4646
If you have never used Docker before you may need to take a few more steps to run the Docker daemon on your system.
4747
The Docker daemon MUST be running before stating Warnet.
4848

49+
#### Managing Kubernetes cluster
50+
51+
The use of a k8s cluster management tool is highly recommended.
52+
We like to use `k9s`: https://k9scli.io/
53+
4954
##### Linux
5055

5156
- [Check Docker user/group permissions](https://stackoverflow.com/a/48957722/1653320)

‎docs/logging_monitoring.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Examples of information provided:
1616

1717
Commands: `warnet network logs` or `warnet network logs --follow`.
1818

19-
See more details in [warcli](/docs/warcli.md#warcli-network-logs)
19+
See more details in [warnet](/docs/warnet.md#warnet-network-logs)
2020

2121
### Bitcoin Core logs
2222

@@ -54,7 +54,7 @@ warnet_test_uhynisdj_tank_000007: 2023-10-11T17:44:52.173199Z [validation] Enque
5454
... (etc)
5555
```
5656

57-
See more details in [warcli](/docs/warcli.md#warcli-bitcoin-grep-logs)
57+
See more details in [warnet](/docs/warnet.md#warnet-bitcoin-grep-logs)
5858

5959
## Monitoring and Metrics
6060

‎docs/quickrun.md

Lines changed: 3 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,39 +28,10 @@ pip install -e .
2828

2929
## Running
3030

31-
> [!TIP]
32-
> When developing locally add the `--dev` flag to `warnet cluster deploy` to enable dev mode with hot-reloading server.
33-
34-
### Using minikube
35-
36-
To run a local cluster using minikube:
37-
38-
```bash
39-
warnet cluster setup-minikube
40-
41-
warnet cluster deploy
42-
```
43-
44-
### Other cluster types
45-
46-
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:
31+
To get started simply run:
4732

4833
```bash
49-
warnet cluster deploy
34+
warnet quickstart
5035
```
5136

52-
...to deploy warnet to your cluster.
53-
54-
`warnet cluster deploy` also automatically configures port forwarding to the Server in the cluster.
55-
56-
## Stopping
57-
58-
To tear down the cluster:
59-
60-
```bash
61-
warnet cluster teardown
62-
```
63-
64-
## Log location
65-
66-
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`.
37+
This will check you have the required dependencies and guide you through setting up and deploying your first network.

‎docs/running.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Warnet runs a server which can be used to manage multiple networks. On Kubernetes
44
this runs as a `statefulSet` in the cluster.
55

6-
See more details in [warcli](/docs/warcli.md), examples:
6+
See more details in [warnet](/docs/warnet.md), examples:
77

88
To start the server run:
99

‎docs/scaling.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Running large networks
22

3+
> [NOTE]
4+
> These changes are not required on multi-host/managed clusters
5+
36
When running a large number of containers on a single host machine, the system may run out of various resources.
47
We recommend setting the following values in /etc/sysctl.conf:
58

‎docs/scenarios.md

Lines changed: 56 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,50 +5,67 @@ with some modifications: most notably that `self.nodes[]` represents an array of
55
containerized `bitcoind` nodes ("tanks"). Scenario files are run with a python interpreter
66
inside the server and can control many nodes in the network simultaneously.
77

8-
See [`src/warnet/scenarios`](../src/warnet/scenarios) for examples of how these can be written.
8+
See [`resources/scenarios/`](../resources/scenarios/) for examples of how these can be written.
9+
When creating a new network default scenarios will be copied into your project directory for convenience.
910

10-
To see available scenarios (loaded from the default directory):
11+
A scenario can be run with `warnet run <path_to_scenario_file> [optional_params]`.
1112

12-
```bash
13-
warnet scenarios available
14-
```
15-
16-
Once a scenario is selected it can be run with `warnet scenarios run [--network=warnet] <scenario_name> [scenario_params]`.
17-
18-
The [`miner_std`](../src/warnet/scenarios/miner_std.py) scenario is a good one to start with as it automates block generation:
13+
The [`miner_std`](../resources/scenarios/miner_std.py) scenario is a good one to start with as it automates block generation:
1914

2015
```bash
21-
# Have all nodes generate a block 5 seconds apart in a round-robin
22-
warnet scenarios run miner_std --allnodes --interval=5
23-
```
24-
25-
This will run the scenario in a background thread on the server until it exits or is stopped by the user.
26-
27-
Active scenarios can be listed and terminated by PID:
28-
29-
```bash
30-
$ warnet scenarios available
31-
miner_std Generate blocks over time. Options: [--allnodes | --interval=<number> | --mature]
32-
sens_relay Send a transaction using sensitive relay
33-
tx_flood Generate 100 blocks with 100 TXs each
34-
35-
$ warnet scenarios run tx_flood
36-
Running scenario tx_flood with PID 14683 in the background...
37-
38-
$ warnet scenarios active
39-
┃ Active ┃ Cmd ┃ Network ┃ Pid ┃ Return_code ┃
40-
┡━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━┩
41-
│ True │ tx_flood │ warnet │ 14683 │ None ┃
42-
43-
$ warnet scenarios stop 14683
44-
Stopped scenario with PID 14683.
16+
₿ warnet run build55/scenarios/miner_std.py --allnodes --interval=10
17+
configmap/warnetjson configured
18+
configmap/scenariopy configured
19+
pod/commander-minerstd-1724708498 created
20+
Successfully started scenario: miner_std
21+
Commander pod name: commander-minerstd-1724708498
22+
23+
₿ warnet status
24+
╭──────────────────── Warnet Overview ────────────────────╮
25+
│ │
26+
│ Warnet Status │
27+
│ ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ │
28+
│ ┃ Component ┃ Name ┃ Status ┃ │
29+
│ ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │
30+
│ │ Tank │ tank-0001 │ running │ │
31+
│ │ Tank │ tank-0002 │ running │ │
32+
│ │ Tank │ tank-0003 │ running │ │
33+
│ │ Tank │ tank-0004 │ running │ │
34+
│ │ Tank │ tank-0005 │ running │ │
35+
│ │ Tank │ tank-0006 │ running │ │
36+
│ │ │ │ │ │
37+
│ │ Scenario │ commander-minerstd-1724708498 │ pending │ │
38+
│ └───────────┴───────────────────────────────┴─────────┘ │
39+
│ │
40+
╰─────────────────────────────────────────────────────────╯
41+
42+
Total Tanks: 6 | Active Scenarios: 1
43+
44+
₿ warnet stop commander-minerstd-1724708498
45+
pod "commander-minerstd-1724708498" deleted
46+
Successfully stopped scenario: commander-minerstd-1724708498
47+
48+
₿ warnet status
49+
╭─────────────── Warnet Overview ───────────────╮
50+
│ │
51+
│ Warnet Status │
52+
│ ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ │
53+
│ ┃ Component ┃ Name ┃ Status ┃ │
54+
│ ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │
55+
│ │ Tank │ tank-0001 │ running │ │
56+
│ │ Tank │ tank-0002 │ running │ │
57+
│ │ Tank │ tank-0003 │ running │ │
58+
│ │ Tank │ tank-0004 │ running │ │
59+
│ │ Tank │ tank-0005 │ running │ │
60+
│ │ Tank │ tank-0006 │ running │ │
61+
│ │ Scenario │ No active scenarios │ │ │
62+
│ └───────────┴─────────────────────┴─────────┘ │
63+
│ │
64+
╰───────────────────────────────────────────────╯
65+
66+
Total Tanks: 6 | Active Scenarios: 0
4567
```
4668

4769
## Running a custom scenario
4870

49-
You can write your own scenario file locally and upload it to the server with
50-
the [run-file](/docs/warcli.md#warcli-scenarios-run-file) command (example):
51-
52-
```bash
53-
warnet scenarios run-file /home/me/bitcoin_attack.py
54-
```
71+
You can write your own scenario file and run it in the same way.

‎docs/warcli.md renamed to ‎docs/warnet.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,7 @@ The command-line interface tool for Warnet.
44

55
Once `warnet` is running it can be interacted with using the cli tool `warnet`.
66

7-
Most `warnet` commands accept a `--network` option, which allows you to specify
8-
the network you want to control. This is set by default to `--network="warnet"`
9-
to simplify default operation.
10-
11-
Execute `warnet --help` or `warnet help` to see a list of command categories.
7+
Execute `warnet --help` to see a list of command categories.
128

139
Help text is provided, with optional parameters in [square brackets] and required
1410
parameters in <angle brackets>.

‎resources/scripts/apidocs.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
from warnet.main import cli
1111

12-
file_path = Path(os.path.dirname(os.path.abspath(__file__))) / ".." / ".." / "docs" / "warcli.md"
12+
file_path = Path(os.path.dirname(os.path.abspath(__file__))) / ".." / ".." / "docs" / "warnet.md"
1313

1414
doc = ""
1515

0 commit comments

Comments
 (0)