Python implementation of the SyncLink Client. See the Changelog for details of the latest releases and upcoming changes.
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.
| Client | Support |
|---|---|
| Checkpointz | âś… |
| Lighthouse | âś… |
| Lodestar | âś… |
| Nimbus | âś… |
| Prysm | âś… |
| Teku | âś… |
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.
The SyncLink Client options must be configured either thru a yaml config file, command line arguments or environment variables.
| 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 |
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
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 -hfor details.
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
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.
- If not already done, install Docker on your OS.
- 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.
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
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.
- Download a release from the releases page (or clone the GitHub repository).
- Refer to the official Python docs to install Python >= 3.10 on your OS.
- On Debian or Ubuntu run
apt install pythonX.Y-venvto install venv. (ReplaceX.Ywith the python MAJOR and MINOR version retrieved bypython -V) - Extract the release (or continue directly with step #5 if you just cloned the GitHub repository).
- Follow the quick start from source on Windows or Linux and macOS examples.
python -m venv .venv
".venv/scripts/activate.bat"
pip install -r requirements.txt
python main.py --addr="$YOUR_SYNCLINK_SERVER_URL"
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
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:
- Fork the project
- Create your feature branch:
git checkout -b feat/new-feature
- Commit your changes:
git commit -m "feat(optional): new feature"
- Push the branch: -
git push origin feat/new-feature - Open a pull request
Note: To test your changes in a local Docker container see the Development Container Examples.
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
pytestto run Unit Tests (where no errors as result means passed) - Execute
flake8to run Lint Tests (where 0 as result means passed)
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 [email protected]. We are happy to get your feedback!
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.
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
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
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