28fe571543
* Remove _build folders for umbrella apps
For umbrella apps everything goes into /_build directory so there no need to ignore directories that should never be created
* Change mix aliases to be more aligned with what OS community would expect
1. We want ecto.create and ecto.migrate to be run on each tests, this will simplify setup steps (no need to run migrations manually)
2. ecto.remigrate is not needed because now you can just run ecto.drop and on tests migrations would be executed anyways.
* Rename docker-compose step name in CONTRIBUTING.md
The step was renamed here: dd67baf629 (diff-67a4805fdcc6145d7b3ada2a6099a9b2e91c9d0fd108c22f95d2f01d219793d1R10)
* Remove .devcontainer
This an is opinionated change. Right now devcontainer doesn't work but should be easy to fix (with renaming step name), but at the same time it forces developers that use VS code to have unified development environment (including plugins for the editor itself).
I feel like it's not a good path to go for OS and for small team - everyone should be allowed to use setup they like. Especially for people like me that tend to recompile ls-elixir for Elixir plugin from master branch.
Plus it's yet another thing to maintain while nobody on the team is using it, which means it will be always causing issues.
* Make fz_http mix.exs aliases aligned with umbrella app ones
* Redirect stderr to stdout in a command called from dev.exs
Otherwise I'm getting this on my MacOS (that has a `route` implementation that doesn't show interfaces) when `mix phx.server` is executed:
```
usage: route [-dnqtv] command [[modifiers] args]
```
* Fix race condition due to static device field values
Both public_key and name are unique and we should not use static values for field covered by unique index, otherwise deadlocks and slow tests are expected.
* Remove unwanted transaction block
The changeset code doesn't have any code that accesses the database and individual Ecto.SQL commands are already wrapped in transactions by default, so there is no need to start it manually and hold for longer than expected (while irrelevant Elixir code is running).
* Use netstat to identify egress interface on MacOS
* Rename uninstall.sh to omnibus-uninstall.sh
* Fix uninstall path in omnibus_build.yml
8.1 KiB
Contributing
Thanks for considering contributing to Firezone! Please read this guide to get started.
Table of Contents
- Overview
- Developer Environment Setup
- Reporting Bugs
- Opening a Pull Request
- 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:
- Please adhere to our code of conduct.
- Please test with your code and include unit tests when possible.
- It is up to you, the contributor, to make a case for why your change is a good idea.
- 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:
- Packet originates on Host
- Enters WireGuard client tunnel
- Forwarding through the Docker bridge net
- Forward to the Firezone container, 127.0.0.1:51820
- Firezone sends packet back out
- Docker bridge net, Docker rewrites src IP to Host's LAN IP, (d'oh!)
- Docker sends packet out to Host ->
- 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.
Routing packets from another host on the local network, through your development machine, and out to the external Internet should work as well.
Local HTTPS
We use Caddy as a development proxy. The docker-compose.yml is set up to link
Caddy's local root cert into your priv/pki/authorities/local/ directory.
Simply add the root.crt file to your browser and/or OS certificate store in
order to have working local HTTPS. This file is generated when Caddy launches for
the first time and will be different for each developer.
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 firezone 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 priv/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.99docker compose exec client curl -k 172.28.0.99:8443/hello: this should returnHELLOtext.
If the above commands indicate success, you should be good to go!
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.
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"
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.