sidhujag/syscoin-core

A syscoin-core docker image with support for the following platforms:

• amd64 (x86_64)
• arm64 (aarch64, armv8)

Tags

• 5.1.0, latest (5.1/alpine/Dockerfile) [multi-arch, Alpine source build]

Multi-architecture builds

The 5.1.0 and latest tags refer to the same image and support amd64 and arm64. Running docker pull automatically selects the matching image from the multi-platform manifest.

Picking the right tag

• sidhujag/syscoin-core:latest: points to the latest stable release available of Syscoin Core. Caution when using in production as blindly upgrading Syscoin Core is a risky procedure.
• sidhujag/syscoin-core:5.1.0: pins the Alpine source build to Syscoin Core v5.1.0 and sysgeth v5.1.0.

Building the 5.1.0 image

Both upstream v5.1.0 tags must exist before building. From the repository root, build one native-platform image and assign both local tags:

docker buildx build \
  --load \
  --build-arg MAKE_JOBS=8 \
  --tag sidhujag/syscoin-core:5.1.0 \
  --tag sidhujag/syscoin-core:latest \
  5.1/alpine

The two tags should resolve to the same image ID:

docker image inspect \
  sidhujag/syscoin-core:5.1.0 \
  sidhujag/syscoin-core:latest \
  --format '{{.RepoTags}} {{.Id}}'

Verify the included clients:

docker run --rm sidhujag/syscoin-core:5.1.0 syscoind -version
docker run --rm sidhujag/syscoin-core:5.1.0 sysgeth version

To publish a multi-platform image after docker login, create and select a Buildx builder once:

docker buildx create --name syscoin-multiarch --use
docker buildx inspect --bootstrap

Then build and push both tags:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg MAKE_JOBS=8 \
  --tag sidhujag/syscoin-core:5.1.0 \
  --tag sidhujag/syscoin-core:latest \
  --push \
  5.1/alpine

Do not combine --load with the multi-platform build; --push publishes its manifest and platform images directly.

What is Syscoin Core?

Syscoin Core is a reference client that implements the Syscoin protocol for remote procedure call (RPC) use. It is also the second Syscoin client in the network's history. Learn more about Syscoin Core on the Syscoin Developer Reference docs.

Usage

How to use this image

This image contains syscoind, syscoin-cli, and sysgeth. It behaves like a binary, so options passed directly to the image are forwarded to syscoind:

❯ docker run --rm -it sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1 \
  -rpcallowip=172.17.0.0/16 \
  -rpcauth='foo:7d9ba5ae63c3d4dc30583ff4fe65a67e$9e3634e81c11659e3de036d0bf88f89cd169c1039e6e09607562d54765c649cc'

Note: learn more about how -rpcauth works for remote authentication.

By default, syscoind runs as user syscoin with its default data directory (~/.syscoin). To customize where Syscoin Core stores its data, use the SYSCOIN_DATA environment variable. The directory is created with the correct permissions and passed to syscoind.

❯ docker run --env SYSCOIN_DATA=/var/lib/syscoin-core --rm -it sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1

You can also mount a directory in a volume under /home/syscoin/.syscoin in case you want to access it on the host:

❯ docker run -v ${PWD}/data:/home/syscoin/.syscoin -it --rm sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1

You can optionally create a service using docker-compose:

syscoin-core:
  image: sidhujag/syscoin-core
  command:
    -printtoconsole
    -regtest=1

Using RPC to interact with the daemon

There are two communications methods to interact with a running Syscoin Core daemon.

The first one is using a cookie-based local authentication. It doesn't require any special authentication information as running a process locally under the same user that was used to launch the Syscoin Core daemon allows it to read the cookie file previously generated by the daemon for clients. The downside of this method is that it requires local machine access.

The second option is making a remote procedure call using a username and password combination. This has the advantage of not requiring local machine access, but in order to keep your credentials safe you should use the newer rpcauth authentication mechanism.

Using cookie-based local authentication

Start by launch the Syscoin Core daemon:

❯ docker run --rm --name syscoin-server -it sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1

Then, inside the running syscoin-server container, locally execute the query to the daemon using syscoin-cli:

❯ docker exec --user syscoin syscoin-server syscoin-cli -regtest getmininginfo

{
  "blocks": 0,
  "currentblocksize": 0,
  "currentblockweight": 0,
  "currentblocktx": 0,
  "difficulty": 4.656542373906925e-10,
  "errors": "",
  "networkhashps": 0,
  "pooledtx": 0,
  "chain": "regtest"
}

In the background, syscoin-cli read the information automatically from /home/syscoin/.syscoin/regtest/.cookie. In production, the path would not contain the regtest part.

Using rpcauth for remote authentication

Before setting up remote authentication, you will need to generate the rpcauth line that will hold the credentials for the Syscoind Core daemon. You can either do this yourself by constructing the line with the format <user>:<salt>$<hash> or use the official rpcauth.py script to generate this line for you, including a random password that is printed to the console.

Note: This is a Python 3 script. use [...] | python3 - <username> when executing on macOS.

Example:

❯ curl -sSL https://raw.githubusercontent.com/syscoin/syscoin/master/share/rpcauth/rpcauth.py | python - <username>

String to be appended to syscoin.conf:
rpcauth=foo:7d9ba5ae63c3d4dc30583ff4fe65a67e$9e3634e81c11659e3de036d0bf88f89cd169c1039e6e09607562d54765c649cc
Your password:
qDDZdeQ5vw9XXFeVnXT4PZ--tGN2xNjjR4nrtyszZx0=

Note that for each run, even if the username remains the same, the output will be always different as a new salt and password are generated.

Now that you have your credentials, you need to start the Syscoin Core daemon with the -rpcauth option. Alternatively, you could append the line to a syscoin.conf file and mount it on the container.

Let's opt for the Docker way:

❯ docker run --rm --name syscoin-server -it sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1 \
  -rpcallowip=172.17.0.0/16 \
  -rpcauth='foo:7d9ba5ae63c3d4dc30583ff4fe65a67e$9e3634e81c11659e3de036d0bf88f89cd169c1039e6e09607562d54765c649cc'

Two important notes:

1. Some shells require escaping the rpcauth line (e.g. zsh), as shown above.
2. It is now perfectly fine to pass the rpcauth line as a command line argument. Unlike -rpcpassword, the content is hashed so even if the arguments would be exposed, they would not allow the attacker to get the actual password.

You can now connect via syscoin-cli or any other compatible client. You will still have to define a username and password when connecting to the Syscoin Core RPC server.

To avoid any confusion about whether or not a remote call is being made, let's spin up another container to execute syscoin-cli and connect it via the Docker network using the password generated above:

❯ docker run -it --link syscoin-server --rm sidhujag/syscoin-core \
  syscoin-cli \
  -rpcconnect=syscoin-server \
  -regtest \
  -rpcuser=foo\
  -stdinrpcpass \
  getbalance

Enter the password qDDZdeQ5vw9XXFeVnXT4PZ--tGN2xNjjR4nrtyszZx0= and hit enter:

0.00000000

Note: under Syscoin Core < 0.16, use -rpcpassword="qDDZdeQ5vw9XXFeVnXT4PZ--tGN2xNjjR4nrtyszZx0=" instead of -stdinrpcpass.

Done!

Exposing Ports

Depending on the network (mode) the Syscoin Core daemon is running as well as the chosen runtime flags, several default ports may be available for mapping.

Ports can be exposed by mapping all of the available ones (using -P and based on what EXPOSE documents) or individually by adding -p. This mode allows assigning a dynamic port on the host (-p <port>) or assigning a fixed port -p <hostPort>:<containerPort>.

Example for running a node in regtest mode mapping JSON-RPC/REST (38370) and P2P (18444) ports:

docker run --rm -it \
  -p 38370:38370 \
  -p 18444:18444 \
  sidhujag/syscoin-core \
  -printtoconsole \
  -regtest=1 \
  -rpcallowip=172.17.0.0/16 \
  -rpcbind=0.0.0.0 \
  -rpcauth='foo:7d9ba5ae63c3d4dc30583ff4fe65a67e$9e3634e81c11659e3de036d0bf88f89cd169c1039e6e09607562d54765c649cc'

To test that mapping worked, you can send a JSON-RPC curl request to the host port:

curl --data-binary '{"jsonrpc":"1.0","id":"1","method":"getnetworkinfo","params":[]}' http://foo:qDDZdeQ5vw9XXFeVnXT4PZ--tGN2xNjjR4nrtyszZx0=@127.0.0.1:38370/

Mainnet

• JSON-RPC/REST: 8370
• P2P: 8369

Testnet

• JSON-RPC/REST: 18370
• P2P: 18369

Regtest

• JSON-RPC/REST: 38370
• P2P: 18444

Signet

• JSON-RPC/REST: 18470
• P2P: 38333

Docker

This image is officially supported on Docker version 17.09, with support for older versions provided on a best-effort basis.

License

License information for the software contained in this image.

License information for the sidhujag/syscoin-core Docker project.