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

• Overview
• Quick Start
  • Docker Setup
    • Test With Docker
  • Bootstrapping
  • Ensure Everything Works
• Developer Environment Setup
  • Git Commit Signing
  • Developer tools
  • Pre-commit
  • Elixir Development
  • Rust Development
  • Shell script Development
• 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
• Logging and sensitive info
• Asking for Help

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 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

The goal of the quick start guide is to get an environment up and running quickly to allow you to get a feel for all of the various components that make up Firezone.

Once you've verified all components are running successfully, the detailed developer guides can help with getting you setup to develop on a specific Firezone component.

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

If you're using Docker Engine on Linux instead, you'll want to make sure to install the compose plugin instead so that you have v2 installed.

> docker compose version
Docker Compose version v2.27.0

To start the local Firezone cluster, follow these steps:

docker compose build
docker compose run --rm elixir /bin/sh -c "mix ecto.create && mix ecto.migrate && mix ecto.seed"

# Before moving to the next step, copy the Firezone account UUID from the seed step
# Here's an example of the output
    Created accounts:
    c89bcc8c-9392-4dae-a40d-888aef6d28e0: Firezone Account

docker compose up -d portal vault gateway client relay-1 relay-2

You should now be able to connect to http://localhost:8080/<account-uuid-here> and sign in with the following credentials:

Email:    firezone@localhost.local
Password: Firezone1234

The docker-compose.yml file configures the Docker development environment. If you make any changes you feel would benefit all developers, feel free to open a PR to get them merged!

After this you will have running:

• A portal
• A gateway connected to the portal
• A headless Linux client connected to the portal
• A relay connected to the portal
• A resource with IP 172.20.0.100 on a separate network shared with the gateway

We recommend generating a trusted self-signed certificate for local development to avoid debugging TLS issues.

On macOS you can generate and trust a certificate with:

cd elixir

# Generate a self-signed certificate for localhost
# Note: We use openssl instead of `mix phx.gen.cert` because of a Phoenix bug
# that generates invalid certificates missing parameters: :NULL
# See: https://github.com/phoenixframework/phoenix/issues/6319 which introduced this bug
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -days 365 \
    -keyout priv/cert/selfsigned-key.pem \
    -out priv/cert/selfsigned.pem \
    -subj "/O=Firezone Development/CN=localhost" \
    -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
    -addext "basicConstraints=critical,CA:FALSE" \
    -addext "keyUsage=critical,digitalSignature,keyEncipherment" \
    -addext "extendedKeyUsage=critical,serverAuth"

# Add the new cert to the system trust store
sudo security add-trusted-cert -d -p ssl -k /Library/Keychains/System.keychain priv/cert/selfsigned.pem

This will generate a self-signed certificate for localhost and add it to your system trust store for easier testing in browsers.

Note for Firefox users: Firefox uses its own certificate store and ignores the macOS system keychain by default. To trust the certificate in Firefox, either:

1. Go to about:config and set security.enterprise_roots.enabled to true, or
2. Import the cert directly: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import priv/cert/selfsigned.pem

# To test that a client can ping the resource
docker compose exec -it client ping 172.20.0.100

# You can also directly use the client
docker compose exec -it client /bin/sh

Firezone requires that all commits in the repository be signed. If you need assistance setting up git to sign commits, please read over the Github pages for Managing Commit signature verification

Docker is the preferred method of developing Firezone locally. It (mostly) works cross-platform, and can be used to develop Firezone on all three major desktop OS.

If you have followed the Docker Setup instructions in the Quick Start section, you can move along to the next step in the development environment setup. If you have not read the Docker Setup instructions we recommend following the directions listed there to get your Docker environment setup properly.

The versions for most tools and SDKs required for working on Firezone are managed via .tool-versions files in the respective directories, i.e. Elixir tools in elixir/.tool-versions etc.

You can use any .tool-versions-compatible version manager for installing them.

• Note: For a fresh install of asdf you will need to install some asdf-plugins. e.g. asdf plugin add nodejs && asdf install nodejs to set up the NodeJS plugin and package.

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

We use pre-commit to catch any static analysis issues before code is committed.

• Install Mise which will automatically install pre-commit and other required tools (see mise.toml)
• Install the repo-specific checks with pre-commit install --config .github/pre-commit-config.yaml

If you are interested in contributing to the Web Application/API, please read the detailed info found in the Elixir Developer Guide

If you are interested in contributing to the Gateway, Relay, or client library, please read the detailed info found in the Rust Developer Guide

Sometimes it's useful to test your changes in a local docker, however the docker-compose.yml file at the root directory requires rebuilding the images each time you want to test the change.

To solve this, you can use the rust/docker-compose-dev.yml file like docker compose -f docker-compose.yml -f rust/docker-compose-dev.yml <command>

This will use locally compiled binaries found at rust/target/x86_64-unknown-musl/debug

You can also set the env variable COMPOSE_FILE so you don't have to manually set the compose files each time.

See scripts/README.

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

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

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 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/.

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.

This will help tremendously during our release engineering process.

Please use the Conventional Commits standard to write your commit message.

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"

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

mise run lint

IP addresses and domain names may be logged at the DEBUG level, but not INFO or any other level that is enabled by default in production builds.

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