github-personal/firezone
1
0
Fork 0
mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: move markdown files into docs/ directory (#3773)

Browse Source 
Apart from the LICENSE, GitHub supports detecting all of these files
also within a `docs/` directory. This includes the README!
This commit is contained in:
Thomas Eizinger
2024-02-27 12:12:57 +11:00
committed by GitHub
parent 2891481662
commit 67aeb009e9
13 changed files with 34 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/CODE_OF_CONDUCT.md Normal file
View File

@@ -0,0 +1,132 @@
# Firezone Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
`conduct AT firezone.dev`.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

279
docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,279 @@
# Contributing
Thanks for considering contributing to Firezone! Please read this guide to get
started.
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Docker Setup](#docker-setup)
- [Test With Docker](#test-with-docker)
- [Bootstrapping](#bootstrapping)
- [Ensure Everything Works](#ensure-everything-works)
- [Developer Environment Setup](#developer-environment-setup)
- [Git Commit Signing](#git-commit-signing)
- [asdf-vm](#asdf-vm-setup)
- [Pre-commit](#pre-commit)
- [Elixir Development](#elixir-development)
- [Rust Development](#rust-development)
- [Shell script Development](#shell-script-development)
- [Reporting Bugs](#reporting-bugs)
- [Opening a Pull Request](#opening-a-pull-request)
- [Run Tests](#run-tests)
- [Unit Tests](#unit-tests)
- [End-to-end Tests](#end-to-end-tests)
- [Use Detailed Commit Messages](#use-detailed-commit-messages)
- [Ensure Static Analysis Checks Pass](#ensure-static-analysis-checks-pass)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Asking for Help](#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](CODE_OF_CONDUCT.md).
1. Please test your code and include unit tests when possible.
1. It is up to you, the contributor, to make a case for why your change is a
good idea.
1. For any security issues, please **do not** open a Github Issue. Please follow
responsible disclosure practices laid out in [SECURITY.md](SECURITY.md)
## Quick Start
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.
### Docker Setup
We recommend [Docker Desktop](https://docs.docker.com/engine/install/#desktop)
even if you're developing on Linux. This is what the Firezone core devs use and
comes with `compose` included.
#### Test With Docker
When you want to test every component together the ideal way to go is to use
docker.
To do this you first need a seeded database, for that follow the steps on the
[Elixir's README](../elixir/README.md#running-control-plane-for-local-development).
Then you can do:
```sh
# To start all the components
docker compose up -d --build
# To check the logs
docker compose logs -f
```
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
```sh
# 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
```
##### Rust development with docker
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 situated at
`rust/target/x86_64-unknown-musl/debug`
You can also set use the env variable `COMPOSE_FILE` as explained [here](https://docs.docker.com/compose/environment-variables/envvars/#compose_file)
so you don't have to manually set the compose files each time.
### Bootstrapping
To start the local Firezone cluster, follow these steps:
```
docker compose build
docker compose run --rm elixir /bin/sh -c "cd apps/domain && 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 api web vault gateway client relay
```
You should now be able to connect to `http://localhost:8080/<account-uuid-here>`
and sign in with the following credentials:
```
Email: firezone@localhost
Password: Firezone1234
```
The [`docker-compose.yml`](../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!
### Ensure Everything Works
```
#TODO
```
## Developer Environment Setup
### Git Commit Signing
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](https://docs.github.com/en/authentication/managing-commit-signature-verification)
### Docker Setup
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](#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.
### asdf-vm Setup
While not strictly required, we use [asdf-vm](https://asdf-vm.com) to manage
language versions for Firezone. You'll need to install the language runtimes
according to the versions laid out in the [.tool-versions](../.tool-versions) file.
If using asdf, simply run `asdf install` from the project root.
- Note: For a fresh install of `asdf` you will need to install some
[asdf-plugins](https://asdf-vm.com/manage/plugins.html). Running
`asdf install` will show which `asdf` plugins need to be installed prior to
installing the required language runtimes.
This is used to run static analysis checks during [pre-commit](#pre-commit) and
for any local, non-Docker development or testing.
### Pre-commit
We use [pre-commit](https://pre-commit.com) to catch any static analysis issues
before code is committed. Install with Homebrew: `brew install pre-commit` or
pip: `pip install pre-commit`.
### Elixir Development
If you are interested in contributing to the Web Application/API, please read
the detailed info found in the [Elixir Developer Guide](../elixir/README.md)
### Rust Development
If you are interested in contributing to the Gateway, Relay, or client library,
please read the detailed info found in the
[Rust Developer Guide](../rust/README.md)
### Shell script Development
See [scripts/README](../scripts/README.md).
## Reporting Bugs
We appreciate any and all bug reports.
To report a bug, please first
[search for it in our issues tracker](https://github.com/firezone/firezone/issues).
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](https://www.conventionalcommits.org/en/v1.0.0/#specification)
standard to write your commit message.
E.g.
```bash
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:
```bash
pre-commit run --all-files
```
## Asking For Help
If you get stuck, don't hesitate to ask for help on our
[community forums](https://discourse.firez.one/?utm_source=contributing).

67
docs/MAINTAINERS.md Normal file
View File

@@ -0,0 +1,67 @@
# Maintainer's Guide
This document contains instructions for maintaining the code in this repo
including the product, website, and documentation.
Table of Contents:
- [Releasing](#releasing)
- [Publishing Clients](#publishing-clients)
- [Apple Client](#apple-client)
## Releasing
**Note**: The version gets set from the Makefile
- Go to Actions tab in GH
- For apple the workflow is `Swift`
- For Android the workflow is `Kotlin`
- Click the edit button on the Draft 1.0.0 release
- Give the release a name (manually - right now we're using
`1.0.0-pre.<num-here>`)
- Create a new tag as well with the same name as the release (click
`create new tag`)
- Double check that the body text of the release is what is expected
- **IMPORTANT**: Scroll to the bottom and check the `Set as latest release` and
uncheck `Set as pre-release`
- Click `Publish Release`
- The `Publish` workflow is now run Note: This will deploy to production and the
following will happen
- All logged in users on the portal will be logged out, but the clients will
not be logged out
- All the websockets will be disconnected and should automatically reconnect
## Publish Clients
### Apple Client
- Log in to the following URL: https://appstoreconnect.apple.com/
- Go to Apps
- Go to Firezone
- Click on TestFlight
- Note: You can't delete a `Version` in TestFlight
- There is "internal testing" and "external testing"
- "internal testing" is only the Firezone team
- "external testing" is the beta customers
- Click on the testing group you want to release to and on the testing group
page:
- Click the `+` on the `Builds` sections
- Select the build you want to push out
- Check the `Automatically notify testers`
- Type a description of what you want users to see in the notification sent to
users (e.g. a small change log of what's in this release)
- Click `Submit for Review`
- Then you have to wait for it to be reviewed (has been a matter of minutes
as of late)
(Alternative way to push out a release)
- After login go to `Builds` (select either ios/macos)
- Find the `Version` section you want to release and drop down to show list of
builds
- Find the build you want to push out, hover over the `Groups` column and select
the `+` icon
- From here it's the same as the instructions above to type a description,
etc...

183
docs/NOTICE.txt Normal file
View File

@@ -0,0 +1,183 @@
NOTICES AND INFORMATION
Do Not Translate or Localize
This software incorporates material from third parties.
Please refer to this document for the license terms of the components that this product uses directly or as a derivate of.
===
Portions of the Firezone product contain derivative work from the https://github.com/cloudflare/boringtun. Its license is included below:
Copyright (c) 2019 Cloudflare, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
===
Portions of this product contain derivative work from https://github.com/wireguard/wireguard-apple. Its license is included below:
Copyright © 2018-2023 WireGuard LLC. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
===
Portions of this product contain derivative work from https://github.com/Willena/OpenDNSUpdater. Its license is included below:
The MIT License
Copyright (c) 2018- Guillaume VILLENA, https://github.com/willena
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
===
Portions of this product contain derivative work from https://www.wintun.net/. Its license is included below:
Prebuilt Binaries License
-------------------------
1. DEFINITIONS. "Software" means the precise contents of the "wintun.dll"
files that are included in the .zip file that contains this document as
downloaded from wintun.net/builds.
2. LICENSE GRANT. WireGuard LLC grants to you a non-exclusive and
non-transferable right to use Software for lawful purposes under certain
obligations and limited rights as set forth in this agreement.
3. RESTRICTIONS. Software is owned and copyrighted by WireGuard LLC. It is
licensed, not sold. Title to Software and all associated intellectual
property rights are retained by WireGuard. You must not:
a. reverse engineer, decompile, disassemble, extract from, or otherwise
modify the Software;
b. modify or create derivative work based upon Software in whole or in
parts, except insofar as only the API interfaces of the "wintun.h" file
distributed alongside the Software (the "Permitted API") are used;
c. remove any proprietary notices, labels, or copyrights from the Software;
d. resell, redistribute, lease, rent, transfer, sublicense, or otherwise
transfer rights of the Software without the prior written consent of
WireGuard LLC, except insofar as the Software is distributed alongside
other software that uses the Software only via the Permitted API;
e. use the name of WireGuard LLC, the WireGuard project, the Wintun
project, or the names of its contributors to endorse or promote products
derived from the Software without specific prior written consent.
4. LIMITED WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF
ANY KIND. WIREGUARD LLC HEREBY EXCLUDES AND DISCLAIMS ALL IMPLIED OR
STATUTORY WARRANTIES, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE, QUALITY, NON-INFRINGEMENT, TITLE, RESULTS,
EFFORTS, OR QUIET ENJOYMENT. THERE IS NO WARRANTY THAT THE PRODUCT WILL BE
ERROR-FREE OR WILL FUNCTION WITHOUT INTERRUPTION. YOU ASSUME THE ENTIRE
RISK FOR THE RESULTS OBTAINED USING THE PRODUCT. TO THE EXTENT THAT
WIREGUARD LLC MAY NOT DISCLAIM ANY WARRANTY AS A MATTER OF APPLICABLE LAW,
THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER
SUCH LAW. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE
EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
5. LIMITATION OF LIABILITY. To the extent not prohibited by law, in no event
WireGuard LLC or any third-party-developer will be liable for any lost
revenue, profit or data or for special, indirect, consequential, incidental
or punitive damages, however caused regardless of the theory of liability,
arising out of or related to the use of or inability to use Software, even
if WireGuard LLC has been advised of the possibility of such damages.
Solely you are responsible for determining the appropriateness of using
Software and accept full responsibility for all risks associated with its
exercise of rights under this agreement, including but not limited to the
risks and costs of program errors, compliance with applicable laws, damage
to or loss of data, programs or equipment, and unavailability or
interruption of operations. The foregoing limitations will apply even if
the above stated warranty fails of its essential purpose. You acknowledge,
that it is in the nature of software that software is complex and not
completely free of errors. In no event shall WireGuard LLC or any
third-party-developer be liable to you under any theory for any damages
suffered by you or any user of Software or for any special, incidental,
indirect, consequential or similar damages (including without limitation
damages for loss of business profits, business interruption, loss of
business information or any other pecuniary loss) arising out of the use or
inability to use Software, even if WireGuard LLC has been advised of the
possibility of such damages and regardless of the legal or quitable theory
(contract, tort, or otherwise) upon which the claim is based.
6. TERMINATION. This agreement is affected until terminated. You may
terminate this agreement at any time. This agreement will terminate
immediately without notice from WireGuard LLC if you fail to comply with
the terms and conditions of this agreement. Upon termination, you must
delete Software and all copies of Software and cease all forms of
distribution of Software.
7. SEVERABILITY. If any provision of this agreement is held to be
unenforceable, this agreement will remain in effect with the provision
omitted, unless omission would frustrate the intent of the parties, in
which case this agreement will immediately terminate.
8. RESERVATION OF RIGHTS. All rights not expressly granted in this agreement
are reserved by WireGuard LLC. For example, WireGuard LLC reserves the
right at any time to cease development of Software, to alter distribution
details, features, specifications, capabilities, functions, licensing
terms, release dates, APIs, ABIs, general availability, or other
characteristics of the Software.
===
Portions of this product (`rust/connection-tests`) contain derivative work from https://github.com/libp2p/test-plans. Its license is included below:
The MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

210
docs/README.md Normal file
View File

@@ -0,0 +1,210 @@
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github-production-user-asset-6210df.s3.amazonaws.com/167144/280001862-73a16cec-f7fd-4983-91ed-4fb8c372b578.png">
<img alt="firezone logo" width="400" src="https://github-production-user-asset-6210df.s3.amazonaws.com/167144/280001875-267dad97-8f4e-4825-8581-71196ce01d3d.png">
</picture>
</p>
<p align="center">
<strong>A modern alternative to legacy VPNs.</strong>
</p>
---
<p align="center">
<a href="https://github.com/firezone/firezone/releases">
<img src="https://img.shields.io/github/v/release/firezone/firezone?color=%23999">
</a>
<a href="https://discourse.firez.one/?utm_source=readme">
<img src="https://img.shields.io/static/v1?logo=discourse&logoColor=959DA5&label=support%20forum&labelColor=333a41&message=join&color=611f69" alt="firezone Discourse" />
</a>
<img src="https://img.shields.io/static/v1?logo=github&logoColor=959DA5&label=Test&labelColor=333a41&message=passing&color=3AC358" alt="firezone" />
<a href="https://coveralls.io/github/firezone/firezone?branch=legacy">
<img src="https://coveralls.io/repos/github/firezone/firezone/badge.svg?branch=legacy" alt="Coverage Status" />
</a>
<img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/firezone/firezone"/>
<img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed/firezone/firezone"/>
<a href="https://cloudsmith.com">
<img src="https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith" alt="Cloudsmith">
</a>
<a href="https://twitter.com/intent/follow?screen_name=firezonehq">
<img src="https://img.shields.io/twitter/follow/firezonehq?style=social&logo=twitter" alt="follow on Twitter">
</a>
</p>
---
**Note**: 🚧 The `main` branch is undergoing major restructuring in preparation
for the release of Firezone 1.0 🚧.
See the [`legacy` branch](https://github.com/firezone/firezone/tree/legacy) if
you're looking for Firezone 0.7.
[Read the 1.0 announcement for more](https://www.firezone.dev/blog/firezone-1-0).
---
## Overview
[Firezone](https://www.firezone.dev/?utm_source=readme) is an open source
platform to securely manage remote access for any-sized organization. Unlike
most VPNs, Firezone takes a granular, least-privileged approach to access
management with group-based policies that control access to individual
applications, entire subnets, and everything in between.
<p align="center">
<img width="1439" alt="architecture" src="https://github.com/firezone/firezone/assets/167144/48cd6a1e-2f3f-4ca7-969a-fc5b33e13d1c">
</p>
<!-- TODO: New intro usage video
![firezone-usage](https://user-images.githubusercontent.com/52545545/147392573-fe4cb936-a0a8-436f-a69b-c0a9587de58b.gif)
-->
## Features
Firezone is:
- **Fast:** Built on WireGuard® to be
[3-4 times](https://wireguard.com/performance/) faster than OpenVPN.
- **Scalable:** Deploy two or more gateways for automatic load balancing and
failover.
- **Private:** Peer-to-peer, end-to-end encrypted tunnels prevent packets from
routing through our infrastructure.
- **Secure:** Zero attack surface thanks to Firezone's holepunching tech which
establishes tunnels on-the-fly at the time of access.
- **Open:** Our entire product is open-source, allowing anyone to audit the
codebase.
- **Flexible:** Authenticate users via email, Google Workspace, or OIDC and sync
users and groups automatically.
- **Simple:** Deploy gateways and configure access in minutes with a snappy
admin UI.
Firezone is **not:**
- A tool for creating bi-directional mesh networks
- A full-featured router or firewall
- An IPSec or OpenVPN server
## Contents of this repository
This is a monorepo containing the full Firezone product, marketing website, and
product documentation, organized as follows:
- [elixir](../elixir): Control plane and internal Elixir libraries:
- [elixir/apps/web](../elixir/apps/web): Admin UI
- [elixir/apps/api](../elixir/apps/api): API for Clients, Relays and Gateways.
- [rust/](../rust): Data plane and internal Rust libraries:
- [rust/gateway](../rust/gateway): Gateway - Tunnel server based on WireGuard
and deployed to your infrastructure.
- [rust/relay](../rust/relay): Relay - STUN/TURN server to facilitate
holepunching.
- [rust/linux-client](../rust/linux-client): Linux CLI client.
- [rust/gui-client](../rust/gui-client): Cross-platform GUI client.
- [swift/](../swift/apple): macOS / iOS clients.
- [kotlin/](../kotlin/android): Android / ChromeOS clients.
- [website/](../website): Marketing website and product documentation.
- [terraform/](../terraform): Terraform files for our cloud infrastructure:
- [terraform/modules/gateway-google-cloud-compute](../terraform/modules/gateway-google-cloud-compute):
Example Terraform module for deploying a Gateway to a Google Compute
Regional Instance Group.
## Quickstart
Firezone 1.x is currently accepting early access signups for closed testing.
Fill out the
[early access form](https://www.firezone.dev/product/early-access?utm_source=readme)
to request access and we'll be in touch!
## Frequently asked questions (FAQ)
### Can I self-host Firezone?
Our [license](#license) won't stop you from self-hosting the entire Firezone
product top to bottom, but we can't commit the resources to make this a smooth
experience and therefore don't support self-hosting the control plane at this
time.
If you have a business case requiring an on-prem installation of Firezone please
[get in touch](https://www.firezone.dev/contact/sales?utm_source=readme).
If you're feeling especially adventurous and want to self-host Firezone for
**educational** or **recreational** purposes, you'll want to build and
distribute the clients from source to ensure they remain locked to a version
compatible with your self-hosted control plane. Unfortunately, the following
clients must be distributed through proprietary app stores due to restrictions
imposed by Apple and Google:
- macOS
- iOS
- Android / ChromeOS
Because it's impossible to select which client version to install from a
particular app store, building and distributing Firezone from source is the only
to way self-host Firezone at this time.
Otherwise, if you're hobbyist or developer and are looking to spin it up locally
to contribute or experiment with, see [CONTRIBUTING.md](CONTRIBUTING.md).
### How do I upgrade from 0.7?
Unfortunately, you can't. The good news is Firezone 1.x is _much_ easier to
setup and manage than 0.x and so you probably don't need to.
### How long will 0.7 be supported until?
**Firezone 0.7 is currently end-of-life and will stop receiving updates after
January 31st, 2024.** It will continue to be available indefinitely from the
`legacy` branch of this repo under the Apache 2.0 license.
### What's your pricing structure like?
Please see our pricing page at
https://www.firezone.dev/pricing?utm_source=readme
## Documentation
Additional documentation on general usage, troubleshooting, and configuration
can be found at [https://docs.firezone.dev](https://docs.firezone.dev).
## Get Help
If you're looking for help installing, configuring, or using Firezone, check our
community support options:
1. [Discussion Forums](https://discourse.firez.one/?utm_source=readme): Ask
questions, report bugs, and suggest features.
1. [Public Slack Group](https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w):
Join live discussions, meet other users, and get to know the contributors.
1. [Open a PR](https://github.com/firezone/firezone/issues): Contribute a bugfix
or make a contribution to Firezone.
<!-- TODO
If you need help deploying or maintaining Firezone for your business, consider
[contacting us about our paid support plan](https://www.firezone.dev/contact/sales?utm_source=readme).
-->
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=firezone/firezone&type=Date)](https://star-history.com/#firezone/firezone&Date)
## Developing and Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
See [SECURITY.md](SECURITY.md).
## License
Portions of this software are licensed as follows:
- All content residing under the "elixir/" directory of this repository, if that
directory exists, is licensed under the "Elastic License 2.0" license defined
in "elixir/LICENSE".
- All third party components incorporated into the Firezone Software are
licensed under the original license provided by the owner of the applicable
component.
- Content outside of the above mentioned directories or restrictions above is
available under the "Apache 2.0 License" license as defined in "LICENSE".
WireGuard® is a registered trademark of Jason A. Donenfeld.

46
docs/SECURITY.md Normal file
View File

@@ -0,0 +1,46 @@
# Security Policy
We appreciate your help in making Firezone secure! We take security issues very
seriously and strive to fix all security issues as soon as they're reported.
## Announcements
We'll announce major security issues on our security mailing list located at:
https://discourse.firez.one/?utm_source=security
## Supported Versions
We release security patches for supported versions of Firezone. We recommend
running the latest version of Firezone at all times.
## Reporting a Vulnerability
Please **do not** open a Github Issue for security issues you encounter.
Instead, please send an email to `security AT firezone.dev` describing the issue
and we'll respond as soon as possible.
## PGP Key
You may use the public key below to encrypt emails to `security AT firezone.dev`.
You can also find this key at:
https://pgp.mit.edu/pks/lookup?op=get&search=0x45113BA04AD83D8A
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: SKS 1.1.6
Comment: Hostname: pgp.mit.edu
mDMEYYwK5BYJKwYBBAHaRw8BAQdA4ooDpwDy3V0wHCftM/LHD5e713LSr0SQy49joUMgHoS0
JkZpcmV6b25lIFNlY3VyaXR5IDxzZWN1cml0eUBmaXJlei5vbmU+iJoEExYKAEIWIQQlD4tW
gEEHBC38anNFETugStg9igUCYYwK5AIbAwUJA8JnAAULCQgHAgMiAgEGFQoJCAsCBBYCAwEC
HgcCF4AACgkQRRE7oErYPYoORwEAiYi3arrcR2e5OfqsoAbCN0O6M0HWeo1K/ZoFWH2jLy0B
AMsWk58vepKqNhUKhuDb8bSjK8TOr/IxB63lSkQaz9MIuDgEYYwK5BIKKwYBBAGXVQEFAQEH
QPLzia/me7FOsFfAJKWm0X1qC5byv2GWn6LZPV013AdoAwEIB4h+BBgWCgAmFiEEJQ+LVoBB
BwQt/GpzRRE7oErYPYoFAmGMCuQCGwwFCQPCZwAACgkQRRE7oErYPYr0ZQEAig86wu+zrNiT
B4t3dk3psHRj+Kdn4uURLjUBZqYNvXoA+QEBUPtP7hNjum+1FrzYmHUFdCBA/cszz7x7PQ36
5gcE
=0gEr
-----END PGP PUBLIC KEY BLOCK-----
```