Add proxy and enable flags to the enterprise getting-started guide (#999)

This commit is contained in:
Bethuel Mmbaga
2026-10-02 12:23:28 +03:00
committed by GitHub
parent 7d66d1b59f
commit ca2634d77d
@@ -39,6 +39,7 @@ curl -fsSL https://pkgs.netbird.io/getting-started-enterprise.sh | bash
The script prompts for: The script prompts for:
- Whether to enable traffic flow — required for traffic event logging and streaming. - Whether to enable traffic flow — required for traffic event logging and streaming.
- Whether to enable the [NetBird Proxy](/manage/reverse-proxy), and optionally [CrowdSec](/selfhosted/maintenance/crowdsec).
- The public NetBird domain. - The public NetBird domain.
- A single license key (used for all enabled products and features). - A single license key (used for all enabled products and features).
@@ -48,6 +49,10 @@ It then generates the deployment files, pulls the required images, starts Postgr
Enabling traffic flow adds NATS, a flow receiver, and a flow enricher to the stack. Traffic flow is required for traffic event logging and streaming. Enabling traffic flow adds NATS, a flow receiver, and a flow enricher to the stack. Traffic flow is required for traffic event logging and streaming.
</Note> </Note>
<Note>
The NetBird Proxy needs a wildcard DNS record for your service domains (for example `*.netbird.example.com`) pointing at the host.
</Note>
### 1.3 Generated files ### 1.3 Generated files
The script writes the generated files into the current directory: The script writes the generated files into the current directory:
@@ -57,8 +62,9 @@ The script writes the generated files into the current directory:
| `.env` | Runtime configuration, license key, and generated secrets | `600` | | `.env` | Runtime configuration, license key, and generated secrets | `600` |
| `docker-compose.yml` | Compose stack for the NetBird server and optional traffic-flow services | `644` | | `docker-compose.yml` | Compose stack for the NetBird server and optional traffic-flow services | `644` |
| `config.yaml` | NetBird server configuration (YAML) | `600` | | `config.yaml` | NetBird server configuration (YAML) | `600` |
| `traefik/` | Traefik dynamic configuration, including the proxy's `proxy.yaml` | `755` |
Reverse proxy and automatic HTTPS are configured through Traefik labels and command flags inside `docker-compose.yml`, so there is no separate proxy configuration file. Reverse proxy and automatic HTTPS are configured through Traefik labels and command flags inside `docker-compose.yml`.
The script aborts if generated files already exist in the directory. This avoids overwriting secrets or replacing an existing deployment by accident. The script aborts if generated files already exist in the directory. This avoids overwriting secrets or replacing an existing deployment by accident.
@@ -94,6 +100,24 @@ Enabling traffic flow adds:
| `receiver` | `ghcr.io/netbirdio/flow-receiver-cloud:latest` | Traffic flow ingest | | `receiver` | `ghcr.io/netbirdio/flow-receiver-cloud:latest` | Traffic flow ingest |
| `enricher` | `ghcr.io/netbirdio/flow-enricher-cloud:latest` | Traffic flow enrichment | | `enricher` | `ghcr.io/netbirdio/flow-enricher-cloud:latest` | Traffic flow enrichment |
Enabling the NetBird Proxy adds:
| Service | Image | Notes |
| --- | --- | --- |
| `proxy` | `ghcr.io/netbirdio/reverse-proxy:latest` | NetBird Proxy |
| `crowdsec` | `crowdsecurity/crowdsec:v1.7.7` | Only when CrowdSec is enabled |
### 1.7 Enable features on an existing installation
Run the script with a flag from the installation directory:
```bash
curl -fsSL https://pkgs.netbird.io/getting-started-enterprise.sh | bash -s -- --enable-traffic-events
curl -fsSL https://pkgs.netbird.io/getting-started-enterprise.sh | bash -s -- --enable-proxy
```
The script shows the changes to `docker-compose.yml` and asks before applying them. If a step fails, it restores the previous files. After `--enable-traffic-events`, turn on traffic events in the dashboard settings.
## 2. Connect Identity Providers ## 2. Connect Identity Providers
We recommend using SCIM provisioning where possible. In the following setup guides, you may **skip JWT group settings** and use our group syncing integration instead. We recommend using SCIM provisioning where possible. In the following setup guides, you may **skip JWT group settings** and use our group syncing integration instead.
@@ -135,6 +159,8 @@ We recommend using SCIM provisioning where possible. In the following setup guid
Use `migrate-to-enterprise.sh` to convert an existing community combined-server deployment to the enterprise images. The same script also migrates SQLite data to Postgres and enables traffic flow, so no manual Compose or `config.yaml` edits are required for the supported migration path. Use `migrate-to-enterprise.sh` to convert an existing community combined-server deployment to the enterprise images. The same script also migrates SQLite data to Postgres and enables traffic flow, so no manual Compose or `config.yaml` edits are required for the supported migration path.
For installations created with `getting-started-enterprise.sh`, use [1.7 Enable features on an existing installation](#1-7-enable-features-on-an-existing-installation) instead.
The script targets an existing combined-server deployment that has a `docker-compose.yml`, a bind-mounted `config.yaml`, and a persistent `/var/lib/netbird` data volume. The script targets an existing combined-server deployment that has a `docker-compose.yml`, a bind-mounted `config.yaml`, and a persistent `/var/lib/netbird` data volume.
### 3.1 Prerequisites ### 3.1 Prerequisites
@@ -268,7 +294,7 @@ Each entry follows the same structure: **Symptom → Cause → Resolution → Ve
- **Resolution:** Sign in with the existing owner credentials if available. To start over from scratch: - **Resolution:** Sign in with the existing owner credentials if available. To start over from scratch:
```bash ```bash
docker compose down --volumes # removes containers and the postgres/embedded-IdP data docker compose down --volumes # removes containers and the postgres/embedded-IdP data
rm -f .env docker-compose.yml config.yaml rm -rf .env docker-compose.yml config.yaml traefik
curl -fsSL https://pkgs.netbird.io/getting-started-enterprise.sh | bash curl -fsSL https://pkgs.netbird.io/getting-started-enterprise.sh | bash
``` ```
- **Verification:** `curl -s https://<your-domain>/api/instance | jq .` returns `setupRequired: true`; the dashboard now shows the owner-setup flow on first visit. - **Verification:** `curl -s https://<your-domain>/api/instance | jq .` returns `setupRequired: true`; the dashboard now shows the owner-setup flow on first visit.
@@ -317,6 +343,8 @@ If your Traefik already has a file provider, add this `tls` block to its existin
### Update `docker-compose.yml` ### Update `docker-compose.yml`
Installations created by the current script already have the file provider and the `./traefik` mount, so only add the certificate mount and remove ACME.
**Enable the file provider.** Add this to the `traefik` service's `command:` list: **Enable the file provider.** Add this to the `traefik` service's `command:` list:
```yaml ```yaml
@@ -391,4 +419,5 @@ echo | openssl s_client -connect <your-domain>:443 -servername <your-domain> 2>/
Then run `docker compose up -d proxy`. Then run `docker compose up -d proxy`.
- **Renewals.** Replace both files at the same paths, then `touch traefik/dynamic.yaml`. Traefik watches the dynamic configuration, not the certificates it references, so replacing them alone has no effect. Touching it reloads them with no container restart. - **Renewals.** Replace both files at the same paths, then `touch traefik/dynamic.yaml`. Traefik watches the dynamic configuration, not the certificates it references, so replacing them alone has no effect. Touching it reloads them with no container restart.
- You can leave the `netbird_traefik_letsencrypt` volume in place. With no resolver configured, the stored certificate is inert. - You can leave the `netbird_traefik_letsencrypt` volume in place. With no resolver configured, the stored certificate is inert.
- `--enable-proxy` and `--enable-traffic-events` keep this setup.
- Dropping the `80:80` mapping does not affect certificates: this deployment validates over TLS-ALPN-01 on port 443 and never uses port 80 for ACME. You do lose the HTTP→HTTPS redirect. - Dropping the `80:80` mapping does not affect certificates: this deployment validates over TLS-ALPN-01 on port 443 and never uses port 80 for ACME. You do lose the HTTP→HTTPS redirect.