Skip to content

Commit

Permalink
Merge PR handshake-org#663 from 'nodech/release-doc'
Browse files Browse the repository at this point in the history
  • Loading branch information
@nodech
nodech committed Apr 7, 2022
2 parents 107ed2b + a0aa531 commit 084b3f0
Show file tree
Hide file tree
Showing 7 changed files with 490 additions and 97 deletions.
101 changes: 5 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,97 +5,12 @@

__HSD__ is an implementation of the [Handshake][handshake] Protocol.

## Install

`hsd` requires Node.js v12 or higher


### Building From Source

```
$ git clone https://github.com/handshake-org/hsd.git
$ cd hsd
$ npm install --production
$ ./bin/hsd
```

Note that `node-gyp` must be installed. See the
[node-gyp](https://github.com/nodejs/node-gyp) documentation for more
information.

### Docker
#### Building an image

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

```bash
$ 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 .
```

#### Running a container

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

```bash
$ docker run --name hsd -p 14037:14037 hsd:$VERSION-$COMMIT \
--network regtest \
--http-host 0.0.0.0 \
--api-key=foo
```

To test connectivity, curl the info endpoint:
```bash
$ curl http://x:foo@localhost:14037/
```

>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](./lib/protocol/networks.js). The DNS
servers must also expose a UDP port. The syntax is different from TCP and can
be found [here](https://docs.docker.com/config/containers/container-networking/#published-ports).

#### Stopping a container

To stop a container named `hsd`, run:

```bash
$ docker stop hsd
```

### 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#v3.0.1`. It is recommended
to use the [latest tagged release](https://github.com/handshake-org/hsd/releases).

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

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

### macOS

`hsd` is available via [Homebrew](https://brew.sh). This will
install all required dependencies as well as `unbound`.
## Documentation

```
$ brew install hsd
```
- [Install guide](./docs/install.md)
- Documentation Site: [https://hsd-dev.org](https://hsd-dev.org)
- API Docs: [https://hsd-dev.org/api-docs](https://hsd-dev.org/api-docs)
- JSDoc: [https://hsd-dev.org/hsd](https://hsd-dev.org/hsd)

## CLI

Expand All @@ -117,12 +32,6 @@ The shortcuts `hsd-rpc` and `hsw-rpc` are available if you install hs-client glo
$ npm install -g hs-client
```

## Documentation

- Documentation Site: [https://hsd-dev.org](https://hsd-dev.org)
- API Docs: [https://hsd-dev.org/api-docs](https://hsd-dev.org/api-docs)
- JSDoc: [https://hsd-dev.org/hsd](https://hsd-dev.org/hsd)

## Contributing

Handshake is a community project, we welcome contributions of all kinds from
Expand Down
16 changes: 16 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
HSD
===

## Links
- [Install](./install.md)
- [Configuration](https://hsd-dev.org/guides/config.html)
- [Release schedule](./release-schedule.md)
- [Release process](./release-process.md)
- [Release files](./release-files.md)

## External Links
- [Documentation repository](https://github.com/handshake-org/handshake-org.github.io)
- [Guides](https://hsd-dev.org)
- [API Doc](https://hsd-dev.org/api-docs/)
- [Code generated docs](https://hsd-dev.org/hsd)
- [Paper](https://hsd-dev.org/files/handshake.txt)
130 changes: 130 additions & 0 deletions docs/install.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
Install `hsd`
=============

`hsd` requires Node.js v12 or higher.

Table of contents
-----------------

<!-- markdown-toc -i install.md -->

<!-- toc -->

- [Verifying keys](#verifying-keys)
- [Building From Source (git and npm)](#building-from-source-git-and-npm)
* [Verifying](#verifying)
- [npm](#npm)
* [Verifying](#verifying-1)
- [macOS](#macos)
* [Verifying](#verifying-2)
- [Docker](#docker)
* [Building an image](#building-an-image)
* [Running a container](#running-a-container)
* [Stopping a container](#stopping-a-container)

<!-- tocstop -->

## Verifying keys
Every verifying process described below will need project maintainer
keys. You can get keys following [Security](../SECURITY.md) 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](https://github.com/nodejs/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](https://github.com/handshake-org/hsd/releases).

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](https://formulae.brew.sh/formula/hsd). 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:

```bash
$ 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 .
```

### Running a container

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

```bash
$ docker run --name hsd -p 12037:12037 hsd:$VERSION-$COMMIT \
--http-host 0.0.0.0 \
--api-key=foo
```

To test connectivity, curl the info endpoint:
```bash
$ curl http://x:foo@localhost:14037/
```

> 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](https://hsd-dev.org/api-docs/#introduction). The DNS
servers must also expose a UDP port. The syntax is different from TCP and can
be found [here](https://docs.docker.com/config/containers/container-networking/#published-ports).

### Stopping a container

To stop a container named `hsd`, run:

```bash
$ docker stop hsd
```

128 changes: 128 additions & 0 deletions docs/release-files.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
Releasing hsd
=============

This document contains information about bundling, signing and
distributing the files.

`hsd` is distributed through several platforms: `github`, `npm`, `brew`.

<!-- markdown-toc -i release-files.md -->

<!-- toc -->

- [Deploying to github (tag)](#deploying-to-github-tag)
* [Major, minor and patches](#major-minor-and-patches)
+ [Major](#major)
+ [Minor, Patch](#minor-patch)
- [Deploying to npm](#deploying-to-npm)
* [Deploying latest version, minor and patches included](#deploying-latest-version-minor-and-patches-included)
* [Deploying support versions (previous and life-support)](#deploying-support-versions-previous-and-life-support)
- [Deploying to homebrew](#deploying-to-homebrew)
- [Deploying to handshake.org](#deploying-to-handshakeorg)
* [Building tarball](#building-tarball)
* [Signing and upload](#signing-and-upload)

<!-- tocstop -->

## Deploying to github (tag)

This does not need many additional actions as we use github as our primary
git platform. Tags MUST to be signed.

### Major, minor and patches
After you are [ready](./release-process.md) to publish files (for example
`v4.0.0`)
- `git checkout 4.x` - switch to proper branch `4.x`.
- `git tag -s v4.0.0` - tag and sign the release.
- `git push origin v4.0.0` - publish the tag. (origin is the main repo)
- Add release to `github` on the `releases` page.

#### Major
When updating major version, we need to move forward all tags.
- `git checkout v4.0.0` - latest version.
- `git tag --force -s latest` - Tag `v4.0.0` as `latest`.
- `git checkout v3.x.x` - latest `v3` version.
- `git tag --force -s previous` - Tag latest `v3` as `previous`.
- `git checkout v2.x.x` - latest `v2` version.
- `git tag --force -s life-support` - Tag latest `v2` as `life-support`.

#### Minor, Patch
If we are updating minor/patch versions, regardless of the `major`, we
need to update tag related to it. E.g. `latest` minor/patch release will
retag the `latest`. If `previous` major version got minor/patch update
it will update `previous` tag. We will have full example with `major`:
- `git checkout v4.x.x` - Checkout the `latest` tagged version we just tagged
with minor/patch.
- `git tag --force -s latest` - Update `latest` tag with the major/minor
update.

## Deploying to npm
Maintainer needs access rights to the npm repository. Releasing
on npm by default tags the release with `latest`, so releasing latest
and supporting older versions is different.

NOTE: You can use `npm publish --dry-run` to see the details before actual
release.

### Deploying latest version, minor and patches included
Major, minor and patch of the latest version deployment (for example v4.1.0):
- `git checkout v4.1.0` - switch to the tag containing `4.1.0` updates.
- `npm publish` - this is will be tagged as `latest`.

NOTE: `package.json` should have been updated in `v4.1.0` tag to `4.1.0`.

### Deploying support versions (previous and life-support)
Older versions can have additional tags for `previous` and `life-support`:
- `git checkout v3.1.0` - switch to the tag for the `previous` version.
- `npm publish --tag previous` - update appropriate npm tag for the release.
or
- `git checkout v2.4.1` - switch to the tag for the `life-support` version.
- `npm publish --tag life-support` - update appropriate npm tag for the
release.

NOTE: `package.json` should have been updated in `v3.1.0` tag to `3.1.0`.

## Deploying to homebrew
To deploy to the popular MacOS package manager [brew][homebrew], you will
need to create Pull request to the [Hombrew Core repository][homebrew-repo].
Formula for the `hsd` can be found at `homebrew-core/Formula/hsd.rb`
- Update `homebrew-core/Formula/hsd.rb`. (e.g. [hsd 3.0.1][homebrew-update])
- You can check the steps when formula was introduced
[hsd formula][homebrew-new-formula] or review the
[Guidelines][homebrew-guidelines].
- Additionally double check if `nodejs` version needs update.

## Deploying to handshake.org
Handshake.org website is hosted via github and can be found at
[handshake-org/handshake-web][handshake-web]. Website contains easy to install
tarball with signatures from the maintainers.

### Building tarball
In order to build tarball, you will need [bpkg][bpkg] tool.
(We'll use `v3.0.1` as an example)
- Checkout to the correct version you want to release.
- Remove `node_modules/`.
- Install deps using: `npm ci --ignore-scripts`.
- Generate tarball: `bpkg --verbose --release --output=../hsd-3.0.1.tar.gz .`
- You can see the tarball at `../hsd-3.0.1.tar.gz`
NOTE: Everything in the existing directory of `hsd` will be bundled, so make
sure there are no external files there. (Check `git status` there's nothing to
commit and working tree is clean)

### Signing and upload
Now that we have tarball, we can sign and upload. Next step is to sign
and create PR with the relevant updates to the `download/index.html` and
`files/` directory.
- Generate signature (default key):
`gpg --detach-sign --armor project-version.tar.gz`
- Move `.asc` and `.tar.gz` tarball files to `files/` directory and commit.
- Update `download/index.html` with new links.
- Create PR to the main repository.

[homebrew]: https://brew.sh/
[homebrew-repo]: https://github.com/Homebrew/homebrew-core
[homebrew-new-formula]: https://github.com/Homebrew/homebrew-core/pull/51014
[homebrew-update]: https://github.com/Homebrew/homebrew-core/pull/87779/files
[homebrew-guidelines]: https://github.com/Homebrew/homebrew-core/blob/master/CONTRIBUTING.md
[handshake-web]: https://github.com/handshake-org/handshake-web/
[bpkg]: https://github.com/chjj/bpkg
Loading

0 comments on commit 084b3f0

Please sign in to comment.