firezone/CONTRIBUTING.md

Contributing

Thanks for considering contributing to Firezone! Please read this guide to get started.

Table of Contents

• Overview
• Developer Environment Setup
  • Docker Setup
    • Docker Caveat
  • asdf-vm
  • Pre-commit
  • The .env File
  • Bootstrapping
  • Ensure Everything Works
  • Running this inside a Devcontainer
    • Note: Devcontainer on Windows
• Reporting Bugs
• Opening a Pull Request
  • Run Tests
    • Unit Tests
    • End-to-end Tests
  • Use Detailed Commit Messages
  • Ensure Static Analysis Checks Pass
• Code of Conduct
• Asking for Help

Overview

We deeply appreciate any and all contributions to the project and do our best to ensure your contribution is included.

To maximize your chances of getting your pull request approved, please abide by the following general guidelines:

1. Please adhere to our code of conduct.
2. Please test with your code and include unit tests when possible.
3. It is up to you, the contributor, to make a case for why your change is a good idea.
4. For any security issues, please do not open a Github Issue. Please follow responsible disclosure practices laid out in SECURITY.md

Developer Environment Setup

Docker is the preferred method of development Firezone locally. It (mostly) works cross-platform, and can be used to develop Firezone on all three major desktop OS. This also provides a small but somewhat realistic network environment with working nftables and WireGuard subsystems for live development.

Docker Setup

We recommend Docker Desktop even if you're developing on Linux. This is what the Firezone core devs use and comes with compose included.

Docker Caveat

Routing packets from the host's WireGuard client through the Firezone compose cluster and out to the external network will not work. This is because Docker Desktop rewrites the source address from containers to appear as if they originated the host , causing a routing loop:

1. Packet originates on Host
2. Enters WireGuard client tunnel
3. Forwarding through the Docker bridge net
4. Forward to the Firezone container, 127.0.0.1:51820
5. Firezone sends packet back out
6. Docker bridge net, Docker rewrites src IP to Host's LAN IP, (d'oh!)
7. Docker sends packet out to Host ->
8. Packet now has same src IP and dest IP as step 1 above, and the cycle continues

However, packets destined for Firezone compose cluster IPs (172.28.0.0/16) reach their destination through the tunnel just fine. Because of this, it's recommended to use 172.28.0.0/16 for your AllowedIPs parameter when using host-based WireGuard clients with Firezone running under Docker Desktop.

asdf-vm Setup

While not strictly required, we use asdf-vm to manage language versions for Firezone. You'll need to install the language runtimes according to the versions laid out in the .tool-versions file.

If using asdf, simply run asdf install from the project root.

This is used to run static analysis checks during pre-commit and for any local, non-Docker development or testing.

Pre-commit

We use pre-commit to catch any static analysis issues before code is committed. Install with Homebrew: brew install pre-commit or pip: pip install pre-commit.

The ENV file

For running tests and developing Firezone outside of Docker, you'll need some environment variables present in your shell's env.

See .env.sample an example of what variables you need. We recommend copying this file to .env and using a dotenv loader to apply this to your current shell env.

For example, run the following command to 'source' the environment variables from .env on mix test:

env $(cat .env | grep -v \# | xargs) mix test

This will initialize everything and run the test suite. If you have no failures, Firezone should be properly set up 🥳.

At this point you should be able to sign in to http://localhost:4000 with email firezone@localhost and password firezone1234.

Bootstrapping

To start the local development cluster, follow these steps:

docker compose build
docker compose up -d postgres
docker compose run --rm elixir mix ecto.setup
docker compose up

Now you should be able to connect to https://localhost/ and sign in with email firezone@localhost and password firezone1234.

Ensure Everything Works

There is a client container in the docker-compose configuration that can be used to simulate a WireGuard client connecting to Firezone. It's already provisioned in the Firezone development cluster and has a corresponding WireGuard configuration located at .devcontainer/wg0.client.conf. It's attached to the isolation Docker network which is isolated from the other Firezone Docker services. By connecting to Firezone from the client container, you can test the WireGuard tunnel is set up correctly by pinging the caddy container:

• docker compose exec client ping 172.28.0.99
• docker compose exec client curl -k 172.28.0.99:8443/hello: this should return HELLO text.

If the above commands indicate success, you should be good to go!

Running this inside a Devcontainer

You can run this using Github Codespaces or your own devcontainer using Docker.

On GitHub Codespaces, follow the instructions above but pass in your Codespace external url:

EXTERNAL_URL=[your_devcontainer_url] MIX_ENV=dev mix start

or using the .env file

env $(cat .env | grep -v \# | xargs) mix start

On Github Codespaces you can find your EXTERNAL_URL by issuing the following command in the terminal:

echo "https://${CODESPACE_NAME}-4000.githubpreview.dev"

Note: Devcontainer on Windows

If you are on Windows, make sure your git config core.autocrlf is off. Otherwise, the \r characters confuse asdf, which in turn fails the devcontainer build.

Reporting Bugs

We appreciate any and all bug reports.

To report a bug, please first search for it in our issues tracker. Be sure to search closed issues as well.

If it's not there, please open a new issue and include the following:

• Description of the problem
• Expected behavior
• Steps to reproduce
• Estimated impact: High/Medium/Low
• Firezone version
• Platform architecture (amd64, aarch64, etc)
• Linux distribution
• Linux kernel version

Opening a Pull Request

We love pull requests! To ensure your pull request gets reviewed and merged swiftly, please read the below before opening a pull request.

Run Tests

Please test your code. As a contributor, it is your responsibility to ensure your code is bug-free, otherwise it may be rejected. It's also a good idea to check the code coverage report to ensure your tests are covering your new code. E.g.

Unit Tests

Unit tests can be run with mix test from the project root.

To view line coverage information, you may run mix coveralls.html which will generate an HTML coverage report in cover/.

End-to-end Tests

More comprehensive e2e testing is performed in the CI pipeline, but for security reasons these will not be triggered automatically by your pull request and must be manually triggered by a reviewer.

Use Detailed Commit Messages

This will help tremendously during our release engineering process. E.g.

read -r -d '' COMMIT_MSG << EOM
Updating the foobar widget to support additional widths

Additional widths are needed to various device screen sizes.
Closes #72
EOM

git commit -m "$COMMIT_MSG"

Ensure Static Analysis Checks Pass

This should run automatically when you run git commit, but in case it doesn't:

pre-commit run --all-files

Asking For Help

If you get stuck, don't hesitate to ask for help on our mailing list.