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.

• Supported clients

• Usage
  • Configuration
    • Options
    • Config file
    • Command line arguments
    • Environment variables
  • Getting Started
    • Run with Docker
      • Images
      • Quick start with Docker
    • Run from source
      • Quick start from source on Windows
      • Quick start from source on Linux and macOS

• Contributing
  • Unit Testing and Linting

• Contact

• Docker Examples
  • Production Container Examples
    • Start container from image with "run" command and "config file"
    • Start container from image with "run" command and "command line arguments"
    • Start container from image with "run" command and "environment variables"
    • Start container from image with "compose" command
  • Development Container Examples
    • Start container from build-image with "run" command and "config file"
    • Start container from build-image with "run" command and "command line arguments"
    • Start container from build-image with "run" command and "environment variables"
    • Start container from build-image with "compose" command

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.

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: 9500
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 -h for 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.

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.

• 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 "9500:9500" -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:9500/docs.

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

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.

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:9500/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:

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.

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)

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

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:9500/docs.

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 9500:9500 -v $(pwd)/config.yaml:/opt/synclink-client/config.yaml stereum/synclink-client
docker logs -f synclink-client
docker stop synclink-client

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

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

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

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 9500:9500 -v $(pwd)/config.yaml:/opt/synclink-client/config.yaml dev/synclink-client
docker logs -f dev-synclink-client
docker stop dev-synclink-client

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

docker build --tag dev/synclink-client .
docker rm --force dev-synclink-client
docker run -d --name dev-synclink-client --rm -it -p "9500:9500" -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