Skip to content

Latest commit

 

History

History
122 lines (86 loc) · 4.17 KB

how-to-contribute.md

File metadata and controls

122 lines (86 loc) · 4.17 KB
Raw

How to contribute

This guide is for contributors to the Permission Manager development.

Install Requirements

In order to setup the development environment you need to install the requirements listed above.

  • bats 1.8.2
  • ctlptl 0.8.16
  • golang 1.19
  • helm 3.11.1
  • jq 1.6
  • kind 0.17.0
  • kubectl >= 1.23.0
  • make 4.1
  • mkcert 1.4.4
  • nodejs 18.0.0
  • shellcheck 0.9.0
  • tilt 0.31.1
  • yarn 1.22.11
  • yq 4.30.8

You can use your preferred package manager to install the requirements but we recommend to use asdf and direnv that we actually use to manage the development environment.

Use asdf and direnv

  1. Install and configure asdf and direnv as described in the official documentation and this article

  2. Add the required asdf plugins to your asdf installation

    asdf plugin-add bats
asdf plugin-add ctlptl
asdf plugin-add direnv
asdf plugin-add golang
asdf plugin-add helm
asdf plugin-add jq
asdf plugin-add kind
asdf plugin-add kubectl
asdf plugin-add make
asdf plugin-add mkcert
asdf plugin-add nodejs
asdf plugin-add shellcheck
asdf plugin-add tilt
asdf plugin-add yarn
asdf plugin-add yq

  3. Run asdf install, it will install all the required versions of the tools listed in the .tool-versions file that we provide.

  4. Run direnv allow to load the local environment from the .envrc file. We provide a .envrc.example file that you can use as a template

Development

We choose to use Tilt for our development environment. Tilt is a tool that allows you to develop your application in a local Kubernetes cluster. It watches your code and automatically rebuilds and deploys your application when you change code.

Check the Tilt documentation to learn more about Tilt.

Start the development environment

We provide a Makefile's target that contains all you need to start the development environment. Just run the following commands:

# Run this one as root
echo "0.0.0.0 permission-manager.dev" >> /etc/hosts

# Use FORCE=1 to recreate the self-signed TLS certificates
make dev-up CLUSTER_VERSION=<k8s-version>

This command will:

  1. Setup the self-signed TLS certificates for the ingress to work (it install the CA certificate to your browser's trusted certificates) using mkcert

    IMPORTANT: If you are using NixOS you need to add the CA certificate to the trusted certificates manually. You can find the CA certificate in the certs directory.

  2. Start the local Kubernetes cluster and Tilt using our provided Tiltfile. Tilt will build and push the Permission Manager image and deploy it using the Helm chart into the cluster using the local environment variables declared in .envrc or .env-cluster file.

Access Permission Manager in your browser

Open up https://permission-manager.dev in your browser, and use admin / admin to login. Done and done!

Stop the development environment

To stop the development environment run the following command:

# Use FORCE=1 to delete local kind registry
make dev-down

Testing

Unit Tests

In order to run the server unit tests run make test-unit.

NOTE: You need to have a UI's build in the static/build directory to run the unit tests. You can build the UI using make build-ui command.

E2E Tests

The E2E tests provide to create a k8s cluster using helm and kind to the version that you specify the CLUSTER_VERSION,KIND_VERSION, HELM_VERSION variables.

So, Executing the make test-e2e command will create a kind cluster, install the CRDs, deploy the Permission Manager and run the E2E tests.

CLUSTER_NAME=<your cluster name> \
CLUSTER_VERSION=<your cluster version> \
KIND_VERSION=<your kind version> \
HELM_VERSION=<your helm version> \
make test-e2e

Publish a new release

To build and publish a new Permission Manager release run

bumpversion {mayor,minor,patch}
git push
git push --tags