install.md

Install hsd

hsd requires Node.js v12 or higher.

Table of contents

• Verifying keys
• Building From Source (git and npm)
  • Verifying
• npm
  • Verifying
• macOS
  • Verifying
• Docker
  • Building an image
  • Running a container
  • Stopping a container

Verifying keys

Every verifying process described below will need project maintainer keys. You can get keys following Security document.

Building From Source (git and npm)

git clone --depth 1 --branch latest https://github.com/handshake-org/hsd.git
cd hsd
npm install --production
# run full node in foreground with default configuration
./bin/hsd

Note that node-gyp must be installed. See the node-gyp documentation for more information.

Verifying

Note this does not verify dependencies, they are downloaded from the npm.

cd hsd
git verify-tag latest

npm

It is not recommended to install hsd from npm's repositories but it is still possible to install with npm using a remote git repository.

$ npm install -g https://github.com/handshake-org/hsd.git

A git ref can be used to install a particular version by appending a # and the name of the git ref to the URL. For example, https://github.com/handshake-org/hsd.git#latest. It is recommended to use the latest tagged release.

If adding hsd as a dependency to a project, use the command:

$ npm install --save https://github.com/handshake-org/hsd.git

Verifying

Not supported.

macOS

hsd is available via Homebrew. This will install all required dependencies as well as unbound.

$ brew install hsd

Verifying

Not supported.

Docker

Building an image

To build a Docker image with the name hsd:<version>-<commit>, run:

$ VERSION=$(cat package.json | grep version | sed 's/.*"\([0-9]*\.[0-9]*\.[0-9]*\)".*/\1/')
$ COMMIT=$(git rev-parse --short HEAD)
$ docker build -t hsd:$VERSION-$COMMIT .

GitHub Hosted images

Baked images are available here.

docker pull ghcr.io/handshake-org/hsd:latest

Running a container

To start a container named hsd on main network with an exposed node API server, run:

$ docker run --name hsd \
    --publish 12037:12037 \
    --volume $HOME/.hsd:/root/.hsd \
    hsd:$VERSION-$COMMIT \
    --http-host 0.0.0.0 \
    --api-key=foo

To test connectivity, curl the info endpoint:

$ curl http://x:foo@localhost:12037/

Note: by default, none of the container's ports are exposed. Depending on the network used for your node, you will need to expose the correct ports for the node's various services (node http api, wallet http api, recursive name server, authoritative name server, p2p protocol, encrypted p2p protocol). The default ports can be found here. The DNS servers must also expose a UDP port. The syntax is different from TCP and can be found here.

Stopping a container

To stop a container named hsd, run:

$ docker stop hsd