add first version of tailwind docs

This commit is contained in:
Pascal Fischer
2023-05-03 18:55:40 +02:00
parent d95022d98e
commit 9d42e075f7
125 changed files with 1 additions and 11576 deletions

View File

@@ -1,4 +0,0 @@
{
"label": "Getting Started",
"position": 4
}

View File

@@ -1,280 +0,0 @@
---
sidebar_position: 2
title: Installation
tags:
- client
- how-to
- install
---
### Linux
**APT/Debian**
1. Add the repository:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] 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
```
**Fedora**
1. Create the repository file:
```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. Import the file
```bash
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
```
3. Install the package
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install netbird-ui
```
**NixOS 22.11+/unstable**
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration
```bash
sudo nixos-rebuild switch
```
### 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
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
Recommended way is to add NetBird in firewall settings:
1. Go to "Control panel".
2. Select "Windows Defender Firewall".
3. Select "Advanced settings".
4. Select "Outbound Rules" -> "New rule".
5. In the new rule select "Program" and click "Next".
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
7. Select "Allow the connection" and click "Next".
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
10. Disconnect and connect to NetBird.
### 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 -L -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
sudo chown root:root /usr/bin/netbird
sudo 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.
<p>
<img src="/docs/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
#### 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.
<p>
<img src="/docs/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
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
Set the ```NB_SETUP_KEY``` environment variable and run the command.
:::tip Environment variables
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
:::
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_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.

View File

@@ -1,75 +0,0 @@
---
sidebar_position: 1
title: Quickstart Guide
---
Step-by-step video guide on YouTube:
<div class="videowrapper">
<iframe src="https://www.youtube.com/embed/HYlhvr_eu2U" 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.
![](/img/getting-started/auth.png)
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.
![](/img/getting-started/empty-peers.png)
3. Choose your machine operating system (in our case it is ```Linux```) and proceed with the installation steps.
![](/img/getting-started/add-peer.png)
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`.
>
![](/img/getting-started/systray.png)
5. At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
![](/img/getting-started/device-confirmation.png)
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
![](/img/getting-started/netbird-up.png)
8. Return to ```Peers``` and you should notice 2 new machines with status ```online```
![](/img/getting-started/peers.png)
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/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)

View File

@@ -1,179 +0,0 @@
---
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 an identity provider (available options will be listed later in this guide).
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
:::tip netbird as a service
It might be a good idea to try NetBird before self-hosting.
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
:::
### 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 TCP ports ```80, 443, 33073, 10000``` (Dashboard HTTP & HTTPS, Management gRCP & HTTP APIs, Signal gRPC API 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 :)
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
### Step 1: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
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
```
Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
### Step 2: 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.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
```bash
## example file, you can copy this file to setup.env and update its values
##
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
NETBIRD_AUTH_AUDIENCE=""
# e.g. netbird-client
NETBIRD_AUTH_CLIENT_ID=""
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- 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.
:::
:::info
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
:::
### Step 3: Configure Identity Provider
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
Pick the one that suits your needs, follow the steps, and continue with this guide:
- Continue with [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service).
- Continue with [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
### Step 4: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
### Step 5: Run configuration script
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.
### Step 6: Run docker compose:
```bash
docker-compose up -d
```
### Step 7: Check docker logs (Optional)
```bash
docker-compose logs signal
docker-compose logs management
docker-compose logs coturn
docker-compose logs dashboard
```
### Advanced: Running netbird behind an existing reverse-proxy
If you want to run netbird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).
:::info
Not all reverse-proxies are supported as netbird uses *gRPC* for various components.
:::
#### Configuration for netbird
In `setup.env`:
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port
Optional:
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server
:::tip info
The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
:::
Now you can continue with [Step 3](#step-3-configure-identity-provider).
#### Configuration for your reverse-proxy
Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.
The following endpoints have to be setup:
Endpoint | Protocol | Target service and internal-port
------------------------------- | --------- | --------------------------------
/ | HTTP | dashboard:80
/signalexchange.SignalExchange/ | gRPC | signal:80
/api | HTTP | management:443
/management.ManagementService/ | gRPC | management:443
Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.
:::tip
You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
:::
### Get in touch
Feel free to ping us on [Slack](https://join.slack.com/t/netbirdio/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)