Skip to content

Sync your Ethereum nodes with eachother with SyncLink (Client)

License

Notifications You must be signed in to change notification settings

stereum-dev/synclink-client

Repository files navigation

SyncLink Client

GitHub - SyncLink - ReadMe


IE Discord Twitter YouTube Gmail

Build Status Latest Release GitHub Discord GitPOAPs

Python implementation of the SyncLink Client. See the Changelog for details of the latest releases and upcoming changes.

WARNING

CURRENTLY IN DEVELOPMENT - DO NOT USE IN PRODUCTION!

You can use the SyncLink Client as described in this document however during development we continue implementing changes that could (and very likely will) make some or all of the described operations and tasks below obsolete.

Table of Contents

Supported clients

Client Support
Checkpointz âś…
Lighthouse âś…
Lodestar âś…
Nimbus âś…
Prysm âś…
Teku âś…

Usage

There are multiple ways you can configure and run the SyncLink Client application. While the recommended setup for production environments is Docker, it is also possible to run the app directly from source with Python, which is mostly preferred for development on your local system, however also an absolutely valid setup for production.

Configuration

The SyncLink Client options must be configured either thru a yaml config file, command line arguments or environment variables.

Options

Name Default Required Description
addr 0.0.0.0 No The IP address or domain where the SyncLink Client is listening for new connections
port 9000 No The port where the SyncLink Client is listening for new connections
nodes [http://localhost:8000] No List of URLs to your SyncLink Server Nodes
config config.yaml No Path to a yaml config file

Config file

By default the SyncLink Client attempts to read the configuration from config.yaml. The path to this file can however explicitly specified by command line arguments or environment variables. The configuration management also supports a hierarchical config structure, which means you can optionally add the "config" option within a config file to load additional settings from a separate config file.

Example config.yaml (see config.yaml.example):

port: 9000
nodes:
  - http://localhost:8000
  - http://host.docker.internal:8000

Command line arguments

You can also configure the SyncLink Client options on the command line. Command line arguments will overwrite all identical options that are already defined in the config file and you can of course set the path to the config file itself.

By default command line arguments must be prefixed with "--" and always lowercase. For example, to specify addr as command line argument:

python main.py --addr="127.0.0.1"

In most cases it is also possible to use just a shortcut, run python main.py -h for details.

Environment variables

At last you can configure the SyncLink Client options by environment variables. They are especially useful with the Docker Image and have the highest priority in the configuration tree.

Environment variables must be prefixed with "SYLI_" and always UPPERCASE. For example, to specify addr as environment variable:

export SYLI_ADDR="127.0.0.1"
python main.py

will be converted to python main.py --addr "127.0.0.1".

For lists, the environment variables need additionally suffixed with a number, e.g.:

export SYLI_NODE_1="10.0.0.1"
export SYLI_NODE_2="10.0.0.2"
python main.py

will be converted to python main.py --node "10.0.0.1" --node "10.0.0.2".

If you have accidentally specified an environment variable that is not supported (see options), you need to unset the variable to avoid an error. For example:

export SYLI_BLA="12345"
python main.py

will be converted to python main.py --bla "12345".

This will of course result in the error main.py: error: unrecognized arguments: --bla 12345.

Therefore, you'd have to remove the environment variable:

unset SYLI_BLA

Getting started

The recommended setup for production environments is to run the SyncLink Client with Docker but it is also possible to run the SyncLink Client directly from source with Python. Make sure you've read the configuration section and then you're good to go.

Run with Docker

  1. If not already done, install Docker on your OS.
  2. Pull the SyncLink Client Docker Image (stereum/synclink-client) from Docker Hub and follow the quick start with Docker or one of the more advanced Docker examples on bottom.

Images

  • latest - latest release of the SyncLink Client on python:3.10-slim
  • $version - specific release (e.g.: v0.0.1) of the SyncLink Client on python:3.10-slim

Quick start with Docker

docker run --name synclink-client --rm -it -p "9000:9000" -e SYLI_NODE_1="$YOUR_SYNCLINK_SERVER_URL" stereum/synclink-client

Important

Change $YOUR_SYNCLINK_SERVER_URL to the URL of your SyncLink Server API (e.g: http://localhost:8000 or http://host.docker.internal:8000 if the server is running in a Docker container on your local machine).

After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:9000/docs.

If you're done you can stop the Docker container by typing CTRL+C in your active terminal.

Run from source

  1. Download a release from the releases page (or clone the GitHub repository).
  2. Refer to the official Python docs to install Python >= 3.10 on your OS.
  3. On Debian or Ubuntu run apt install pythonX.Y-venv to install venv. (Replace X.Y with the python MAJOR and MINOR version retrieved by python -V)
  4. Extract the release (or continue directly with step #5 if you just cloned the GitHub repository).
  5. Follow the quick start from source on Windows or Linux and macOS examples.

Quick start from source on Windows

python -m venv .venv
".venv/scripts/activate.bat"
pip install -r requirements.txt
python main.py --addr="$YOUR_SYNCLINK_SERVER_URL"

Quick start from source on Linux and macOS

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py --addr="$YOUR_SYNCLINK_SERVER_URL"

Important

Change $YOUR_SYNCLINK_SERVER_URL to the URL of your SyncLink Server API (e.g: http://localhost:8000 or http://host.docker.internal:8000 if the server is running in a Docker container on your local machine).

After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:9000/docs.

If you're done you can stop the Python process and deactivate the virtual environment by typing the following in your active terminal:

CTRL+C
deactivate

Contributing

Contributions are greatly appreciated and pull requests will be reviewed/merged ASAP!

If you're interested in improving the SyncLink Client please follow these steps:

  1. Fork the project
  2. Create your feature branch:
    • git checkout -b feat/new-feature
  3. Commit your changes:
    • git commit -m "feat(optional): new feature"
  4. Push the branch: -git push origin feat/new-feature
  5. Open a pull request

Note: To test your changes in a local Docker container see the Development Container Examples.

Unit Testing and Linting

All pull requests running thru automated tests. It is recommended to run these tests locally before you open a pull request.

  • Setup your local development environment, thus you're able to run from source
  • Execute pytest to run Unit Tests (where no errors as result means passed)
  • Execute flake8 to run Lint Tests (where 0 as result means passed)

Contact

Discord

To get in touch just join the Stereum Discord server and leave a message in one of the public channels or drop us an email to synclink@synclink.io. We are happy to get your feedback!

Docker Examples

Below you'll find a few practical examples of how to start and stop the SyncLink Client with docker run or docker compose commands. Keep in mind that these examples should just give you a hint - it is absolutely your freedom of choice how to run the SyncLink Client! For more details regarding Docker just visit https://docs.docker.com.

Generic description of the used Docker commands

Command Description
docker rm Remove one or more containers
docker run Run a command in a new container
docker logs Fetch the logs of a container
docker stop Stop one or more running containers
docker compose up Create and start containers
docker compose pull Pull service images
docker compose down Stop and remove containers, networks

See also https://docs.docker.com/engine/reference/commandline

Important

Change $YOUR_SYNCLINK_SERVER_URL to the URL of your SyncLink Server API (e.g: http://localhost:8000 or http://host.docker.internal:8000 if the server is running in a Docker container on your local machine).

After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:9000/docs.

Production Container Examples

Start container from stereum/synclink-client image with run command and config file

Copy config.yaml.example to config.yaml and configure as needed, then:

docker rm --force synclink-client
docker run -d --name synclink-client --rm -it -p 9000:9000 -v $(pwd)/config.yaml:/opt/synclink-client/config.yaml stereum/synclink-client
docker logs -f synclink-client
docker stop synclink-client

Start container from stereum/synclink-client image with run command and command line arguments

docker rm --force synclink-client
docker run -d --name synclink-client --rm -it -p 9000:9000 stereum/synclink-client python main.py --node="$YOUR_SYNCLINK_SERVER_URL"
docker logs -f synclink-client
docker stop synclink-client

Start container from stereum/synclink-client image with run command and environment variables

docker rm --force synclink-client
docker run -d --name synclink-client --rm -it -p "9000:9000" -e SYLI_NODE_1="$YOUR_SYNCLINK_SERVER_URL" stereum/synclink-client
docker logs -f synclink-client
docker stop synclink-client

Start container from stereum/synclink-client image with compose command

Copy docker-compose.yaml.example to docker-compose.yaml and configure as needed, then:

docker rm --force synclink-client
docker-compose pull
docker-compose --project-name synclink-client up -d
docker logs -f synclink-client
docker-compose --project-name synclink-client down

Development Container Examples

Start container from dev/synclink-client build-image with run command and config file

Copy config.yaml.example to config.yaml and configure as needed, then:

docker build --tag dev/synclink-client .
docker rm --force dev-synclink-client
docker run -d --name dev-synclink-client --rm -it -p 9000:9000 -v $(pwd)/config.yaml:/opt/synclink-client/config.yaml dev/synclink-client
docker logs -f dev-synclink-client
docker stop dev-synclink-client

Start container from dev/synclink-client build-image with run command and command line arguments

docker build --tag dev/synclink-client .
docker rm --force dev-synclink-client
docker run -d --name dev-synclink-client --rm -it -p 9000:9000 dev/synclink-client python main.py --node="$YOUR_SYNCLINK_SERVER_URL"
docker logs -f dev-synclink-client
docker stop dev-synclink-client

Start container from dev/synclink-client build-image with run command and environment variables

docker build --tag dev/synclink-client .
docker rm --force dev-synclink-client
docker run -d --name dev-synclink-client --rm -it -p "9000:9000" -e SYLI_NODE_1="$YOUR_SYNCLINK_SERVER_URL" dev/synclink-client
docker logs -f dev-synclink-client
docker stop dev-synclink-client

Start container from dev/synclink-client build-image with compose command

Copy docker-compose.dev.yaml.example to docker-compose.dev.yaml and configure as needed, then:

docker rm --force dev-synclink-client
docker-compose --project-name dev-synclink-client -f docker-compose.dev.yaml up -d
docker logs -f dev-synclink-client
docker-compose --project-name dev-synclink-client down