mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 15:36:36 +00:00
Move the documentation repository to a public repo
Added a LICENSE and documentation on how to contribute Updated CI/CD to use the root level code
This commit is contained in:
mlsmaycon
4
docs/getting-started/_category_.json
Normal file
4
docs/getting-started/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 3
|
||||
}
|
||||
206
docs/getting-started/installation.md
Normal file
206
docs/getting-started/installation.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Installation
|
||||
---
|
||||
|
||||
### Linux
|
||||
|
||||
**APT/Debian**
|
||||
1. Add the repository:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install ca-certificates curl gnupg -y
|
||||
curl -L https://pkgs.wiretrustee.com/debian/public.key | sudo apt-key add -
|
||||
echo 'deb https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
|
||||
```
|
||||
2. Update APT's cache
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
```
|
||||
3. Install the package
|
||||
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo apt-get install netbird
|
||||
# for GUI package
|
||||
sudo apt-get install netbird-ui
|
||||
```
|
||||
|
||||
**RPM/Red hat**
|
||||
|
||||
1. Add the repository:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
|
||||
[Wiretrustee]
|
||||
name=Wiretrustee
|
||||
baseurl=https://pkgs.wiretrustee.com/yum/
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
|
||||
repo_gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
2. Install the package
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo yum install netbird
|
||||
# for GUI package
|
||||
sudo yum install netbird-ui
|
||||
```
|
||||
### macOS
|
||||
**Homebrew install**
|
||||
1. Download and install homebrew at https://brew.sh/
|
||||
2. If wiretrustee was previously installed with homebrew, you will need to run:
|
||||
```bash
|
||||
# Stop and uninstall daemon service:
|
||||
sudo wiretrustee service stop
|
||||
sudo wiretrustee service uninstall
|
||||
# unlik the app
|
||||
brew unlink wiretrustee
|
||||
```
|
||||
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
|
||||
|
||||
3. Install the client
|
||||
```bash
|
||||
# for CLI only
|
||||
brew install netbirdio/tap/netbird
|
||||
# for GUI package
|
||||
brew install --cask netbirdio/tap/netbird-ui
|
||||
```
|
||||
4. If you installed CLI only, you need to install and start the client daemon service:
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Windows
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
|
||||
3. Proceed with the installation steps
|
||||
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
|
||||
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
|
||||
> To uninstall the client and service, you can use Add/Remove programs
|
||||
|
||||
### Binary Install
|
||||
**Installation from binary (CLI only)**
|
||||
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest release:
|
||||
```bash
|
||||
curl -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
You need to replace some variables from the URL above:
|
||||
|
||||
- Replace **VERSION** with the latest released verion.
|
||||
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
|
||||
- Replace **Arch** with your target system CPU archtecture
|
||||
|
||||
:::
|
||||
|
||||
3. Decompress
|
||||
```bash
|
||||
tar xcf ./netbird_<VERSION>.tar.gz
|
||||
sudo mv netbird /usr/bin/netbird
|
||||
chmod +x /usr/bin/netbird
|
||||
```
|
||||
After that you may need to add /usr/bin in your PATH environment variable:
|
||||
````bash
|
||||
export PATH=$PATH:/usr/bin
|
||||
````
|
||||
4. Install and run the service
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Running NetBird with SSO Login
|
||||
#### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
|
||||
|
||||
#### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
```bash
|
||||
netbird up
|
||||
```
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
|
||||
|
||||
Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
### Running NetBird with a Setup Key
|
||||
In case you are activating a server peer, you can use a [setup key](/overview/setup-keys) as described in the steps below.
|
||||
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
|
||||
|
||||
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/overview/setup-keys)).
|
||||
|
||||
For all systems:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY>
|
||||
```
|
||||
|
||||
For **Docker**, you can run with the following command:
|
||||
```bash
|
||||
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
|
||||
```
|
||||
> TAG > 0.6.0 version
|
||||
|
||||
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
|
||||
```
|
||||
|
||||
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
|
||||
|
||||
2. Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
3. Check your IP:
|
||||
|
||||
On **macOS** :
|
||||
````bash
|
||||
sudo ifconfig utun100
|
||||
````
|
||||
On **Linux**:
|
||||
```bash
|
||||
ip addr show wt0
|
||||
```
|
||||
On **Windows**:
|
||||
```bash
|
||||
netsh interface ip show config name="wt0"
|
||||
```
|
||||
|
||||
### Running NetBird in Docker
|
||||
|
||||
```bash
|
||||
docker run --rm --privileged -d -e WT_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
|
||||
```
|
||||
|
||||
See [Docker example](examples/netbird-docker.md) for details.
|
||||
|
||||
### Troubleshooting
|
||||
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
|
||||
which is ```https://api.wiretrustee.com:33073```.
|
||||
|
||||
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
|
||||
to override it you can do the following:
|
||||
|
||||
```bash
|
||||
netbird down
|
||||
netbird up --management-url https://<CORRECT HOST:PORT>/
|
||||
```
|
||||
|
||||
To override it see the solution #1 above.
|
||||
75
docs/getting-started/quickstart.md
Normal file
75
docs/getting-started/quickstart.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Quickstart Guide
|
||||
---
|
||||
|
||||
Step-by-step video guide on YouTube:
|
||||
|
||||
<div class="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/Tu9tPsUWaY0" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/>
|
||||
This guide describes how to quickly get started with NetBird and create a secure private network with 2 connected machines.
|
||||
|
||||
One machine is a Linux laptop, and the other one a EC2 node running on AWS.
|
||||
Both machines are running Linux but NetBird also works on Windows and MacOS.
|
||||
|
||||
1. Sign-up at [https://app.netbird.io/](https://app.netbird.io/)
|
||||
|
||||
You can use your Google, GitHub or Microsoft account.
|
||||
|
||||
|
||||
|
||||
2. After a successful login you will be redirected to the ```Peers``` screen which is empty because you don't have any peers yet.
|
||||
|
||||
Click ```Add peer``` to add a new machine.
|
||||
|
||||
|
||||
|
||||
3. Choose your machine operating system (in our case it is ```Linux```) and proceed with the installation steps.
|
||||
|
||||
|
||||
|
||||
4. If you installed NetBird Desktop UI you can use it to connect to the network instead of running `netbird up` command. Look for `NetBird` in your application list, run it, and click `Connect`.
|
||||
>
|
||||
|
||||
|
||||
|
||||
5. At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
|
||||
|
||||
|
||||
|
||||
6. On the EC2 node repeat the installation steps and run `netbird up` command.
|
||||
|
||||
```bash
|
||||
sudo netbird up
|
||||
```
|
||||
7. Copy the verification URL from the terminal output and paste it in your browser. Repeat step #5
|
||||
|
||||
|
||||
|
||||
8. Return to ```Peers``` and you should notice 2 new machines with status ```online```
|
||||
|
||||
|
||||
|
||||
9. To test the connection you could try pinging devices:
|
||||
|
||||
On your laptop:
|
||||
```bash
|
||||
ping 100.64.0.2
|
||||
```
|
||||
|
||||
On the EC2 node:
|
||||
```bash
|
||||
ping 100.64.0.1
|
||||
```
|
||||
10. Done! You now have a secure peer-to-peer private network configured.
|
||||
|
||||
<br/>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/wiretrustee/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
|
||||
|
||||
134
docs/getting-started/self-hosting.md
Normal file
134
docs/getting-started/self-hosting.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Self-hosting Guide
|
||||
|
||||
NetBird is open-source and can be self-hosted on your servers.
|
||||
|
||||
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
|
||||
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn) and a 3rd party service [Auth0](https://auth0.com/).
|
||||
|
||||
:::info auth0
|
||||
All the components can be self-hosted except for the Auth0 service.
|
||||
This service offers excellent support for multiple features that we need, and it saved us lots of time.
|
||||
We couldn't find any suitable open-source solution that would be a good combination of effort and benefit.
|
||||
There is a free plan that can fulfill most of the personal use-cases.
|
||||
|
||||
There were a few discussions about alternatives on [GitHub](https://github.com/netbirdio/dashboard/issues/9).
|
||||
We'd greatly appreciate any help on integrating one of the open-source Auth0 alternatives.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
|
||||
|
||||
### Requirements
|
||||
|
||||
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
|
||||
- Any Linux OS.
|
||||
- Docker Compose installed (see [Install Docker Compose](https://docs.docker.com/compose/install/)).
|
||||
- Domain name pointing to the public IP address of your server.
|
||||
- Open ports ```443, 33071, 33073, 10000``` (Dashboard, Management HTTP API, Management gRpc API, Signal gRpc respectively) on your server.
|
||||
- Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, UDP 3478, and range of ports, UDP 49152-65535, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
|
||||
- Maybe a cup of coffee or tea :)
|
||||
|
||||
### Step-by-step guide
|
||||
|
||||
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
|
||||
|
||||
1. Create Auth0 account at [auth0.com](https://auth0.com/).
|
||||
2. Get latest released NetBird code:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
REPO="https://github.com/netbirdio/netbird/"
|
||||
# this command will fetch the latest release e.g. v0.6.1
|
||||
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
|
||||
echo $LATEST_TAG
|
||||
|
||||
# this comman will clone the latest tag
|
||||
git clone --depth 1 --branch $LATEST_TAG $REPO
|
||||
```
|
||||
|
||||
and switch to the infra folder that contains docker-compose file:
|
||||
|
||||
```bash
|
||||
cd netbird/infrastructure_files/
|
||||
```
|
||||
3. Prepare configuration files.
|
||||
|
||||
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
|
||||
|
||||
The [setup.env](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env) file contains multiple properties that have to be filled.
|
||||
:::tip
|
||||
You need to fill only the first 5 properties, the rest will be filled automatically at a later step.
|
||||
:::
|
||||
```bash
|
||||
# Dashboard domain. e.g. app.mydomain.com
|
||||
NETBIRD_DOMAIN=""
|
||||
# e.g. dev-24vkclam.us.auth0.com
|
||||
NETBIRD_AUTH0_DOMAIN=""
|
||||
# e.g. 61u3JMXRO0oOevc7gCkZLCwePQvT4lL0
|
||||
NETBIRD_AUTH0_CLIENT_ID=""
|
||||
# e.g. https://app.mydomain.com/ or https://app.mydomain.com,
|
||||
# Make sure you used the exact same value for Identifier
|
||||
# you used when creating your Auth0 API
|
||||
NETBIRD_AUTH0_AUDIENCE=""
|
||||
# e.g. hello@mydomain.com
|
||||
NETBIRD_LETSENCRYPT_EMAIL=""
|
||||
```
|
||||
|
||||
Please follow the steps to get the values.
|
||||
|
||||
4. Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
|
||||
|
||||
5. Configure Auth0 ```NETBIRD_AUTH0_DOMAIN``` ```NETBIRD_AUTH0_CLIENT_ID``` properties.
|
||||
|
||||
* To obtain these, please use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK".
|
||||
|
||||
> Use ```https://YOUR DOMAIN``` as ````Allowed Callback URLs````, ```Allowed Logout URLs```, ```Allowed Web Origins``` and ```Allowed Origins (CORS)```
|
||||
* set the variables in the ```setup.env```
|
||||
* Make sure that `Token Endpoint Authentication Method` is set to `None` in your Auth0 Default Application
|
||||
6. Configure ```NETBIRD_AUTH0_AUDIENCE``` property.
|
||||
|
||||
* Check [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) section to obtain AuthAudience.
|
||||
* set the property in the ```setup.env``` file.
|
||||
7. Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
|
||||
|
||||
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
|
||||
|
||||
:::tip
|
||||
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
|
||||
:::
|
||||
|
||||
8. Make sure all the required properties set in the ```setup.env``` file and run:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
|
||||
|
||||
9. Run docker compose:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
10. Optionally check the logs by running:
|
||||
|
||||
```bash
|
||||
docker-compose logs signal
|
||||
docker-compose logs management
|
||||
docker-compose logs coturn
|
||||
docker-compose logs dashboard
|
||||
```
|
||||
|
||||
### Get in touch
|
||||
|
||||
Feel free to ping us on [Slack](https://join.slack.com/t/wiretrustee/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) if you have any questions
|
||||
|
||||
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) :pray:
|
||||
- Follow us [on Twitter](https://twitter.com/netbird)
|
||||
Reference in New Issue
Block a user