From 8046beee03a6378c0650571903e68a694697cda7 Mon Sep 17 00:00:00 2001 From: Maycon Santos Date: Thu, 19 Oct 2023 21:09:46 +0200 Subject: [PATCH] Update SQLite docs (#107) --------- Co-authored-by: braginini --- src/components/NavigationDocs.jsx | 3 +- src/pages/selfhosted/sqlite-store.mdx | 144 +++++++++++++++++++------- 2 files changed, 109 insertions(+), 38 deletions(-) diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 7e9a97d3..3d010150 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -38,8 +38,7 @@ export const docsNavigation = [ links: [ { title: 'Quickstart guide', href: '/selfhosted/selfhosted-quickstart' }, { title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' }, - // hide the sqlite guid as this is work in progress - //{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store'}, + { title: 'Management SQLite Store', href: '/selfhosted/sqlite-store'}, { title: 'Supported IdPs', href: '/selfhosted/identity-providers' }, ], }, diff --git a/src/pages/selfhosted/sqlite-store.mdx b/src/pages/selfhosted/sqlite-store.mdx index cbbaa951..fd39a25b 100644 --- a/src/pages/selfhosted/sqlite-store.mdx +++ b/src/pages/selfhosted/sqlite-store.mdx @@ -1,10 +1,10 @@ -# Management SQLite Store +# Management SQLite store -In NetBird, the management system traditionally relies on JSON file storage. -Starting from version 0.24.0, we have introduced **experimental** support for SQLite. +In NetBird, the Management system traditionally relies on JSON file storage. +Starting from version [0.24.0](https://github.com/netbirdio/netbird/releases/tag/v0.24.0), we have introduced **experimental** support for SQLite. This addition aims to provide users with enhanced performance and scalability options. -## SQLite Entity Relationship Diagram +## SQLite entity relationship diagram For a high-level overview of the SQLite schema, refer to the Entity Relationship Diagram (ERD) below: @@ -12,28 +12,40 @@ For a high-level overview of the SQLite schema, refer to the Entity Relationship high-level-dia

-## Using SQLite for Fresh Installations +## Using SQLite for fresh installations 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, update your management.json as follows: - +To enable SQLite, add to your setup.env the following variable: +```bash +NETBIRD_STORE_CONFIG_ENGINE=sqlite +``` +This will result in a configuration similar to the following in your management.json file: ```json - "StoreKind": "Sqlite", + "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. + -Alternatively, you can explicitly set the store to JSON file storage: +## Migrating from JSON store to SQLite store +This migration process allows users to seamlessly transition between storage options while maintaining data integrity. +Ensure that you are running the commands described below after upgrading to version 0.24.0 or later. -```json - "StoreKind": "JsonFile", +### Migration commands + +Starting from version 0.24.0, NetBird Management provides a subcommand to facilitate migration to SQLite. This command is part of the binary shipped within the official docker image. + + 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. + +```bash +$ docker compose exec management /go/bin/netbird-mgmt sqlite-migration ``` - -## Migration from JSON Store - -Starting from version 0.24.0, NetBird management provides a subcommand to facilitate migration to SQLite: - -``` -$ netbird-mgmt sqlite-migration +This will produce an output similar to: +```bash Contains sub-commands to perform JSON file store to SQLite store migration and rollback Usage: @@ -54,24 +66,84 @@ Global Flags: Use "netbird-mgmt sqlite-migration [command] --help" for more information about a command. ``` -Follow these steps for migration: - -1. Stop NetBird management service. +### Follow these steps for migration: +To migrate from JSON file store to SQLite, 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.json` in `datadir` - default "/var/lib/netbird/"). -3. Run the migration to SQLite subcommand. Example: `netbird-mgmt sqlite-migration upgrade --log-file console` -4. Enable SQLite in management following [the instruction in the previous section](#using-sq-lite-for-fresh-installations). -5. Run NetBird management service. - - -## Rollback to JSON File Store +```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 compose exec 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: +```json + "StoreConfig": { + "Engine": "sqlite" + } +``` +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:75: using SQLite store engine +``` +### Rollback to JSON file store To rollback to the JSON file store, follow these steps: - -1. Stop the NetBird management service. -2. Backup your SQLite data store (`store.db` in `datadir` - default "/var/lib/netbird/"). -3. Run the rollback to JSON file subcommand (Example: `netbird-mgmt sqlite-migration downgrade --log-file console`). -4. Enable JSON file store in management following [the instructions for fresh installations](#using-sq-lite-for-fresh-installations). -5. Restart the NetBird management service. - -This migration process allows users to seamlessly transition between storage options while maintaining data integrity. -Ensure you perform backups before any migration or rollback operations. \ No newline at end of file + + 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 compose exec 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