p2panda network node
Configurable node for the p2panda network, which runs as a command line
application on any computer, single-board or server.
Check out our Releases section where we publish binaries for Linux, RaspberryPi, MacOS and Windows.
For the following steps you need a Rust development environment on your machine.
# Download source code
git clone https://github.com/p2panda/aquadoggo.git
cd aquadoggo
# Compile binary
cargo build --release
# Copy binary into your path (example)
cp ./target/release/aquadoggo ~/.local/bin# For experimental setups it is enough to just start the node!
aquadoggo
# Enable logging
aquadoggo --log-level info
# By default the config.toml is loaded from the same folder or from the XDG
# config directory, but you can also specify a custom path
aquadoggo -c ../config.toml
# Turn your aquadoggo into a relay
aquadoggo --relay-mode
# Check out the config.toml file for more options or consult the help menu. You
# might need it for more sophisticated setups
aquadoggo --helpaquadoggo is a powerful node implementation which can run in very different
setups during development and in production. It can be configured through a
config.toml file, environment variables and command line arguments,
depending on your needs.
"I want to run a node which only replicates and serves data from a limited set of schemas. In this case its schemas required by a mushroom sighting app."
allow_schema_ids = [
"mushroom_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
"mushroom_finding_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0"
]"Me and my friends are running our own
p2pandanetwork supported by a couple of relay nodes, we trust each other and want to support all published data, but not allow anyone else to join the network."
# I can do this by configuring `allow_schema_ids` to be a wildcard, meaning any
# schema are automatically supported!
allow_schema_ids = "*"
# Add relay addresses to allow establishing connections over the internet
relay_addresses = [
"203.0.113.12:2022",
"203.0.113.34:2022",
]
# Enable discovery using mDNS (true by default)
mdns = true
# Populate an allow list which will contain the peer ids of our friends
# (including the ones acting as relays)
allow_peer_ids = [
"12D3KooWLxGKMgUtekXam9JsSjMa3b7M3rYEYUYUywdehHTRrLgU",
"12D3KooWP1ahRHeNp6s1M9qDJD2oyqRsYFeKLYjcjmFxrq6KM8xd",
]"I want to deploy a relay which assists in connecting edge peers but doesn't persist any data itself."
# I can do this by configuring `allow_schema_ids` an empty list, meaning this
# node does not support any schemas
allow_schema_ids = []
# Then set the relay flag so this node behaves as a relay for other nodes
relay_mode = true"I want my node to connect to a list of known and accessible peers."
# Allow all schemas
allow_schema_ids = "*"
# Address of nodes with static IP addresses we can connect directly to
direct_node_addresses = [
"192.0.2.78:2022",
"198.51.100.22:2022",
"192.0.2.211:2022",
"203.0.114.123:2022",
]"I want my node to persist its identity, uploaded files and database on the filesystem and retreive them whenever it runs again."
# Persist node private key at given location (using Linux XDG paths as an example)
private_key = "$HOME/.local/share/aquadoggo/private-key.txt"
# Persist SQLite database at given location
database_url = "sqlite:$HOME/.local/share/aquadoggo/db.sqlite3"
# Persist blobs (large binary files) at given location
blobs_base_path = "$HOME/.local/share/aquadoggo/blobs""I want only peers who know a pre-shared key to be able to join my network."
# Generate a 32 digit hexadecimal string, for example on the command line like this
hexdump -vn32 -e'"%x"' /dev/urandom
# => <PRE_SHARED_KEY>
# Pass the pre-shared key to your node via environment variables or config file
PSK=<PRE_SHARED_KEY> aquadoggoCheck out the config.toml file for all configurations and documentation or
run --help to see all possible command line arguments. All values can also be
defined as environment variables, written in CAMEL_CASE (for example
HTTP_PORT=3000).
Usage: aquadoggo [OPTIONS]
Options:
-c, --config <PATH>
Path to an optional "config.toml" file for further configuration.
When not set the program will try to find a `config.toml` file in the
same folder the program is executed in and otherwise in the regarding
operation systems XDG config directory
("$HOME/.config/aquadoggo/config.toml" on Linux).
-s, --allow-schema-ids [<SCHEMA_ID>...]
List of schema ids which a node will replicate, persist and expose on
the GraphQL API. Separate multiple values with a whitespace. Defaults
to allow _any_ schemas ("*").
When allowing a schema you automatically opt into announcing,
replicating and materializing documents connected to it, supporting
applications and networks which are dependent on this data.
It is recommended to set this list to all schema ids your own
application should support, including all important system schemas.
WARNING: When set to wildcard "*", your node will support _any_
schemas it will encounter on the network. This is useful for
experimentation and local development but _not_ recommended for
production settings.
-d, --database-url <CONNECTION_STRING>
URL / connection string to PostgreSQL or SQLite database. Defaults to
an in-memory SQLite database.
WARNING: By default your node will not persist anything after
shutdown. Set a database connection url for production settings to
not loose data.
-p, --http-port <PORT>
HTTP port for client-node communication, serving the GraphQL API.
Defaults to 2020
-q, --transport <TRANSPORT>
Protocol (TCP/QUIC) used for node-node communication and data
replication. Defaults to QUIC
-t, --node-port <PORT>
QUIC port for node-node communication and data replication. Defaults
to 2022
-y, --psk <PSK>
Pre-shared key formatted as a 64 digit hexadecimal string.
When provided a private network will be made with only peers knowing
the psk being able to form connections.
WARNING: Private networks are only supported when using TCP for the
transport layer.
-f, --blobs-base-path <PATH>
Path to folder where blobs (large binary files) are persisted.
Defaults to a temporary directory.
WARNING: By default your node will not persist any blobs after
shutdown. Set a path for production settings to not loose data.
-k, --private-key <PATH>
Path to persist your ed25519 private key file. Defaults to an
ephemeral key only for this current session.
The key is used to identify you towards other nodes during network
discovery and replication. This key is _not_ used to create and sign
data.
If a path is set, a key will be generated newly and stored under this
path when node starts for the first time.
When no path is set, your node will generate an ephemeral private key
on every start up and _not_ persist it.
-m, --mdns [<BOOL>]
mDNS to discover other peers on the local network. Enabled by default
[possible values: true, false]
-n, --direct-node-addresses [<IP:PORT>...]
List of known node addresses we want to connect to directly.
Make sure that nodes mentioned in this list are directly reachable
(they need to be hosted with a static IP Address). If you need to
connect to nodes with changing, dynamic IP addresses or even with
nodes behind a firewall or NAT, do not use this field but use at
least one relay.
-a, --allow-peer-ids [<PEER_ID>...]
List of peers which are allowed to connect to your node.
If set then only nodes (identified by their peer id) contained in
this list will be able to connect to your node (via a relay or
directly). When not set any other node can connect to yours.
Peer IDs identify nodes by using their hashed public keys. They do
_not_ represent authored data from clients and are only used to
authenticate nodes towards each other during networking.
Use this list for example for setups where the identifier of the
nodes you want to form a network with is known but you still need to
use relays as their IP addresses change dynamically.
-b, --block-peer-ids [<PEER_ID>...]
List of peers which will be blocked from connecting to your node.
If set then any peers (identified by their peer id) contained in this
list will be blocked from connecting to your node (via a relay or
directly). When an empty list is provided then there are no
restrictions on which nodes can connect to yours.
Block lists and allow lists are exclusive, which means that you
should _either_ use a block list _or_ an allow list depending on your
setup.
Use this list for example if you want to allow _any_ node to connect
to yours _except_ of a known number of excluded nodes.
-r, --relay-addresses [<IP:PORT>...]
List of relay addresses.
A relay helps discover other nodes on the internet (also known as
"rendesvouz" or "bootstrap" server) and helps establishing direct p2p
connections when node is behind a firewall or NAT (also known as
"holepunching").
WARNING: This will potentially expose your IP address on the network.
Do only connect to trusted relays or make sure your IP address is
hidden via a VPN or proxy if you're concerned about leaking your IP.
-e, --relay-mode [<BOOL>]
Enable if node should also function as a relay. Disabled by default.
Other nodes can use relays to aid discovery and establishing connectivity.
Relays _need_ to be hosted in a way where they can be reached
directly, for example with a static IP address through an VPS.
[possible values: true, false]
-l, --log-level <LEVEL>
Set log verbosity. Use this for learning more about how your node
behaves or for debugging.
Possible log levels are: ERROR, WARN, INFO, DEBUG, TRACE. They are
scoped to "aquadoggo" by default.
If you want to adjust the scope for deeper inspection use a filter
value, for example "=TRACE" for logging _everything_ or
"aquadoggo=INFO,libp2p=DEBUG" etc.
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
# Run node during development with logging enabled
cargo run -- --log-level debug
# Show logs of all modules
cargo run -- --log-level "=debug"
# Run tests
cargo testGNU Affero General Public License v3.0 AGPL-3.0-or-later
This project has received funding from the European Union’s Horizon 2020 research and innovation programme within the framework of the NGI-POINTER Project funded under grant agreement No 871528 and NGI-ASSURE No 957073