mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-25 01:01:27 +02:00
Simplify enterprise setup steps (#877)
This commit is contained in:
Bethuel Mmbaga
@@ -11,7 +11,7 @@ The scripts generate the Compose files, configuration, secrets, and Postgres set
|
||||
|
||||
Both run the **embedded identity provider**, so no external OIDC provider is required. On a fresh install, you create the owner account from the dashboard on first login; you can connect an external provider later.
|
||||
|
||||
NetBird issues `getting-started-enterprise.sh`, the GHCR token, and the license key with your [Enterprise Commercial License](https://netbird.io/pricing#on-prem). `migrate-to-enterprise.sh` is available on request — contact your account team.
|
||||
NetBird issues `getting-started-enterprise.sh` and the license key with your [Enterprise Commercial License](https://netbird.io/pricing#on-prem). If you wish to upgrade the community edition, `migrate-to-enterprise.sh` is available below.
|
||||
|
||||
## 1. Fresh Installation
|
||||
|
||||
@@ -24,7 +24,6 @@ NetBird issues `getting-started-enterprise.sh`, the GHCR token, and the license
|
||||
- `bash`, `curl`, `jq`, and `openssl` available on the host.
|
||||
- A real DNS-resolvable FQDN with an A record pointing at the host. Bare IP addresses are not supported.
|
||||
- Open inbound ports: `80/tcp`, `443/tcp`, and `3478/udp`.
|
||||
- GHCR token (PAT) associated with the enterprise license.
|
||||
- An enterprise license key authorized for the products you want to enable.
|
||||
|
||||
### 1.2 Run the script
|
||||
@@ -42,9 +41,8 @@ The script prompts for:
|
||||
- Whether to enable traffic flow — required for traffic event logging and streaming.
|
||||
- The public NetBird domain.
|
||||
- A single license key (used for all enabled products and features).
|
||||
- GHCR token (PAT).
|
||||
|
||||
It then generates the deployment files, logs in to GHCR, pulls the required images, starts Postgres, waits for it to become ready, and starts the remaining services.
|
||||
It then generates the deployment files, pulls the required images, starts Postgres, waits for it to become ready, and starts the remaining services.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
@@ -136,10 +134,6 @@ 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.
|
||||
|
||||
<Note>
|
||||
The migration script is available on request — contact your account team to obtain it.
|
||||
</Note>
|
||||
|
||||
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
|
||||
@@ -149,7 +143,6 @@ The script targets an existing combined-server deployment that has a `docker-com
|
||||
- `bash`, `openssl`, Docker, and Docker Compose are available on the host.
|
||||
- At least 5 GB of free disk space — the enterprise images (~2.2 GB) are pulled while the community images are still present (~1.5 GB extra), plus a SQLite backup and Postgres data.
|
||||
- `yq` is installed using the [Mike Farah implementation](https://github.com/mikefarah/yq); the Python wrapper is not supported.
|
||||
- GHCR token (PAT) associated with the enterprise license.
|
||||
- An enterprise license key authorized for the products you want to enable.
|
||||
- Access to the deployment directory that contains `docker-compose.yml`.
|
||||
|
||||
@@ -174,7 +167,7 @@ cd /path/to/existing/netbird/deployment
|
||||
curl -fsSL https://pkgs.netbird.io/migrate-to-enterprise.sh | bash
|
||||
```
|
||||
|
||||
The script detects the combined-server service name, the dashboard service name, the host path for `config.yaml`, the data volume mounted at `/var/lib/netbird`, and the Compose network. It then prompts for the license key, GHCR token, whether to migrate to Postgres, and whether to enable traffic flow.
|
||||
The script detects the combined-server service name, the dashboard service name, the host path for `config.yaml`, the data volume mounted at `/var/lib/netbird`, and the Compose network. It then prompts for the license key, whether to migrate to Postgres, and whether to enable traffic flow.
|
||||
|
||||
### 3.4 Files created by the migration script
|
||||
|
||||
@@ -279,13 +272,6 @@ Each entry follows the same structure: **Symptom → Cause → Resolution → Ve
|
||||
```
|
||||
- **Verification:** `curl -s https://<your-domain>/api/instance | jq .` returns `setupRequired: true`; the dashboard now shows the owner-setup flow on first visit.
|
||||
|
||||
### `docker login ghcr.io` fails during the script
|
||||
|
||||
- **Symptom:** `getting-started-enterprise.sh` aborts at the GHCR login step with an authentication error.
|
||||
- **Cause:** The token lacks the `read:packages` scope, or the username does not match the one issued alongside the enterprise license.
|
||||
- **Resolution:** Confirm the token at [github.com/settings/tokens](https://github.com/settings/tokens) has `read:packages` scope, and that the username matches the one NetBird issued with the license.
|
||||
- **Verification:** `echo "$TOKEN" | docker login ghcr.io -u "<username>" --password-stdin` returns `Login Succeeded`.
|
||||
|
||||
## Appendix: Using a custom TLS certificate
|
||||
|
||||
By default the generated `Caddyfile` uses Caddy's automatic TLS via Let's Encrypt. Operators using an internal PKI, a corporate CA, or a pre-issued wildcard certificate can swap to their own cert with three manual edits after the script runs. Caddy stays in front of the stack either way — all reverse-proxy routes (signal, management, OAuth2, relay, dashboard) flow through it.
|
||||
|
||||
@@ -18,7 +18,7 @@ Throughout this page, **control plane** means the server-side services you self-
|
||||
|
||||
The commercial license is designed for running NetBird on infrastructure you control: your own cloud account, data center, or private environment. Nothing phones home for your network traffic.
|
||||
|
||||
With the license, NetBird issues you three things: an install script, a GitHub Container Registry (GHCR) token to pull the enterprise container images (the `-cloud` image variants), and a license key. You set the key as `NB_LICENSE_KEY` in the deployment's `.env` file; on startup the server validates it and unlocks the licensed features.
|
||||
With the license, NetBird issues you two things: an install script and a license key. You set the key as `NB_LICENSE_KEY` in the deployment's `.env` file; on startup the server validates it and unlocks the licensed features.
|
||||
|
||||
To obtain a license, contact the NetBird team through the [on-prem pricing page](https://netbird.io/pricing#on-prem).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user