Python implementation of the SyncLink Server. 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 Server 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 Server 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 develpment on your local system, however also an absolutely valid setup for production.
The SyncLink Server 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 Server is listening for new connections |
| port | 8000 | No | The port where the SyncLink Server is listening for new connections |
| eth_api_address | http://localhost:5051 | No | The URL to your Beacon node API (usually running on the same host) |
| config | config.yaml | No | Path to a yaml config file |
By default the SyncLink Server attempts to read the configuration from config.yaml. The path to this file can however explicitely 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: 8000
eth_api_address: http://localhost:5051
You can also configure the SyncLink Server 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 Server 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".
However, this is just a demo because the SyncLink Server currently has no arguments that require a list!
If you have accidently 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 Server with Docker but it is also possible to run the SyncLink Server 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 Server Docker Image (stereum/synclink-server) 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 Server on python:3.10-slim$version- specific release (e.g.:v0.0.1) of the SyncLink Server on python:3.10-slim
docker run --name synclink-server --rm -it -p "8000:8000" -e SYLI_ETH_API_ADDRESS="$YOUR_NODE_API_ADDRESS" stereum/synclink-server
Important
Change $YOUR_NODE_API_ADDRESS to the URL of your Beacon node API (e.g: http://localhost:5051).
After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:8000/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_NODE_API_ADDRESS"
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py --addr="$YOUR_NODE_API_ADDRESS"
Important
Change $YOUR_NODE_API_ADDRESS to the URL of your Beacon node API (e.g: http://localhost:5051).
After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:8000/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 Server please follow this 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 this 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 synclink@synclink.io. We are happy to get your feedback!
Below you'll find a few practical examples how to start and stop the SyncLink Server with docker run or docker compose commands.
Keep in mind that this examples should just give you a hint - it is absolutely your freedom of choice how to run the SyncLink Server!
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_NODE_API_ADDRESS to the URL of your Beacon node API (e.g: http://localhost:5051).
After the app is started you can visit the API docs (depending on your config) by default at http://127.0.0.1:8000/docs.
Start container from stereum/synclink-server image with run command and config file
Copy config.yaml.example to config.yaml and configure as needed, then:
docker rm --force synclink-server
docker run -d --name synclink-server --rm -it -p 8000:8000 -v $(pwd)/config.yaml:/opt/synclink-server/config.yaml stereum/synclink-server
docker logs -f synclink-server
docker stop synclink-server
Start container from stereum/synclink-server image with run command and command line arguments
docker rm --force synclink-server
docker run -d --name synclink-server --rm -it -p 8000:8000 stereum/synclink-server python main.py --eth_api_address="$YOUR_NODE_API_ADDRESS"
docker logs -f synclink-server
docker stop synclink-server
Start container from stereum/synclink-server image with run command and environment variables
docker rm --force synclink-server
docker run -d --name synclink-server --rm -it -p "8000:8000" -e SYLI_ETH_API_ADDRESS="$YOUR_NODE_API_ADDRESS" stereum/synclink-server
docker logs -f synclink-server
docker stop synclink-server
Start container from stereum/synclink-server image with compose command
Copy docker-compose.yaml.example to docker-compose.yaml and configure as needed, then:
docker rm --force synclink-server
docker-compose pull
docker-compose --project-name synclink-server up -d
docker logs -f synclink-server
docker-compose --project-name synclink-server down
Start container from dev/synclink-server 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-server .
docker rm --force dev-synclink-server
docker run -d --name dev-synclink-server --rm -it -p 8000:8000 -v $(pwd)/config.yaml:/opt/synclink-server/config.yaml dev/synclink-server
docker logs -f dev-synclink-server
docker stop dev-synclink-server
Start container from dev/synclink-server build-image with run command and command line arguments
docker build --tag dev/synclink-server .
docker rm --force dev-synclink-server
docker run -d --name dev-synclink-server --rm -it -p 8000:8000 dev/synclink-server python main.py --eth_api_address="$YOUR_NODE_API_ADDRESS"
docker logs -f dev-synclink-server
docker stop dev-synclink-server
Start container from dev/synclink-server build-image with run command and environment variables
docker build --tag dev/synclink-server .
docker rm --force dev-synclink-server
docker run -d --name dev-synclink-server --rm -it -p "8000:8000" -e SYLI_ETH_API_ADDRESS="$YOUR_NODE_API_ADDRESS" dev/synclink-server
docker logs -f dev-synclink-server
docker stop dev-synclink-server
Copy docker-compose.dev.yaml.example to docker-compose.dev.yaml and configure as needed, then:
docker rm --force dev-synclink-server
docker-compose --project-name dev-synclink-server -f docker-compose.dev.yaml up -d
docker logs -f dev-synclink-server
docker-compose --project-name dev-synclink-server down