Joining an Existing Testnet
In this section, we use Docker Compose to run a validator and join an existing Testnet.
Infrastructure Requirements
Validators run via Docker Compose do not come with a pre-packaged load balancer to perform TLS termination (unlike validators running on Kubernetes).
The load balancer configuration must have the following properties:
- Support HTTP/2 connections.
- Support gRPC connections.
- Support long-lived HTTP/2 connections.
- Support a maximum body size of up to 20 MB.
- Provide TLS termination with a certificate signed by a known CA.
Finally, the load balancer that performs TLS termination must redirect traffic
from 443
to 19100
(the port exposed by the proxy).
Using Nginx
Minimum supported version: 1.18.0.
Below is an example Nginx configuration which upholds the infrastructure
requirements found in /etc/nginx/sites-available/default
:
server {
listen 80 http2;
location / {
grpc_pass grpc://127.0.0.1:19100;
}
}
server {
listen 443 ssl http2;
server_name <hostname>; # e.g. my-subdomain.my-domain.net
# SSL certificates
ssl_certificate <ssl-cert-path>; # e.g. /etc/letsencrypt/live/my-subdomain.my-domain.net/fullchain.pem
ssl_certificate_key <ssl-key-path>; # e.g. /etc/letsencrypt/live/my-subdomain.my-domain.net/privkey.pem;
# Proxy traffic to the service running on port 19100.
location / {
grpc_pass grpc://127.0.0.1:19100;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
keepalive_timeout 10m 60s;
grpc_read_timeout 10m;
grpc_send_timeout 10m;
client_header_timeout 10m;
client_body_timeout 10m;
}
Using Caddy
Minimum supported version: v2.4.3
Below is an example Caddy configuration which upholds the infrastructure
requirements found in /etc/caddy/Caddyfile
:
example.com {
reverse_proxy localhost:19100 {
transport http {
versions h2c
read_timeout 10m
write_timeout 10m
}
}
}
ScyllaDB Configuration
ScyllaDB is an open-source distributed NoSQL database built for high-performance and low-latency. Linera validators use ScyllaDB as their persistent storage.
ScyllaDB may require kernel parameters to be modified in order to work. Specifically the number of events allowed in asynchronous I/O contexts.
To set this run:
echo 1048576 > /proc/sys/fs/aio-max-nr
One-Click Deploy
Note: This section was only tested under Linux.
After downloading the linera-protocol
repository, and checking out the testnet
branch testnet_archimedes
you can run
scripts/deploy-validator.sh <hostname>
to deploy a Linera validator.
For example:
$ git fetch origin
$ git checkout -t origin/testnet_archimedes
$ scripts/deploy-validator.sh linera.mydomain.com
The public key will be printed after the command has finished executing, for example:
$ scripts/deploy-validator.sh linera.mydomain.com
...
Public Key: 92f934525762a9ed99fcc3e3d3e35a825235dae133f2682b78fe22a742bac196
The public key, in this case beginning with 92f
, must be communicated to the
Linera Protocol core team along with the chosen host name for onboarding in the
next epoch.
For a more bespoke deployment, refer to the manual installation instructions below.
Note: If you have previously deployed a validator you may need to remove old docker volumes (
docker_linera-scylla-data
anddocker_linera-shared
).
Verifying installation
To verify the installation, you can use the query-validator
command. For
example:
$ linera wallet init --with-new-chain --faucet https://faucet.testnet-archimedes.linera.net
$ linera query-validator grpcs:my-domain.com:443
RPC API hash: kd/Ru73B4ZZjXYkFqqSzoWzqpWi+NX+8IJLXOODjSko
GraphQL API hash: eZqzuBlLT0bcoQUjOCPf2j22NfZUWG95id4pdlUmhgs
WIT API hash: 4/gsw8G+47OUoEWK6hJRGt9R69RanU/OidmX7OKhqfk
Source code: https://github.com/linera-io/linera-protocol/tree/
0cd20d06af5262540535347d4cc6e5952a921d1a6a7f6dd0982159c9311cfb3e
The last line is the hash of the network's genesis configuration.
Manual Installation
This section covers everything you need to install to run a Linera validator node with Docker Compose.
Note: This section was only tested under Linux.
Docker Compose Requirements
To install Docker Compose see the installing Docker Compose section in the Docker docs.
Installing the Linera Toolchain
When installing the Linera Toolchain, you must check out the
testnet_archimedes
branch.
To install the Linera Toolchain refer to the installation section.
You want to install the toolchain from GitHub, as you'll be using the repository to run the Docker Compose validator service.
Setting up a Linera Validator
For the next section, we'll be working out of the docker
subdirectory in the
linera-protocol
repository.
Creating your Validator Configuration
Validators are configured using a TOML file. You can use the following template to set up your own validator configuration:
server_config_path = "server.json"
host = "<your-host>" # e.g. my-subdomain.my-domain.net
port = 19100
metrics_host = "proxy"
metrics_port = 21100
internal_host = "proxy"
internal_port = 20100
[external_protocol]
Grpc = "ClearText" # Depending on your load balancer you may need "Tls" here.
[internal_protocol]
Grpc = "ClearText"
[[shards]]
host = "shard"
port = 19100
metrics_host = "shard"
metrics_port = 21100
Genesis Configuration
The genesis configuration describes the committee of validators and chains at the point of network creation. It is required for validators to function.
Initially, the genesis configuration for each Testnet will be found in a public bucket managed by the Linera Protocol core team.
An example can be found here:
wget "https://storage.googleapis.com/linera-io-dev-public/testnet-archimedes/genesis.json"
Creating Your Keys
Now that the validator configuration has been created and the genesis configuration is available, the validator private keys can be generated.
To generate the private keys, the linera-server
binary is used:
linera-server generate --validators /path/to/validator/configuration.toml
This will generate a file called server.json
with the information required for
a validator to operate, including a cryptographic keypair.
The public key will be printed after the command has finished executing, for example:
$ linera-server generate --validators /path/to/validator/configuration.toml
2024-07-01T16:51:32.881255Z INFO linera_version::version_info: Linera protocol: v0.12.0
2024-07-01T16:51:32.881273Z INFO linera_version::version_info: RPC API hash: p//G+L8e12ZRwUdWoGHWYvWA/03kO0n6gtgKS4D4Q0o
2024-07-01T16:51:32.881274Z INFO linera_version::version_info: GraphQL API hash: KcS5z1lEg+L9QjcP99l5vNSc7LfCwnwEsfDvMZGJ/PM
2024-07-01T16:51:32.881277Z INFO linera_version::version_info: WIT API hash: p//G+L8e12ZRwUdWoGHWYvWA/03kO0n6gtgKS4D4Q0o
2024-07-01T16:51:32.881279Z INFO linera_version::version_info: Source code: https://github.com/linera-io/linera-protocol/tree/44b3e1ab15 (dirty)
2024-07-01T16:51:32.881519Z INFO linera_server: Wrote server config server.json
92f934525762a9ed99fcc3e3d3e35a825235dae133f2682b78fe22a742bac196 # <- Public Key
The public key, in this case beginning with 92f
, must be communicated to the
Linera Protocol core team along with the chosen host name for onboarding in the
next epoch.
Note: Before being included in the next epoch, validator nodes will receive no traffic from existing users.
Building the Linera Docker image
To build the Linera Docker image, run the following command from the root of the
linera-protocol
repository:
docker build --build-arg git_commit="$(git rev-parse --short HEAD)" -f docker/Dockerfile . -t linera
This can take several minutes.
Running a Validator Node
Now that the genesis configuration is available at docker/genesis.json
and the
server configuration is available at docker/server.json
, the validator can be
started by running from inside the docker
directory:
cd docker && docker compose up -d
This will run the Docker Compose deployment in a detached mode. It can take a few minutes for the ScyllaDB image to be downloaded and started.