Prerequisites

Prerequisites for working with the repo

This section lists the prerequisites for working with the repository. Most contributors should start with the basic prerequisites. Depending on the task you need to perform, you may need to install more tools.

We also provide a Devcontainer for working with this repository without installing prerequisites. Keep reading for instructions.

Operating system

We support developing on macOS, Linux and Windows with WSL.

Asking for help

If you get stuck installing any of our dependencies, you can raise an issue or ask for help in our discord.

Required tools

This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present:

  • Git

  • Go

  • golangci-lint

  • protoc

  • make

    • Linux: Install the build-essential package:

      $ apt install build-essential
      
    • Mac:

      Xcode

      $ xcode-select --install
      

      Homebrew

      $ brew install make
      

Testing Required Tools

If you have not already done so, clone the repository and navigate there in your command shell.

You can build the main outputs using make:

$ make build lint

Running these steps will run our build and lint steps and verify that the tools are installed correctly. If you get stuck or suspect something is not working in these instructions please raise an issue or ask for help in our Discord linked on our homepage.

Integration/Multicloud Tests

Our integration/multicloud tests perform real requests to cloud providers. You can run these with the following commands

$ make integration-test
$ make multicloud-test

Note that the make test command only runs unit tests.

If you would like to run these locally, you will need to be authenticated. The following are the steps for each respective cloud provider.

Google Cloud

  1. Install the gcloud CLI. If you’re using the dev container, this will already be installed for you.

  2. Set up your application default credentials.

  3. Set the active project with gcloud config set project <project-id>.

  4. The tests will automatically create (and delete) new projects for each test run. You must set the environment variable INVISINETS_GCP_PROJECT_BILLING_ACCOUNT_NAME in the form of the billingAccount field of the “ProjectBillingInfo” resource.

    • If you’d like them to be created in a certain parent, set the environment variable INVISINETS_GCP_PROJECT_PARENT in the form of the parent field of the “Project” resource.

      Warning

      This requires privileges of creating projects and linking billing accounts.

    • If you want to use your own project, set the environment variable INVISINETS_GCP_PROJECT. The order for deleting resources when deleting through the console: instances, VPN tunnels, VPN gateway + peer/external VPN gateways + router, VPC. The connectivity tests can be deleted at any time.

      Warning

      Resources will not automatically be cleaned up for you.

Azure

  1. Install azure cli. If you’re using the dev container, this will already be installed for you.

  2. Authenticate to your account with azure login.

  3. The tests will automatically create (and delete) new resource groups for each test run. You must set the environment variable INVISINETS_AZURE_SUBSCRIPTION_ID with a valid subscription.

    • If you want to use your own existing resource group, set the environment variable INVISINETS_AZURE_RESOURCE_GROUP. The tests will not delete the resource group and instead only clean up the resources within it.

      Warning

      Resource group must be created before running the test.

If you’d like to persist resources after a test (i.e., not teardown project/resource group), you can set the environment variable INVISINETS_TEST_PERSIST to 1.

IBM

Note

IBM integration tests are not currently supported. We plan to add some soon.

Editor

If you don’t have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers.

Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice.

Launching VS Code

The best way to launch VS Code for Go is to do File > Open Folder on the repository.

You can easily do this from the command shell with code ., which opens the current directory as a folder in VS Code.

Using the Dev Container

Dev Containers allow you to run a development environment using VS Code inside a container. If you want to try this:

Now when you open the Paraglider repo, you will be prompted with the option to open in a Dev Container. This will take a few minutes the first time to download and build the container, but will be much faster on subsequent opens.

Additional Tools

Test summaries

The default go test output can be hard to read when you have many tests. We recommend gotestsum as a tool to solve this. Our make test command will automatically use gotestsum if it is available.