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
```
Then install make:
```
$ apt install make
```

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

Install the gcloud CLI. If you’re using the dev container, this will already be installed for you.
Set up your application default credentials.
Set the active project with gcloud config set project <project-id>.
The tests will automatically create (and delete) new projects for each test run. You must set the environment variable PARAGLIDER_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 PARAGLIDER_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 PARAGLIDER_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

Install azure cli. If you’re using the dev container, this will already be installed for you.
Authenticate to your account with azure login.
The tests will automatically create (and delete) new resource groups for each test run. You must set the environment variable PARAGLIDER_AZURE_SUBSCRIPTION_ID with a valid subscription.
- If you want to use your own existing resource group, set the environment variable PARAGLIDER_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 PARAGLIDER_TEST_PERSIST to 1.

IBM

Set environment variable PARAGLIDER_IBM_API_KEY with an IAM API key. Create a key on IBM’s web console.
Set environment variable PARAGLIDER_IBM_RESOURCE_GROUP_ID with a resource group ID. Pick a resource group from IBM’s web console.

Cleanup function, terminating all Paraglider resources on IBM, is executed automatically when tests end, unless INVISINETS_TEST_PERSIST is set to 1.

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:

Install Docker
Install VS Code
Install the Dev Container extension

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.

gotestsum