From fa275d838002526e9222fdb1c93b041cec956bf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emanuel=20Tesa=C5=99?= Date: Mon, 27 Nov 2023 08:45:00 +0100 Subject: [PATCH] Document release process --- packages/api/README.md | 40 +++++++++++++++++++++-------- packages/pusher/README.md | 54 ++++++++++++++++++++++++--------------- 2 files changed, 64 insertions(+), 30 deletions(-) diff --git a/packages/api/README.md b/packages/api/README.md index 5d6ccda1..45db4cb9 100644 --- a/packages/api/README.md +++ b/packages/api/README.md @@ -13,6 +13,16 @@ the data in memory and provides endpoints to push and retrieve beacon data. 3. `pnpm run dev` - To start the API server. The port number can be configured by `DEV_SERVER_PORT` environment variable. +### Docker instructions + +You can use shorthands from package.json. To understand how the docker image is built, read the +[Dockerfile](../../Dockerfile). + +```sh +pnpm run docker:build +pnpm run docker:run +``` + ### Testing To run the tests: @@ -211,6 +221,26 @@ The API provides the following endpoints: - Returns all Airnode addresses for which there is signed data. It is possible that this data cannot be shown by the delayed endpoints (in case the data is too fresh and there is not an older alternative). +## Versioning and release + +Signed API uses [semantic versioning](https://semver.org/). The version is specified in the `package.json` file. The +package is not published to NPM, but instead dockerized and published to Docker Hub. The image is called +[api3/signed-api](https://hub.docker.com/r/api3/signed-api). + +To release a new version: + +1. `git checkout main` - Always version from `main` branch. Also, ensure that the working directory is clean (has no + uncommitted changes). +2. `cd packages/api` - Change directory to the API package. +3. `pnpm version [major|minor|patch]` - Choose the right version bump. This will bump the version, create a git tag and + commit it. +4. `pnpm run docker:build` - Build the docker image with tag `api3/signed-api:latest`. +5. `docker tag api3/signed-api:latest api3/signed-api:` - Tag the image with the version. Replace the + `` with the version you just bumped (copy it from `package.json`). +6. `docker push api3/signed-api:latest && docker push api3/signed-api:` - Push the image upstream. + Both the latest and the versioned tag should be published. +7. `git push --follow-tags` - Push the tagged commit upstream. + ## Deployment To deploy signed API on AWS you can use a CloudFormation template in the `deployment` folder. You need to specify the @@ -247,16 +277,6 @@ As of now, the docker image is not published anywhere. You need to build it loca docker build --target api --tag api3/signed-api:latest ../../ ``` -### Development only docker instructions - -You can use shorthands from package.json. To understand how the docker image is built, read the -[Dockerfile](../../Dockerfile). - -```sh -pnpm run docker:build -pnpm run docker:run -``` - ### Examples Here are some examples of how to use the API with `curl`. Note, the port may differ based on the configuration. diff --git a/packages/pusher/README.md b/packages/pusher/README.md index 4b7e39d3..7c10cf7f 100644 --- a/packages/pusher/README.md +++ b/packages/pusher/README.md @@ -47,6 +47,16 @@ pnpm run test schema LOGGER_ENABLED=true pnpm run test ``` +### Docker instructions + +You can use shorthands from package.json. To understand how the docker image is built, read the +[Dockerfile](../../Dockerfile). + +```sh +pnpm run docker:build +pnpm run docker:run +``` + ## Configuration Pusher can be configured via a combination of [environment variables](#environment-variables) and @@ -333,21 +343,41 @@ An identifier of the deployment stage. This is used to distinguish between diffe `dev`, `staging` or `production`. The stage value can have 256 characters at maximum and can only include lowercase alphanumeric characters and hyphens. +## Versioning and release + +Pusher uses [semantic versioning](https://semver.org/). The version is specified in the `package.json` file. The package +is not published to NPM, but instead dockerized and published to Docker Hub. The image is called +[api3/pusher](https://hub.docker.com/r/api3/pusher). + +To release a new version: + +1. `git checkout main` - Always version from `main` branch. Also, ensure that the working directory is clean (has no + uncommitted changes). +2. `cd packages/pusher` - Navigate to the pusher package. +3. `pnpm version [major|minor|patch]` - Choose the right version bump. This will bump the version, create a git tag and + commit it. +4. `pnpm run docker:build` - Build the docker image with tag `api3/pusher:latest`. +5. `docker tag api3/pusher:latest api3/pusher:` - Tag the image with the version. Replace the + `` with the version you just bumped (copy it from `package.json`). +6. `docker push api3/pusher:latest && docker push api3/pusher:` - Push the image upstream. Both the + latest and the versioned tag should be published. +7. `git push --follow-tags` - Push the tagged commit upstream. + ## Deployment -To deploy Pusher on AWS you can use the Cloud Formation template created by the API integrations team. The template can +To deploy pusher on AWS you can use the Cloud Formation template created by the API integrations team. The template can be found in the private api-integrations repository [here](https://github.com/api3dao/api-integrations/blob/main/data/cloudformation-template.json). -To deploy on premise you can use the Docker instructions below. +To deploy on premise you can use the Docker image by reading the instructions below. -## Docker +### Run pusher with Docker -Pusher is also dockerized. To run the dockerized pusher you need to: +To run the pusher docker image you need to: 1. Mount config folder to `/app/config`. The folder should contain the `pusher.json` and `secrets.env` files. 2. Pass the `-it --init` flags to the docker run command. This is needed to ensure the docker is stopped gracefully. See @@ -365,19 +395,3 @@ For example: # Assuming the current folder contains the "config" folder and ".env" file. docker run -it --init --volume $(pwd)/config:/app/config --env-file .env --rm api3/pusher:latest ``` - -As of now, the docker image is not published anywhere. You need to build it locally. To build the image run: - -```sh -docker build --target pusher --tag api3/pusher:latest ../../ -``` - -### Development only docker instructions - -You can use shorthands from package.json. To understand how the docker image is built, read the -[Dockerfile](../../Dockerfile). - -```sh -pnpm run docker:build -pnpm run docker:run -```