diff --git a/src/pages/get-started/install/android-tv.mdx b/src/pages/get-started/install/android-tv.mdx index 69325b8d..1c77f439 100644 --- a/src/pages/get-started/install/android-tv.mdx +++ b/src/pages/get-started/install/android-tv.mdx @@ -47,7 +47,7 @@ Changing servers erases the device's current NetBird config, so you'll need to c confirm-erase-cponfig -Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to your management.json configuration file if you're unsure. +Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'change' to apply your new management server config, and if successful you'll see the following: diff --git a/src/pages/get-started/install/android.mdx b/src/pages/get-started/install/android.mdx index b2c9eb64..a20a4a13 100644 --- a/src/pages/get-started/install/android.mdx +++ b/src/pages/get-started/install/android.mdx @@ -43,7 +43,7 @@ Changing servers erases the device's current NetBird config, so you'll need to c confirmeraseconfig -Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to your management.json configuration file if you're unsure. +Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'change' to apply your new management server config, and if successful you'll see the following: diff --git a/src/pages/get-started/install/tvos.mdx b/src/pages/get-started/install/tvos.mdx index e6f8cbd2..8d42f50b 100644 --- a/src/pages/get-started/install/tvos.mdx +++ b/src/pages/get-started/install/tvos.mdx @@ -30,7 +30,7 @@ Navigate to **'Settings > Change Server'**, and the app will warn you that chang tvos-confirm-change-server After confirming, you'll be presented with a dialog to enter your management server URL. Cloud users who want to enroll the device with a setup key should enter the URL For cloud users, this is `https://api.netbird.io:443`. -For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to your management.json configuration file if you're unsure. +For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'Change' to apply your new management server config. NetBird will run a brief verification step on the details you've entered, after which you can move on to connecting. diff --git a/src/pages/manage/activity/index.mdx b/src/pages/manage/activity/index.mdx index 36ac7c2c..29c41206 100644 --- a/src/pages/manage/activity/index.mdx +++ b/src/pages/manage/activity/index.mdx @@ -120,7 +120,7 @@ Future versions will also support connection events that occur in NetBird agents The `unknown` name or `unknown@unknown.com` email address may be displayed in the activity event store if the encryption key has been corrupted or lost. This issue is most relevant for self-hosted setups. In this case, the events returned by the API could show `unknown@unknown.com` for the email address field and `unknown` for the name field. - If the configuration files have been generated by the `configure.sh` script, you can find the previous encryption key in the backup files in the same folder as the script. Look for the DataStoreEncryptionKey field in the `management.json` backup file. + For the combined setup, the encryption key is the server.store.encryptionKey field in config.yaml. For older multi-container setups generated by the configure.sh script, look for the DataStoreEncryptionKey field in the management.json backup file. ## Enable Audit Events Streaming to SIEM Systems diff --git a/src/pages/selfhosted/environment-variables.mdx b/src/pages/selfhosted/environment-variables.mdx index a0be3c61..c2daee43 100644 --- a/src/pages/selfhosted/environment-variables.mdx +++ b/src/pages/selfhosted/environment-variables.mdx @@ -267,7 +267,7 @@ environment: Configuration values are applied in the following order (later values override earlier): 1. Default values -2. Configuration file (`management.json`) +2. Configuration file (`config.yaml` for combined setup, `management.json` for older multi-container setup) 3. Environment variables 4. Command-line flags @@ -275,6 +275,6 @@ Configuration values are applied in the following order (later values override e - [Self-hosting Quickstart Guide](/selfhosted/selfhosted-quickstart) - [Advanced Self-hosting Guide](/selfhosted/selfhosted-guide) -- [Configuration Files Reference](/selfhosted/configuration-files) - Detailed documentation for docker-compose.yml, management.json, and other config files +- [Configuration Files Reference](/selfhosted/configuration-files) - Detailed documentation for docker-compose.yml, config.yaml, and other config files - [Management SQLite Store](/selfhosted/sqlite-store) - [Management Postgres Store](/selfhosted/postgres-store) diff --git a/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx b/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx index 7751a0a2..6ae7803d 100644 --- a/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx +++ b/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx @@ -38,7 +38,32 @@ NetBird will refuse to disable local authentication if no external identity prov ## Configuration -Update your `management.json` to disable local authentication: +### Combined setup (config.yaml) + +Set `localAuthDisabled` to `true` in your `config.yaml`: + +```yaml +server: + auth: + localAuthDisabled: true +``` + +Restart the server: +```bash +docker compose restart netbird-server +``` + + +For a full list of available configuration options, see the [config.yaml.example](https://github.com/netbirdio/netbird/blob/main/combined/config.yaml.example) reference file. + + +### Older multi-container setup (management.json) + + +This section applies to deployments using the older multi-container architecture. If you deployed using [`getting-started.sh`](/selfhosted/selfhosted-quickstart), you are on the combined setup and should use the `config.yaml` instructions above. See the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + +Update your `management.json`: ```json { @@ -49,12 +74,18 @@ Update your `management.json` to disable local authentication: } ``` -After updating the configuration, restart the Management service. -The local login option will no longer appear on the login page—users will only see the configured external identity providers. +Restart the Management service: +```bash +docker compose restart management +``` + +--- + +After updating the configuration, the local login option will no longer appear on the login page — users will only see the configured external identity providers. ## Re-enabling Local Authentication -To restore local authentication, set `LocalAuthDisabled` to `false` (or remove the option) and restart the Management service. +To restore local authentication, set `localAuthDisabled` back to `false` in `config.yaml` (or `LocalAuthDisabled` in `management.json`) and restart the server. All previously created local users will be able to log in again with their existing passwords. diff --git a/src/pages/selfhosted/identity-providers/local.mdx b/src/pages/selfhosted/identity-providers/local.mdx index 0b7cfc7b..074b1e22 100644 --- a/src/pages/selfhosted/identity-providers/local.mdx +++ b/src/pages/selfhosted/identity-providers/local.mdx @@ -41,7 +41,39 @@ Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configu ### Enabling Embedded IdP -The embedded IdP is enabled by default when using the new [`getting-started.sh`](/selfhosted/selfhosted-quickstart) quickstart script. For manual configuration, update your `management.json`: +The embedded IdP is enabled by default when using the [`getting-started.sh`](/selfhosted/selfhosted-quickstart) quickstart script and requires no manual configuration. + +#### Combined setup (config.yaml) + +The embedded IdP is always enabled in the combined setup and cannot be disabled. The relevant settings in `config.yaml` are: + +```yaml +server: + auth: + issuer: "https://netbird.example.com/oauth2" + localAuthDisabled: false + signKeyRefreshEnabled: true + dashboardRedirectURIs: + - "https://netbird.example.com/nb-auth" + - "https://netbird.example.com/nb-silent-auth" + cliRedirectURIs: + - "http://localhost:53000/" + + store: + encryptionKey: "" +``` + + +For a full list of available configuration options, see the [config.yaml.example](https://github.com/netbirdio/netbird/blob/main/combined/config.yaml.example) reference file. + + +#### Older multi-container setup (management.json) + + +This section applies to deployments using the older multi-container architecture. If you deployed using `getting-started.sh`, you are on the combined setup and should use the `config.yaml` instructions above. See the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + +Update your `management.json`: ```json { @@ -53,17 +85,7 @@ The embedded IdP is enabled by default when using the new [`getting-started.sh`] } ``` -### Configuration Options - -| Option | Description | Default | -|--------|-------------|---------| -| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) | -| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` | -| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated | - -### Environment Variables - -When using docker-compose, you can configure these via environment variables: +Or configure via environment variables on the `management` container: ```yaml environment: @@ -330,7 +352,7 @@ The embedded IdP encrypts sensitive user data at rest: | Name | AES-256-GCM | | Password | bcrypt hash (via Dex) | -The encryption key is configured in `management.json` and should be: +The encryption key is configured in `config.yaml` (`server.store.encryptionKey`) or `management.json` (`EncryptionKey`) for older multi-container setups. It should be: - Generated using a cryptographically secure random generator - Stored securely (not in version control) @@ -364,17 +386,23 @@ User authentication events are logged in the activity log: ### "Embedded IdP not available" error -Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted. +For the combined setup, the embedded IdP is always enabled. For older multi-container setups, ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and restart the Management service. ### Users can't log in -1. Check Management service logs: `docker compose logs management` +1. Check server logs: `docker compose logs netbird-server` (or `docker compose logs management` for older multi-container setups) 2. Verify the encryption key hasn't changed 3. Confirm the user exists: Check **Team** → **Users** in Dashboard ## Disabling Embedded IdP -To switch from embedded IdP to a (standalone) external IdP: + +The embedded IdP cannot be disabled in the combined setup. If you want to use only external identity providers, you can [disable local authentication](/selfhosted/identity-providers/disable-local-authentication) instead and add your external IdP through the Dashboard UI. + + +### Older multi-container setup (management.json) + +To switch from embedded IdP to a standalone external IdP on the older multi-container setup: 1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide) 2. Update `management.json`: diff --git a/src/pages/selfhosted/migration/coturn-to-stun-migration.mdx b/src/pages/selfhosted/migration/coturn-to-stun-migration.mdx index 21f56bd6..76bb01a6 100644 --- a/src/pages/selfhosted/migration/coturn-to-stun-migration.mdx +++ b/src/pages/selfhosted/migration/coturn-to-stun-migration.mdx @@ -2,6 +2,10 @@ This guide helps you migrate your existing NetBird self-hosted installation from using an external Coturn TURN server to the new embedded STUN server integrated into the relay service. + +This guide applies only to the **older multi-container setup** with separate `management`, `signal`, `relay`, and `coturn` containers configured via `management.json`. If you deployed using the [`getting-started.sh`](/selfhosted/selfhosted-quickstart) script (combined setup with `config.yaml`), STUN is already embedded — no migration is needed. If you are still on the older setup, consider migrating to the [combined container](/selfhosted/migration/combined-container) instead, which handles this automatically. + + **Who is this guide for?** This migration guide is intended for users who: - Have an existing NetBird self-hosted deployment with **Coturn configured for STUN** (NAT traversal) diff --git a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx index b9db6f04..cfbdfaae 100644 --- a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx +++ b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx @@ -244,7 +244,7 @@ The reverse proxy SSO feature authenticates users through an OAuth2/OIDC flow th If you want to keep using your current external identity provider, follow these three steps: -#### Step 1: Add callback URL to management.json +#### Step 1: Add callback URL to management.json (multi-container only) Add the `AuthCallbackURL` and `AuthClientID` fields to the `HttpConfig` section of your `management.json`: @@ -307,7 +307,7 @@ After configuring SSO for your external identity provider, verify it works: 3. Confirm you are redirected to your IdP login page 4. After authenticating, confirm you are redirected back to the service and can access it -If the redirect fails or you see an error from your IdP, double-check that the callback URL is correctly registered in both `management.json` and your identity provider's settings. +If the redirect fails or you see an error from your IdP, double-check that the callback URL is correctly registered in both your configuration (`management.json` for multi-container setups) and your identity provider's settings. ## Connecting through Traefik instead of Docker network diff --git a/src/pages/selfhosted/postgres-store.mdx b/src/pages/selfhosted/postgres-store.mdx index d1596856..656078b4 100644 --- a/src/pages/selfhosted/postgres-store.mdx +++ b/src/pages/selfhosted/postgres-store.mdx @@ -1,25 +1,75 @@ -# Management Postgresql store +# Management PostgreSQL store -## Using Postgres for fresh installations +PostgreSQL is recommended for production deployments. It supports concurrent access, enabling multiple management instances for high availability. -As of version 0.26.0, the default configuration for fresh installations is SQLite storage. -However, users have the option to leverage the benefits of Postgres for new instances beginning from version `0.27.8`. -To enable Postgres, add to your `setup.env` the following variable: +## Configuration + +### Combined setup (config.yaml) + +To use PostgreSQL, update your `config.yaml`: + +```yaml +server: + store: + engine: "postgres" + dsn: "host= user= password= dbname= port=" +``` + +You can also pass the DSN as an `NB_` environment variable on the `netbird-server` container in your `docker-compose.yml`: + +```yaml +environment: + - NB_STORE_ENGINE_POSTGRES_DSN=host= user= password= dbname= port= +``` + +Restart the server and confirm: +```bash +docker compose restart netbird-server +docker compose logs netbird-server +``` +You should see: +``` +INFO management/server/store.go:109: using Postgres store engine +``` + + +For a full list of available configuration options, see the [config.yaml.example](https://github.com/netbirdio/netbird/blob/main/combined/config.yaml.example) reference file. + + +### Older multi-container setup (management.json) + + +This section applies to deployments using the older multi-container architecture with separate `management`, `signal`, `relay`, and `coturn` containers. If you deployed using the [`getting-started.sh`](/selfhosted/selfhosted-quickstart) script, you are on the combined setup and should use the `config.yaml` instructions above. See the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + +To enable Postgres, add to your `setup.env`: ```bash NETBIRD_STORE_CONFIG_ENGINE=postgres ``` -This will result in a configuration similar to the following in your `management.json` file: +This sets the following in your `management.json`: ```json - "StoreConfig": { - "Engine": "postgres" - } +"StoreConfig": { + "Engine": "postgres" +} ``` -You can switch back to sqlite storage by setting the `NETBIRD_STORE_CONFIG_ENGINE` variable to `sqlite`. + +Create a `.env` file with the connection string: +```bash +NETBIRD_STORE_ENGINE_POSTGRES_DSN="host= user= password= dbname= port=" +``` + +Update `docker-compose.yml` to pass the config to the `management` container: +```yaml +environment: + - NETBIRD_STORE_ENGINE_POSTGRES_DSN=${NETBIRD_STORE_ENGINE_POSTGRES_DSN} +env_file: + - .env +``` + Switching between storage options requires migration steps to prevent data loss. - ## Migrating from SQLite store to Postgres store This migration process allows users to seamlessly transition between storage options while maintaining data integrity. @@ -28,14 +78,22 @@ This migration process allows users to seamlessly transition between storage opt 1. Backup your data store (`store.db` in `datadir` - default `/var/lib/netbird/`) + +For the combined setup: +```bash +mkdir backup +docker compose cp -a netbird-server:/var/lib/netbird/. backup/ +``` + +For the older multi-container setup: ```bash mkdir backup docker compose cp -a management:/var/lib/netbird/. backup/ ``` -2. Import Sqlite data to Postgres +2. Import SQLite data to Postgres -For migrating the Sqlite data we rely on the [pgloader](https://github.com/dimitri/pgloader) tool. You can install it by running +For migrating the SQLite data we rely on the [pgloader](https://github.com/dimitri/pgloader) tool. You can install it by running `sudo apt-get install pgloader` on debian or `brew install pgloader` on MacOS. ```bash @@ -68,74 +126,94 @@ DELETE FROM name_server_groups WHERE name_server_groups.account_id NOT IN (SELEC DROP TABLE IF EXISTS rules; ``` -4. Enable Postgres by updating the `management.json` file and setting the `Engine` field to `postgres` as the following example: +4. Enable Postgres in your configuration. + +For the combined setup, update `config.yaml`: +```yaml +server: + store: + engine: "postgres" + dsn: "host= user= password= dbname= port=" +``` + +For the older multi-container setup, update `management.json`: ```json "StoreConfig": { "Engine": "postgres" } ``` +And pass the DSN via environment variable as described in the [older multi-container setup](#older-multi-container-setup-managementjson) section above. -5. Create `.env` file with the following content: +5. Restart the server and confirm: + +For the combined setup: ```bash -NETBIRD_STORE_ENGINE_POSTGRES_DSN="host= user= password= dbname= port=" +docker compose restart netbird-server +docker compose logs netbird-server ``` -6. Update `docker-compose.yml` file to pass the postgres configuration to the `management` container -```yaml -environment: - - NETBIRD_STORE_ENGINE_POSTGRES_DSN=${NETBIRD_STORE_ENGINE_POSTGRES_DSN} -env_file: - - .env -``` - -7. Restart the management service +For the older multi-container setup: ```bash docker compose restart management -``` - -8. Check logs to confirm the store switch: -```bash docker compose logs management ``` + You should see an entry similar to: ``` -2024-05-10T15:09:34Z INFO management/server/store.go:109: using Postgres store engine +INFO management/server/store.go:109: using Postgres store engine ``` -## Rollback to Sqlite store -To rollback to the Sqlite store, follow these steps: - - The following commands assume you use the latest docker version with the compose plugin. If you have docker-compose installed as a standalone, please use docker-compose as a command. - +## Rollback to SQLite store +To rollback to the SQLite store, follow these steps: 1. Restore `store.db` backup + +For the combined setup: +```bash +docker compose cp backup/. netbird-server:/var/lib/netbird/ +``` + +For the older multi-container setup: ```bash docker compose cp backup/. management:/var/lib/netbird/ ``` -2. Enable SQLite by updating the `management.json` file and setting the `Engine` field to `sqlite` as the following example: +2. Switch the store engine back to SQLite. + +For the combined setup, update `config.yaml`: +```yaml +server: + store: + engine: "sqlite" +``` + +For the older multi-container setup, update `management.json`: ```json "StoreConfig": { "Engine": "sqlite" } ``` -3. Restart the Management service. +3. Restart the server and confirm: + +For the combined setup: ```bash -docker compose restart management +docker compose restart netbird-server +docker compose logs netbird-server ``` -4. Check logs to confirm the store switch: +For the older multi-container setup: ```bash +docker compose restart management docker compose logs management ``` You should see an entry similar to: ``` -2024-05-10T15:09:34Z INFO management/server/store.go:109: using SQLite file store engine +INFO management/server/store.go:109: using SQLite file store engine ``` -## Optional Rollback Postgres data to Sqlite +## Optional Rollback Postgres data to SQLite This is optional and should be used only if you want to rollback the data from Postgres to SQLite while running the same NetBird version. For migrating the Postgres data, we rely on the `pg_dump`, `sed`, and `sqlite3` tools. Make sure these are installed before proceeding @@ -145,7 +223,7 @@ For migrating the Postgres data, we rely on the `pg_dump`, `sed`, and `sqlite3` pg_dump --data-only --column-inserts "postgresql://:@:/" > data.sql ``` -2. Convert exported Postgres data sql to Sqlite format +2. Convert exported Postgres data sql to SQLite format ```bash sed \ -e 's/\\\\:/\:/g' \ @@ -159,39 +237,26 @@ sed \ -e '/^[[:space:]]*SELECT/d' data.sql > data.sql ``` -3. Generate database schema from Sqlite backup +3. Generate database schema from SQLite backup ```bash sqlite3 backup/store.db '.schema' > schema.sql ```` -4. Create Sqlite database with Postgres exported data +4. Create SQLite database with Postgres exported data ```bash sqlite3 store.db '.read schema.sql' && sqlite3 store.db '.read data.sql' ``` -5. Copy db to the management container +5. Copy db to the container + +For the combined setup: +```bash +docker compose cp store.db netbird-server:/var/lib/netbird/store.db +``` + +For the older multi-container setup: ```bash docker compose cp store.db management:/var/lib/netbird/store.db ``` -6. Enable SQLite by updating the `management.json` file and setting the `Engine` field to `sqlite` as the following example: -```json -"StoreConfig": { - "Engine": "sqlite" -} -``` - -7. Restart the Management service. -```bash -docker compose restart management -``` - -8. Check logs to confirm the store switch: -```bash -docker compose logs management -``` - -You should see an entry similar to: -``` -2024-05-10T15:09:34Z INFO management/server/store.go:109: using SQLite file store engine -``` +6. Switch the store engine back to SQLite using the instructions in the [Rollback to SQLite store](#rollback-to-sqlite-store) section above. \ No newline at end of file diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx index 8a5195f7..2b903aad 100644 --- a/src/pages/selfhosted/selfhosted-guide.mdx +++ b/src/pages/selfhosted/selfhosted-guide.mdx @@ -7,6 +7,10 @@ a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/cot If you would like to learn more about the architecture please refer to the [architecture section](/about-netbird/how-netbird-works). + +This guide uses the **older multi-container architecture** with separate `management`, `signal`, `relay`, and `coturn` containers, configured via `management.json`. For new deployments, the [Quickstart guide](/selfhosted/selfhosted-quickstart) uses the **combined setup** with a single `netbird-server` container and `config.yaml`. If you are on the older setup, see the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + **New to self-hosting?** The [Quickstart guide](/selfhosted/selfhosted-quickstart) uses the built-in identity provider and is the fastest way to get started. This advanced guide is for users who need to integrate with an existing IdP or have specific enterprise requirements. diff --git a/src/pages/selfhosted/sqlite-store.mdx b/src/pages/selfhosted/sqlite-store.mdx index 44c44239..7b6d75e6 100644 --- a/src/pages/selfhosted/sqlite-store.mdx +++ b/src/pages/selfhosted/sqlite-store.mdx @@ -1,21 +1,9 @@ # Management SQLite store -In NetBird, the Management system traditionally relies on JSON file storage. +SQLite is the default storage engine for NetBird Management. It requires no external dependencies and works out of the box for new installations. -Starting from version [0.24.0](https://github.com/netbirdio/netbird/releases/tag/v0.24.0), -we have introduced support for SQLite. -This addition aims to provide users with enhanced performance and scalability options. - - - -Starting from version [0.26.0](https://github.com/netbirdio/netbird/releases/tag/v0.26.0), -SQLite is **the default** storage engine for new installations. -Please follow this manual if you insist on migrating from JSON file storage. -If you have new installation you already have SQLite. To confirm please check the `management` logs on startup: -``` -2024-02-06T15:28:04Z INFO management/server/store.go:77: using SQLite store engine -``` +If you need concurrent access or high availability with multiple management instances, consider using [PostgreSQL](/selfhosted/postgres-store) instead. ## SQLite entity relationship diagram @@ -26,27 +14,59 @@ For a high-level overview of the SQLite schema, refer to the Entity Relationship high-level-dia

-## Using SQLite for fresh installations +## Configuration -As of version 0.24.0, the default configuration for fresh installations is JSON file storage. -However, users have the option to leverage the benefits of SQLite for new instances. -To enable SQLite, add to your setup.env the following variable: +### Combined setup (config.yaml) + +SQLite is the default engine. If you need to explicitly set it in your `config.yaml`: + +```yaml +server: + store: + engine: "sqlite" +``` + +Confirm SQLite is active by checking the server logs on startup: +```bash +docker compose logs netbird-server +``` +You should see: +``` +INFO management/server/store.go:77: using SQLite store engine +``` + + +For a full list of available configuration options, see the [config.yaml.example](https://github.com/netbirdio/netbird/blob/main/combined/config.yaml.example) reference file. + + +### Older multi-container setup (management.json) + + +This section applies to deployments using the older multi-container architecture with separate `management`, `signal`, `relay`, and `coturn` containers. If you deployed using the [`getting-started.sh`](/selfhosted/selfhosted-quickstart) script, you are on the combined setup and should use the `config.yaml` instructions above. See the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + +To enable SQLite, add to your `setup.env`: ```bash NETBIRD_STORE_CONFIG_ENGINE=sqlite ``` -This will result in a configuration similar to the following in your management.json file: +This sets the following in your `management.json`: ```json "StoreConfig": { "Engine": "sqlite" } ``` -You can switch back to JSON file storage by setting the `NETBIRD_STORE_CONFIG_ENGINE` variable to `jsonfile`. - - Switching between storage options requires migration steps to prevent data loss. - ## Migrating from JSON store to SQLite store -This migration process allows users to seamlessly transition between storage options while maintaining data integrity. + + +This migration only applies to the older multi-container setup. The combined setup has always used SQLite by default and does not support JSON file storage. + + + +Since version [0.28.0](https://github.com/netbirdio/netbird/releases/tag/v0.28.0), support for JSON file storage has been removed. All installations should be on SQLite or PostgreSQL. + + +This migration process allows users to seamlessly transition from JSON file storage to SQLite while maintaining data integrity. Ensure that you are running the commands described below after upgrading to version 0.24.0 or later. ### Migration commands @@ -102,7 +122,7 @@ To migrate from JSON file store to SQLite, follow these steps: ```bash docker exec -it netbird-management /go/bin/netbird-mgmt sqlite-migration upgrade --log-file console ``` -5. Enable SQLite by updating the management.json file and setting the `Engine` field to `sqlite` as the following example: +5. Enable SQLite by updating the `management.json` file and setting the `Engine` field to `sqlite`: ```json "StoreConfig": { "Engine": "sqlite" @@ -119,49 +139,4 @@ To migrate from JSON file store to SQLite, follow these steps: You should see an entry similar to: ``` 2023-10-19T18:55:29Z INFO management/server/store.go:75: using SQLite store engine -``` - -### Rollback to JSON file store - -Since version [0.28.0](https://github.com/netbirdio/netbird/releases/tag/v0.28.0), support for JSON file storage has been removed, and the option to roll back to JSON store is no longer supported. - - -To rollback to the JSON file store, follow these steps: - - The following commands assume you use the latest docker version with the compose plugin. If you have docker-compose installed as a standalone, please use docker-compose as a command. - -1. After accessing the path that contains your docker-compose.yml and management.json files, stop the NetBird Management service. -```bash - docker compose stop management -``` -2. Backup your data store (`store.db` in `datadir` - default "/var/lib/netbird/"). -```bash - mkdir backup - docker compose cp -a management:/var/lib/netbird/ backup/ -``` -3. Start NetBird Management service: -```bash - docker compose start management -``` -4. Run the migration to SQLite subcommand: -```bash - docker exec -it netbird-management /go/bin/netbird-mgmt sqlite-migration downgrade --log-file console -``` -5. Enable JSON file by updating the management.json file and setting the `Engine` field to `jsonfile` as the following example: -```json - "StoreConfig": { - "Engine": "jsonfile" - } -``` -6. Restart the Management service. -```bash - docker compose restart management -``` -7. Check logs to confirm the store switch: -```bash - docker compose logs management -``` -You should see an entry similar to: -``` -2023-10-19T18:55:29Z INFO management/server/store.go:72: using JSON file store engine -``` +``` \ No newline at end of file diff --git a/src/pages/selfhosted/troubleshooting.mdx b/src/pages/selfhosted/troubleshooting.mdx index e1864c6c..bf0d6d90 100644 --- a/src/pages/selfhosted/troubleshooting.mdx +++ b/src/pages/selfhosted/troubleshooting.mdx @@ -54,7 +54,8 @@ This page will help with various issues when self-hosting NetBird. **Solution**: This tab is only visible when the embedded IdP is enabled. Check your deployment configuration: - For quickstart deployments, the embedded IdP should be enabled by default -- For advanced deployments, ensure `EmbeddedIdP.Enabled` is set to `true` in management.json +- For the combined setup, the embedded IdP is always enabled +- For older multi-container deployments, ensure `EmbeddedIdP.Enabled` is set to `true` in `management.json` ### Users not syncing from SSO provider @@ -74,7 +75,7 @@ To test your TURN configuration you can access the [online tester](https://webrt There you will find a ICE servers input box, where you can select and remove the existing server, then add your turn server configuration as follows: -Please replace netbird.DOMAIN.com and PASSWORD with the information from the management.json TURNConfig, then click on Add server. +Please replace netbird.DOMAIN.com and PASSWORD with your STUN/TURN server details from your configuration (config.yaml for the combined setup, or the TURNConfig section in management.json for older multi-container setups), then click on Add server.

turn