diff --git a/README.md b/README.md index 53fa734..95396cf 100644 --- a/README.md +++ b/README.md @@ -171,3 +171,49 @@ The building process is standard. You just need to notice that the `Dockerfile`s DOCKER_USER=$USER ./scripts/build-docker-frontend.sh DOCKER_USER=$USER ./scripts/build-docker-backend.sh ``` + +## Deployment + +This section covers the internal deployment of Substrate Telemetry to our staging and live environments. + +### Deployment to staging + +Every time new code is merged to `master`, a new version of telemetry will be automatically built and deployed to our staging environment, so there is nothing that you need to do. Roughly what will happen is: + +- An image tag will be generated that looks like `$CI_COMMIT_SHORT_SHA-beta`, for example `224b1fae-beta`. +- Docker images for the frontend and backend will be pushed to the docker repo (see https://hub.docker.com/r/parity/substrate-telemetry-backend/tags?page=1&ordering=last_updated and https://hub.docker.com/r/parity/substrate-telemetry-frontend/tags?page=1&ordering=last_updated). +- A deployment to the staging environment will be performed using these images. Go to https://gitlab.parity.io/parity/substrate-telemetry/-/pipelines to inspect the progress of such deployments. + +### Deployment to live + +Once we're happy with things in staging, we can do a deployment to live as follows. + +1. Ensure that the PRs you'd like to deploy are merged to master. +2. Navigate to https://gitlab.parity.io/parity/substrate-telemetry/-/pipelines/new. +3. Add a variable called `FORCE_DEPLOY` with the value `true`. +4. Hit 'Run Pipeline'. A deployment to staging will be carried out, and if you're happy with that, you can then hit the "play" button on the "Deploy-production" stage to perform the deployment to live. +5. Confirm that things are working once the deployment has finished by visiting https://telemetry.polkadot.io/. + +### Rolling back to a previous deployment + +If something goes wrong running the above, we can roll back the deployment to live as follows. + +1. Decide what image tag you'd like to roll back to. Go to https://hub.docker.com/r/parity/substrate-telemetry-backend/tags?page=1&ordering=last_updated and have a look at the available tags (eg `224b1fae-beta`) to select one you'd like. You can cross reference this with the tags available using `git tag` in the repository to help see which tags correspond to which code changes. +2. Navigate to https://gitlab.parity.io/parity/substrate-telemetry/-/pipelines/new. +3. Add a variable called `FORCE_DEPLOY` with the value `true`. +4. Add a variable called `FORCE_DOCKER_TAG` with a value corresponding to the tag you want to deploy, eg `224b1fae-beta`. Images must exist already for this tag. +5. Hit 'Run Pipeline'. As above, a deployment to staging will be carried out, and if you're happy with that, you can hit the "play" button on the "Deploy-production" stage to perform the deployment to live. +6. Confirm that things are working once the deployment has finished by visiting https://telemetry.polkadot.io/. + +### Deploying a commit that no image exists for + +This should be unnecessary, but I mention it here for the sake of completeness and to briefly mention the handling of specially tagged commits on master by the CI pipeline. + +If we want to deploy a commit that an image does not exist for (see https://hub.docker.com/r/parity/substrate-telemetry-backend/tags?page=1&ordering=last_updated), we can do the following. + +1. Tag the commit on `master` that you'd like to deploy, eg `git tag v0.1-foo`. The tag must be compatible with the regular expression `^v[0-9]+\.[0-9]+.*$`. +2. Push the tag to master, eg `git push origin v0.1-foo`. +3. This will kick off the deployment process, which in this case will also lead to new docker images being built. You can view the progress at https://gitlab.parity.io/parity/substrate-telemetry/-/pipelines. +4. Once a deployment to staging has been successful, run whatever tests you need against the staging deployment to convince yourself that you're happy with it. +5. Visit the CI/CD pipelines page again (URl above) and click the "play" button on the "Deploy-production" stage to perform the deployment to live. +6. Confirm that things are working once the deployment has finished by visiting https://telemetry.polkadot.io/. \ No newline at end of file