0l-Operations

Tooling for operations of https://0l.network

Requirements

• Docker 20+
• Task
• Internet connection
• Dedicated IP with opened ports (check each service)

How to

• Clone this repo
• Create .env file (cp example.env .env) and set relevant variables. This depends on what you want to do:
  • Manage Docker images
  • Operate a fullnode or a validator setup
  • Run a miner only

Manage docker images

There exists a list of pre-built images that you may directly use here: https://hub.docker.com/r/nourspace/0l/tags These images were built using the Dockerfile in this repo and come without any guaranties.

• Set these env variables

  • OL_REPO: Repository to use. Defaults to https://github.com/0LNetworkCommunity/libra.git. This is useful when building forks.
  • OL_BRANCH: Release tag or branch to check out and build
  • OL_IMAGE: Docker image (username/image:tag), used to build/push images, also to run services

• Build and push docker images

  task docker:build
  task docker:push

• [Optional] Build and push source docker images

  source image is a stage in Dockerfile that has 0L source and Rust toolchain

  task docker:build:source
  task docker:push:source

• [Optional] Build and push builder docker images

  builder image is a stage in Dockerfile that has 0L source, built binaries, and Rust toolchain

  task docker:build:builder
  task docker:push:builder

Operate 0L node (Fullnode or Validator/VFN)

• Set these env variables

  • OL_DATA_DIR: points to host path where 0L data directory is located

  Create this directory if it does not yet exist

  • OL_NODE_MODE: determines node mode fullnode, validator, vfn

• Use docker compose to manage services: node, tower, monitor

  # Start service(s) in background
  docker compose up -d node tower monitor 
  
  # Tail logs
  docker compose logs -f --tail 50

Run a Tower (0L Miner) only

This is useful if you have a unix server, and you only want to mine 0L coins and identity without operating any nodes.

• Set these env variables

  • OL_DATA_DIR: points to host path where 0L data directory is located

  Create this directory if it does not yet exist

  • OL_TOWER_OPERATOR='': this is only for validators that own an operator account
  • OL_TOWER_USE_FIRST_UPSTREAM='--use-first-url': this makes sure the tower is using the upstream urls
  • OL_TOWER_TEST=y: allows reading mnemonic seed phrase from env

  There is a PR that allows reading MNEM without setting TEST=y

  • MNEM: the mnemonic seed phrase generated during account creation

• Check if an account needs to be created This step makes sure we have an account and the data directory OL_DATA_DIR contains the required files:

  • ./vdf_proofs/proof_0.json (and potentially other proofs)
  • ./key_store.json
  • ./0L.toml

• To create a new account

  # Generate mnemonic seed phrase
  onboard keygen
  
  # Let someone onboard it using authKey
  
  # Create 0L.toml file
  cd $HOME/.0L
  
  # Initialise configs (requires ol version >= 5.0.12)
  ol init --app --rpc-playlist https://raw.githubusercontent.com/0LNetworkCommunity/seed-peers/main/fullnode_seed_playlist.json
  
  # Create the first proof and `account.json`, the following will take about 30-40 minutes
  onboard user

• Use docker compose to manage tower service

  # Start Tower service in background
  docker compose up -d tower
  
  # Tail logs
  docker compose logs -f --tail 50 tower

docker compose commands

This is a list of some useful commands.

########## Main Services #########

# Start service(s)
docker compose up tower 

# You can pass one or more services
docker compose up node tower monitor

# Start service(s) in background
docker compose up -d node tower monitor 

# Display all logs
docker compose logs tower

# Tail logs
docker compose logs -f --tail 50 node

# Force recreate and start service(s)
docker compose up -d --force-recreate node 

# Stop service(s)
docker compose stop node

# Stops containers and removes containers, networks, volumes, and images
# Data directory on the host specified with `$OL_DATA_DIR` won't be deleted. Only the Docker volume will be unmounted
docker compose down

########## Utility Services #########

# Start a shell service with all 0L binaries available
# Useful to run `txs` commands
docker compose run --rm shell bash

# Start a builder service with all 0L source and binaries available
# Useful to run `make` commands
docker compose run --rm builder bash

# Start a builder service and exec into it to keep the container and its files after exiting
docker compose up -d builder
docker compose exec builder bash

# Use Task to start utility services
task shell
task source
task builder

# Clean all utility containers with their data
task clean-utils

---

Main Services

This are the main services commonly run by node operators.

node service

Ports - operations: 6179, 6180, 8080

Ports - monitoring: 9101, 9102

This service can run as either of: fullnode, validator, vfn. That is determined by the OL_NODE_MODE env variable.

tower service

Tower service can be launched in multiple modes. That depends on whether the accompanying node is fully synced or not. Validators have operator accounts that can be used to start tower without providing mnemonic phrase for owner account.

• mode 1: initial start uses upstream as fullnode/validator are not yet synced

  entrypoint: [ "tower", "--use-upstream-url", "--verbose", "start" ]

• mode 2: fullnode/validator are synced: run as non-operator (requires MNEM)

  entrypoint: [ "tower", "--verbose", "start" ]

  This mode is also meant for miners only as they will be using an upstream fullnode that is synced

• mode 3: fullnode/validator are synced: run as operator

  entrypoint: [ "tower", "--is-operator", "--verbose", "start" ]

monitor service

Port: 3030

Start web monitor.

---

Utility Services

These services are mostly for debugging and developing inside containers.

shell service

Run different ol and other commands inside an isolated container. This uses the production image

source service

Run make commands inside an isolated container with access to 0L source under /root/libra and Rust toolchain.

builder service

Run different ol and other make commands inside an isolated container with access to 0L source under /root/libra and Rust toolchain.

---

Restarting Nodes with Cron

In some cases when the network is having syncing issues we resort to restarting nodes on the top of the hour. Since not every node operator might be available, setting a cronjob to restart nodes seemed like a good work around.

Add the content of restart.cron to crontab -e. Make sure to update paths as necessary. It is meant to stop node at :58 and start it again on :00.

The cron output will be logged to `./cron-runs.log

---

Notes

General

• Some services like monitor expect other services like node and tower to be running first.

Miners

• Make sure to set default_node and upstream_nodes in ~/.0L/0L.toml with IPs of fullnodes. https://github.com/0LNetworkCommunity/seed-peers/blob/main/fullnode_seed_playlist.json

• TEST variable should not be included in any services other than tower Pending PR 0LNetworkCommunity/libra-legacy-v6#979

---

Todos

Docker

• Use smaller image
• Security
  • use non-root user
  • what else?

Deployment

• Create CI to auto build image