Skip to content

Commit 211a15a

Browse files
johnnymatthewsjohnnymatthews
authored
Potential fixes for Devnet spin-up guide. (#279)
* Adds missing dependencies for local devnet install. * Improves devnet structure. Updates build-from-source steps.
1 parent 6fd9658 commit 211a15a

File tree

1 file changed

+102
-144
lines changed

1 file changed

+102
-144
lines changed

‎content/guides/spin-up-a-devnet.md

Lines changed: 102 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,214 +1,172 @@
11
---
2-
title: "Spin up a devnet"
3-
lead: "A developer network (devnet) is a private, isolated blockchain network that developers use to test and experiment with features and programs without affecting other Entropy networks or risking real-world assets. This guide will walk you through creating a local devnet on your machine."
2+
title: "Spin up a devnet for Entropy"
3+
lead: "A developer network (devnet) is a private blockchain network that mimics the mainnet but is isolated for testing and development purposes. This allows developers to make mistakes and iterate quickly without impacting real users or risking real-world assets. This guide will walk you through setting up a local devnet for the Entropy."
44
---
55

6-
Developers should use a devnet when testing new features, experimenting with network parameters, or during initial development stages. However, developers should avoid using it for final production deployments, security audits requiring mainnet conditions, or when real-world economic incentives need to be tested.
6+
A devnet is an essential tool for devs working with Entropy. It provides a safe and controlled environment to:
77

8-
## Docker image
8+
- Test new features and functionalities.
9+
- Experiment with network parameters.
10+
- Debug and troubleshoot issues.
11+
- Develop and test Entropy Programs without impacting mainnet.
912

10-
Spinning up a devnet using the Docker images supplied in the Entropy Core repo is the easiest way to get up and running. The requirements are fairly minimal, and everything should work straight out of the box.
13+
This guide will cover two primary methods for setting up a local Entropy devnet:
1114

12-
### Prerequisites
13-
14-
You need to have [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) installed. Verify you have them both installed by running:
15+
- [Using Docker containers]({{< relref "#docker-containers" >}}): The recommended method for most users due to its ease of use and simplicity.
16+
- [Building from source]({{< relref "building-from-source" >}}): For developers who require more control or are unable to use Docker.
1517

16-
```shell
17-
docker version && docker compose version
18-
```
18+
## Docker containers
1919

20-
```output
21-
Client:
22-
Cloud integration: v1.0.35+desktop.13
23-
Version: 26.1.1
20+
This method leverages pre-built Docker images to quickly and easily spin up a local devnet.
2421

25-
...
22+
### Prerequisites
2623

27-
Docker Compose version v2.27.0-desktop.2
28-
```
24+
- [Docker](https://docs.docker.com/engine/install/).
25+
- [Docker Compose](https://docs.docker.com/compose/install/).
26+
- Basic understanding of Docker commands.
2927

3028
### Steps
3129

32-
1. Clone the Entropy Core repository and move into the new `entropy-core` directory:
30+
1. Clone the Entropy Core repo:
3331

34-
```shell
35-
git clone https://github.com/entropyxyz/entropy-core.git
36-
cd entropy-core
37-
```
32+
```bash
33+
git clone https://github.com/entropyxyz/entropy-core.git
34+
cd entropy-core
35+
```
3836

39-
1. Add the Alice and Bob threshold-signing services (TSS) to your local `hosts` file:
37+
1. Start the Docker daemon:
4038

41-
```shell
42-
echo "127.0.0.1 alice-tss-server bob-tss-server" | sudo tee -a /etc/hosts
43-
```
39+
{{< tabs items="MacOS, Linux" >}}
40+
{{< tab >}}
41+
```shell
42+
sudo systemctl start docker
43+
```
44+
{{< /tab >}}
4445

45-
You may need to enter your computer's password when prompted.
46+
{{< tab >}}
47+
```shell
48+
dockerd
49+
```
50+
{{< /tab >}}
51+
{{< /tabs >}}
4652

4753
1. Start the Docker containers:
4854

55+
```bash
56+
docker compose up --detach
57+
```
4958

50-
```shell
51-
docker compose up --detach # Detaching is optional.
52-
```
53-
54-
```output
55-
[+] Running 0/17
56-
⠸ bob-tss-server [⠀] Pulling
57-
⠏ b3d3cc4a5268 Waiting
58-
⠏ dec0c2d4580b Waiting
59-
60-
...
61-
62-
✔ Container entropy-devnet-local-bob-chain-node-1 Started
63-
✔ Container entropy-devnet-local-alice-tss-server-1 Started
64-
✔ Container entropy-devnet-local-bob-tss-server-1 Started
65-
```
66-
67-
1. Confirm that the containers are up and running:
68-
69-
```shell
70-
docker ps
71-
```
72-
73-
```output
74-
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
75-
23116711e503 entropyxyz/entropy-tss "/usr/local/bin/entr…" 1 minutes ago Up 4 seconds 9615/tcp, 9944/tcp, 127.0.0.1:3001->3001/tcp, 30333/tcp entropy-devnet-local-alice-tss-server-1
76-
c83c2ae9da20 entropyxyz/entropy "/usr/local/bin/entr…" 1 minutes ago Up 4 seconds 3001/tcp, 9615/tcp, 30333/tcp, 127.0.0.1:9944->9944/tcp entropy-devnet-local-alice-chain-node-1
77-
5088bb75951c entropyxyz/entropy-tss "/usr/local/bin/entr…" 1 minutes ago Up 4 seconds 3001/tcp, 9615/tcp, 9944/tcp, 30333/tcp, 127.0.0.1:3002->3002/tcp entropy-devnet-local-bob-tss-server-1
78-
3b0048bcaa00 entropyxyz/entropy "/usr/local/bin/entr…" 1 minutes ago Up 4 seconds 3001/tcp, 9615/tcp, 30333/tcp, 127.0.0.1:9945->9944/tcp entropy-devnet-local-bob-chain-node-1
79-
```
80-
81-
1. Confirm that the local devnet is functioning by using the Rust test interface within the Entropy Core repo:
82-
83-
```shell
84-
cargo run -p entropy-test-cli -- --chain-endpoint="ws://127.0.0.1:9944" status
85-
```
59+
1. Verify container status:
8660

87-
```output
88-
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.60s
89-
Running `target/debug/entropy-test-cli '--chain-endpoint=ws://127.0.0.1:9944' status`
61+
```bash
62+
docker ps
63+
```
9064

91-
...
65+
This command lists all running Docker containers. Look for containers like `entropy-devnet-local-alice-chain-node-1`.
9266

93-
Hash Stored by: Times used: Size in bytes: Configurable? Has auxiliary?
94-
0x0000…0000 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 10 300498 true true
95-
Success: Got status
96-
That took 224.958542ms
97-
```
67+
1. (Optional) Check server logs:
9868

99-
If this is the first time you are running the Rust testing interface, the `cargo` command above will take a few minutes to complete.
69+
```bash
70+
docker compose logs
71+
```
10072

101-
1. You can also verify that things are working as expected by checking the server logs:
73+
While optional, this command shows logs from running containers which can be helpful for troubleshooting.
10274

103-
```shell
104-
docker compose logs
105-
```
75+
1. Stop all running containers:
10676

107-
```output
108-
alice-chain-node-1 | 2024-06-24 19:41:06 Unexpected status code: 204
109-
alice-chain-node-1 | 2024-06-24 19:41:06 💤 Idle (1 peers), best: #116 (0xd68c…bfed), finalized #113 (0x06df…be36), ⬇ 0.6kiB/s ⬆ 0.6kiB/s
110-
alice-chain-node-1 | 2024-06-24 19:41:11 💤 Idle (1 peers), best: #116 (0xd68c…bfed), finalized #114 (0xb994…0299), ⬇ 0.6kiB/s ⬆ 0.5kiB/s
111-
```
77+
```bash
78+
docker stop $(docker ps -a -q)
79+
```
11280

113-
1. To stop the network, simply use the `docker stop` command followed by the ID of each Docker container:
114-
115-
```shell
116-
docker stop $(docker ps -a -q)
117-
```
118-
119-
```output
120-
23116711e503
121-
c83c2ae9da20
122-
5088bb75951c
123-
3b0048bcaa00
124-
```
125-
126-
Alternatively, you can stop each container individually.
127-
128-
```shell
129-
docker stop 23116711
130-
docker stop c83c2...
131-
132-
...
133-
```
134-
135-
1. That's it!
136-
137-
## Build from source
81+
## Building from Source
13882

13983
It is possible to build the chain node and threshold-signature scheme server binaries. However, the process for spinning up a devnet with this method is slightly more involved than the Docker method outlined above. We recommend that you only follow this method if you have a specific reason to _not_ run Docker.
14084

14185
### Prerequisites
14286

143-
You must have the latest LTS version of [Rust](https://www.rust-lang.org/tools/install) installed, along with all the [Substrate dependencies](https://docs.substrate.io/install/) for your operating system.
87+
- [Latest LTS version of Rust](https://www.rust-lang.org/)
88+
- [Substrate dependencies](https://docs.substrate.io/install/)
14489

14590
### Steps
14691

147-
1. Clone the Entropy Core repository and move into the new `entropy-core` directory:
92+
1. Clone the Entropy Core repository:
14893

149-
```shell
150-
git clone https://github.com/entropyxyz/entropy-core.git
151-
cd entropy-core
152-
```
94+
```bash
95+
git clone https://github.com/entropyxyz/entropy-core.git
96+
cd entropy-core
97+
```
15398

154-
1. Build the chain node and threshold signature scheme server binaries:
99+
1. Compile the source into an executable binary:
155100

156-
```shell
157-
cargo build --release
158-
```
101+
```bash
102+
cargo build --release
103+
```
159104

160-
```output
161-
Downloaded asn1-rs-derive v0.4.0
162-
Downloaded byte-tools v0.3.1
163-
Downloaded const-random-macro v0.1.16
105+
```output
106+
Downloaded asn1-rs-derive v0.4.0
107+
Downloaded byte-tools v0.3.1
108+
Downloaded const-random-macro v0.1.16
164109
165-
...
166-
```
110+
...
111+
```
167112

168-
Cargo is downloading and compiling a lot of tooling for the binaries. This process may take upwards of 10 minutes, depending on your system.
113+
Cargo is downloading and compiling a lot of tooling for the binaries. This process may take upwards of 10 minutes, depending on your system.
169114

170115
1. Run the node binary:
171116

172-
```shell
173-
./target/release/entropy --dev --rpc-external
174-
```
117+
```bash
118+
./target/release/entropy --dev --rpc-external
119+
```
175120

176-
```output
177-
2024-06-24 18:36:10 💤 Idle (0 peers), best: #4 (0xe3da…d11b), finalized #0 (0xe938…3b8f), ⬇ 0 ⬆ 0
178-
2024-06-24 18:36:12 🙌 Starting consensus session on top of parent 0xe3da43079cb427b60ca77cee0fe206b933ec9df57ece549ad46a5681ea95d11b
179-
2024-06-24 18:36:12 🎁 Prepared block for proposing at 5 (2 ms) [hash: 0x636c606f7d66d8c25bc64956c14b1a9c209d035279ff4f7dccd629c346d81047; parent_hash: 0xe3da…d11b; extrinsics (1): [0x7f45…6999
180-
```
121+
```output
122+
2024-06-24 18:36:10 💤 Idle (0 peers), best: #4 (0xe3da…d11b), finalized #0 (0xe938…3b8f), ⬇ 0 ⬆ 0
123+
2024-06-24 18:36:12 🙌 Starting consensus session on top of parent 0xe3da43079cb427b60ca77cee0fe206b933ec9df57ece549ad46a5681ea95d11b
124+
2024-06-24 18:36:12 🎁 Prepared block for proposing at 5 (2 ms) [hash: 0x636c606f7d66d8c25bc64956c14b1a9c209d035279ff4f7dccd629c346d81047; parent_hash: 0xe3da…d11b; extrinsics (1): [0x7f45…6999
125+
```
181126

182-
1. Confirm that the local devnet is functioning by using the Rust test interface within the Entropy Core repo:
127+
4. (Optional) Test with the Rust test interface:
183128

184-
```shell
185-
cargo run -p entropy-test-cli -- --chain-endpoint="ws://127.0.0.1:9944" status
129+
```bash
130+
cargo run -p entropy-test-cli -- --chain-endpoint="ws://127.0.0.1:9944" status
186131
```
187132

188133
```output
189134
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.83s
190-
Running `target/debug/entropy-test-cli '--chain-endpoint=ws://127.0.0.1:9944' status`
135+
Running `target/debug/entropy-test-cli '--chain-endpoint=ws://127.0.0.1:9944' status`
191136
192137
...
193138
194-
Hash Stored by: Times used: Size in bytes: Configurable? Has auxiliary?
195-
0x0000…0000 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 10 300498 true true
139+
Hash Stored by: Times used: Size in bytes: Configurable? Has auxiliary?
140+
0x0000…0000 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY 10 300498 true true
196141
Success: Got status
197142
That took 182.155ms
198143
```
199144

200-
If this is the first time you are running the Rust testing interface, the `cargo` command above will take a few minutes to complete.
201-
202-
1. That's it!
145+
If this is the first time you are running the Rust testing interface, the `cargo` command above will take a few minutes to complete.
203146

204147
## Best Practices
205148

206-
It's important to regularly reset the network to maintain a clean testing environment, thoroughly document all configuration settings for reproducibility, and simulate various network conditions to ensure robustness.
149+
It's important to regularly reset the network to maintain a clean testing environment, thoroughly document all configuration settings for reproducibility, and simulate various network conditions to ensure robustness.
207150
208-
Developers should strive to mirror the mainnet environment as closely as possible while still maintaining flexibility for rapid iteration. If you plan to share access to the devnet, it's essential to establish a clear protocol for managing and distributing test tokens, implement monitoring and logging systems to track network behaviour, and regularly update the devnet software to match planned mainnet upgrades.
151+
Developers should strive to mirror the mainnet environment as closely as possible while still maintaining flexibility for rapid iteration. If you plan to share access to the devnet, it's essential to establish a clear protocol for managing and distributing test tokens, implement monitoring and logging systems to track network behaviour, and regularly update the devnet software to match planned mainnet upgrades.
209152

210153
## Troubleshooting
211154

212155
**Cannot connect to the Docker daemon**: If you see the error message `Cannot connect to the Docker daemon at unix:///Users/johnny/.docker/run/docker.sock. Is the docker daemon running?` it's likely because your Docker daemon isn't running. Double-check that you've opened the Docker application.
213156
214157
**I can't build from source**: there are quite a few dependencies for building Substrate-based nodes. Run through the [official Substrate documentation](https://docs.substrate.io/install/) and make sure you have everything installed.
158+
159+
**Permission denied while trying to connect to the Docker daemon socket**: you likely don't have the correct permissions and user-groups set. Verify that the Docker socket file /var/run/docker.sock has the correct permissions. It should be owned by the `root` user and have appropriate permissions for the `docker` group:
160+
161+
162+
```shell
163+
sudo chown root:docker /var/run/docker.sock
164+
sudo chmod 0660 /var/run/docker.sock
165+
```
166+
167+
Also, make sure that your current user is in the `docker` group:
168+
169+
```shell
170+
sudo su
171+
usermod -aG docker your_username
172+
```

0 commit comments

Comments
 (0)