10. Developer how-to’s
The following assume you have a working developer environment with all the dependencies listed in ./dependencies.md available to you.
If you want to deploy to the CI kubernetes cluster (how-tos below), you need to set the
KUBECONFIG env var, where
$cailleach_repo is replaced by your local checkout of the
Check that this file exists by running
10.1. How to look at the swagger docs / UI locally
Set up backing services:
Build and start wire-server services:
make c && ./services/run-services
Open your browser at: http://localhost:8080/api/swagger-ui for a list of API verions.
Also check out the docs for swagger in our staging environment:
Swagger API documentation. Replace the staging domain by
localhost:8080 to get to your local build.
10.2. How to run federation tests across two backends
kubectlavailable on your PATH
access to a kubernetes cluster via e.g. a
The process consists of:
Inspect/change the multi-backend tests
Deploy two backends to kubernetes cluster
Run multi-backend test half-locally half-on-kubernetes or fully on kubernetes
10.2.1. Inspect/change the multi-backend test code
services/brig/test/integration/API/Federation/End2End.hs for the current multi-backend tests.
Note that they only run if
INTEGRATION_FEDERATION_TESTS is set to
1. This is currently configured to be OFF when running regular brig integration tests (e.g. via
make -C services/brig integration) but is by default ON when running tests on kubernetes or on CI, or when using the
10.2.2. Deploy two backends to kubernetes cluster
Decide which code you would like to deploy. The following options are detailed in the subsections below.
2.1 Deploy the the latest compiled code from
2.2 Deploy code from your pull request
2.3 Deploy your local code to a kind cluster
10.2.2.1. Deploy the the latest compiled code from
First, find the latest CI-compiled code made available as docker images:
# Run all commands from the top directory of wire-server make latest-tag
Output might be
./hack/bin/find-latest-docker-tag.sh latest tag for brig: 2.104.11 latest tag for nginz: 2.104.11
Let’s assume the tags are the same(*) for both, then export an environment variable:
export DOCKER_TAG=2.104.11 export NAMESPACE="myname" make kube-integration-setup
This will create two full installations of wire-server on the kubernetes cluster you’ve configured to connect to, and should take ~10 minutes. The namespaces will be
make latest-tag gives different tags for brig and nginz:
maybe CI hasn’t finished, or failed. Look at concourse (
10.2.2.2. Deploy code from your pull request
Note: CI already runs multi-backend federation integration tests on your PR, so this section may not be often useful in practice. This is still documented for completeness and to help understand the relation between source code and compiled docker images on CI.
Check CI for the latest tag that has been created on your PR (expect this to take at least 30-60 minutes from the last time you pushed to your branch). Example:
Look at a successful job in the
wire-server-pr pipeline from a job bruild matching your desired PR and commit hash. Then, find the actual docker tag used.
# PR 1438 commit 7a183b2dbcf019df1af3d3b97604edac72eca762 translates to export DOCKER_TAG=0.0.1-pr.3684 export NAMESPACE="myname" make kube-integration-setup
10.2.2.3. Deploy your local code to a kind cluster
This can be useful to get quicker feedback while working on multi-backend code or configuration (e.g. helm charts) than to wait an hour for CI. This allows you to test code without uploading it to github and waiting an hour for CI.
FUTUREWORK: this process is in development (update this section after it’s confirmed to work):
10.2.2.3.1. Run tests in kind
Create a local kind cluster with
Upload images in docker-daemon running inside kind with
Note: First time all the images need to be uploaded. When working on one service it can be selectively uploaded using
Install wire-server using
Run tests using
Run end2end integration tests:
10.2.2.4. Deploy your local code to a kubernetes cluster
This sections describes how partially update a release with a local build of a service, in this example
Start by deploying a published release (see 2.1 or 2.2).
export NAMESPACE=$USER export DOCKER_TAG=2.116.32 make kube-integration-setup
Then build and push the
brig image by running
To update the release with brig’s local image run
./hack/bin/set-chart-image-version.sh "$DOCKER_TAG_LOCAL_BUILD" brig ./hack/bin/integration-setup-federation.sh
10.2.3. Run multi-backend tests
10.2.3.1. Run all integration tests on kubernetes
takes ~10 minutes to run
test output is delayed until all tests have run. You will have to scroll the output to find the relevant multi-backend test output.
tests run entirely on kubernetes.
includes running the federation multi-backend tests by default (see also section (1))
10.2.3.2. Run only the multi-backend tests
runs faster (~ half a minute)
test output is shown dynamically as tests run
business logic code runs on kubernetes, but the test executable runs on your local computer (which connects using
ensure you have compiled brig-integration:
make -C services/brig fast
ensure you have
telepresenceinstalled (see developer dependencies documentation)
Run the actual tests, (takes half a minute):
Note that this runs your locally compiled
brig-integration, so this allows to easily change test code locally with the following process:
change code under
make -C services/brig fast
10.2.3.3. Run selected integration tests on kubernetes
To run selective tests from brig-integration:
helm -n $NAMESPACE get hooks $NAMESPACE-wire-server | yq '.' | jq -r 'select(.metadata.name | contains("brig-integration"))' > /tmp/integration-pod # optional: edit the test pattern /tmp/integration-pod kubectl apply -n $NAMESPACE -f /tmp/integration-pod
To destroy all the resources on the kubernetes cluster that have been created run
Note: Simply deleting the namespaces is insufficient, because it leaves some resources (of kind ClusterRole, ClusterRoleBinding) that cause problems when redeploying to the same namespace via helm.
10.3. How to manage RabbitMQ
We support two different ways of managing the docker-compose instance of rabbitmq:
A web console interface is available here
rabbitmqadminCLI is made available in the dev environment