diff --git a/doc/2/api/controllers/security/create-first-admin/index.md b/doc/2/api/controllers/security/create-first-admin/index.md index fe2eca7a53..8b0683cdaa 100644 --- a/doc/2/api/controllers/security/create-first-admin/index.md +++ b/doc/2/api/controllers/security/create-first-admin/index.md @@ -15,7 +15,7 @@ Creates a Kuzzle administrator account, only if none exist. ### HTTP ```http -URL: http://kuzzle:7512//_createFirstAdmin[?reset] +URL: http://kuzzle:7512/_createFirstAdmin/[?reset] URL(2): http://kuzzle:7512/_createFirstAdmin[?reset] Method: POST Body: diff --git a/doc/2/guides/elasticsearch/migrate-project-from-v7-to-v8/index.md b/doc/2/guides/elasticsearch/migrate-project-from-v7-to-v8/index.md index c586cf31f8..2959a2b70d 100644 --- a/doc/2/guides/elasticsearch/migrate-project-from-v7-to-v8/index.md +++ b/doc/2/guides/elasticsearch/migrate-project-from-v7-to-v8/index.md @@ -1,94 +1,57 @@ --- code: false type: page -order: 50 -title: Migrate to Elasticsearch 8 | Elasticsearch | Guide | Core +order: 200 +title: Elasticsearch 8 | Elasticsearch | Guide | Core meta: - name: description - content: Migrate your Kuzzle project from Elasticsearch 7 to Elasticsearch 8 + content: Configure Kuzzle to use Elasticsearch 8 - name: keywords content: Kuzzle, Documentation, kuzzle write pluggins, General purpose backend, iot, backend, opensource, API Controllers --- -# Migrate a project from Elasticsearch 7 to Elasticsearch 8 +# Elasticsearch 8 - + -Kuzzle relies on Elasticsearch as a [NoSQL document store](/core/2/guides/main-concepts/data-storage). -The support of Elasticsearch 8 has been introduced in Kuzzle 2.30.0. +## Migrating production data from Elasticsearch 7 to 8 -To avoid any breaking changes around the support of Elasticsearch 8, we kept Kuzzle working seemlessly with Elasticsearch 7 and Elasticsearch 8. +Is this section, we will see how to migrate a production environnement data from Elasticsearch 7.x to Elasticsearch 8.x -The use of Elasticsearch 8 is an **opt-in** option, so no modification is needed on your behalf if you want to keep using Elasticsearch 7. +### Prerequisites -The default major version of Elasticsearch will be 7 until the next major version of Kuzzle that would ne Kuzzle v3. +Before starting the migration process, ensure the following: +* __Backup your data__: Always backup your indices and cluster settings before starting the migration. Use the Snapshot and Restore feature for this. +* __Version Check__: Make sure your Elasticsearch 7.x is at the latest minor version. Elasticsearch supports migrating from the last minor version of the previous major version. -## How to setup your project to use Elasticsearch 8 +### Check Deprecation API -### Setup Kuzzle to use Elasticsearch 8 +* Elasticsearch Deprecation API can be used to check for any features or settings in your current cluster that are deprecated or removed in the 8.x version. Address these issues before proceeding. +* Test in a **Non-Production Environment** +Conduct a dry run in a development environment to spot potential issues and estimate the duration the migration process might take. -#### Upgrade the npm package -First you need to upgrade you Kuzzle package to version `>= 2.30.0-es8` in the `package.json` file. Then run `npm install` to upgrade the packages for you application. +### Migration Methods -### Configure Kuzzle -A new configuration key `majorVersion` has been introduced ine the `storageEngine` section to allow the selection of the Eleasticsearch version you want to support for your project. +Theire are 2 strategies to upgrade Elasticsearch in a production environment: +1. Re-indexing + * Step 1: Create a new cluster running Elasticsearch 8.x. + * Step 2: Take a snapshot of your data in the current 7.x cluster. + * Step 3: Restore the snapshot into the new 8.x cluster. +1. Rolling Upgrade + * Step 1: Disable Shard Allocation. + * Step 2: Stop and upgrade a single Elasticsearch node. + * Step 3: Enable Shard Allocation and allow the node to join the cluster and the cluster to re-balance. + * Step 4: Repeat for each node in the cluster. -When not specified, it will be considered to be version 7, specify 8 if you want to switch Kuzzle to support Elasticasearch 8. +After you have migrated your data: +1. Post Upgrade Checks + * Run the health and stats APIs to ensure the health of your newly upgraded cluster. + * Update your clients and integrations to the latest version that's compatible with Elasticsearch 8.x, if not done already. + * Monitor your cluster using the Monitoring API or third-party monitoring services. +1. Troubleshoot + * If you encounter any issues during the migration process, take advantage of the Elasticsearch documentation, forums, and issue trackers for troubleshooting information and support. -This has to be add to you kuzzlerc file, or provided via an environnement variable (see RC doc for details on kuzzlerc configation options) +> Note: Migration steps can vary depending on your setup and needs. Always refer to the official Elasticsearch documentation for the most accurate information, you can find it [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html). -```json -{ - "services": { - "storageEngine": { - "majorVersion": 8 - } - } -} -``` - -:::warning -You can not set the `majorVersion` key to 8 if you are using a version of Kuzzle that does not support it. (older versions of Kuzzle won't complain about this value) -::: - -:::info -Kuzzle cannot connect to both Elasticsearch 7 and Elasticsearch 8 at the same time. -::: - -Once the version is set to 8, Kuzzle will use the Elasticsearch 8 API to communicate with the database. - -### Launch Elasticsearch 8 (dev environnement) - -Next you will have to change the docker-compose.yml file so that it pulls Elasticsearch 8 image with the recommanded configuration to work with Kuzzle - -You can replace the original `elasticsearch` section with the following exemple - -```yaml - elasticsearch: - image: elasticsearch:8.11.3 - container_name: kuzzle_elasticsearch - environment: - - xpack.security.enabled=false - - action.destructive_requires_name=false - - cluster.name=kuzzle - - node.name=alyx - - discovery.type=single-node - - ingest.geoip.downloader.enabled=false - - indices.id_field_data.enabled=true - ports: - - '9200:9200' - healthcheck: - test: ['CMD', 'curl', '-f', 'http://localhost:9200'] - interval: 2s - timeout: 2s - retries: 10 - ulimits: - nofile: 65536 -``` - -### Data migration - -In the context of running the project in a development envinronnement, you can run your usual initialisation scripts as usual, or use Kourou to dump data from the project still running on Elasticsearch 7 and import them when you are done with setuping the project to run with Elasticsearch 8. - -In the context of an hosted environment such as pre-prodcution or production environnement, we recommand following this guide. +Disclaimer: The above steps provide a general migration guide. Migrations can be complex and it's advised to always test these steps in a **non-production environment** before applying them to production. diff --git a/doc/2/guides/elasticsearch/v8/index.md b/doc/2/guides/elasticsearch/v8/index.md index a1fb49cfa2..9100428083 100644 --- a/doc/2/guides/elasticsearch/v8/index.md +++ b/doc/2/guides/elasticsearch/v8/index.md @@ -2,17 +2,17 @@ code: false type: page order: 100 -title: Elasticsearch 8 | Elasticsearch | Guide | Core +title: Migrate to Elasticsearch 8 | Elasticsearch | Guide | Core meta: - name: description - content: Configure Kuzzle to use Elasticsearch 8 + content: Migrate your Kuzzle project from Elasticsearch 7 to Elasticsearch 8 - name: keywords content: Kuzzle, Documentation, kuzzle write pluggins, General purpose backend, iot, backend, opensource, API Controllers --- -# Elasticsearch 8 +# Elasticsearch 8 support - + Kuzzle uses Elasticsearch as a [NoSQL document store](/core/2/guides/main-concepts/data-storage). @@ -117,43 +117,29 @@ services: Or you can run `kourou app:scaffold sandbox` to create a new Kuzzle project with a `docker-compose.yml` file that uses Elasticsearch 8. -## Migrating production data from Elasticsearch 7 to 8 +## Inside a kuberenetes cluster -Is this section, we will see how to migration en production environnement data from Elasticsearch 7.x to Elasticsearch 8.x +While running Kuzzle inside a Kubernetes cluster, you can use the following configuration to run Kuzzle with Elasticsearch 8: -### Prerequisites - -Before starting the migration process, ensure the following: -* __Backup your data__: Always backup your indices and cluster settings before starting the migration. Use the Snapshot and Restore feature for this. -* __Version Check__: Make sure your Elasticsearch 7.x is at the latest minor version. Elasticsearch supports migrating from the last minor version of the previous major version. - -### Check Deprecation API - -* Elasticsearch Deprecation API can be used to check for any features or settings in your current cluster that are deprecated or removed in the 8.x version. Address these issues before proceeding. -* Test in a **Non-Production Environment** -Conduct a dry run in a development environment to spot potential issues and estimate the duration the migration process might take. - -### Migration Methods - -Theire are 2 strategies to upgrade Elasticsearch in a production environment: -1. Re-indexing - * Step 1: Create a new cluster running Elasticsearch 8.x. - * Step 2: Take a snapshot of your data in the current 7.x cluster. - * Step 3: Restore the snapshot into the new 8.x cluster. -1. Rolling Upgrade - * Step 1: Disable Shard Allocation. - * Step 2: Stop and upgrade a single Elasticsearch node. - * Step 3: Enable Shard Allocation and allow the node to join the cluster and the cluster to re-balance. - * Step 4: Repeat for each node in the cluster. - -After you have migrated your data: -1. Post Upgrade Checks - * Run the health and stats APIs to ensure the health of your newly upgraded cluster. - * Update your clients and integrations to the latest version that's compatible with Elasticsearch 8.x, if not done already. - * Monitor your cluster using the Monitoring API or third-party monitoring services. -1. Troubleshoot - * If you encounter any issues during the migration process, take advantage of the Elasticsearch documentation, forums, and issue trackers for troubleshooting information and support. - -> Note: Migration steps can vary depending on your setup and needs. Always refer to the official Elasticsearch documentation for the most accurate information, you can find it [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html). +```yaml + # SSL/TLS Configuration + - name: kuzzle_services__storageEngine__client__tls__ca + valueFrom: + secretKeyRef: + name: elasticsearch-master-certs + key: ca.crt + - name: kuzzle_services__storageEngine__client__tls__rejectUnauthorized + value: "false" + - name: kuzzle_services__storageEngine__client__tls__cert + valueFrom: + secretKeyRef: + name: elasticsearch-master-certs + key: tls.crt + - name: kuzzle_services__storageEngine__client__tls__key + valueFrom: + secretKeyRef: + name: elasticsearch-master-certs + key: tls.key +``` -Disclaimer: The above steps provide a general migration guide. Migrations can be complex and it's advised to always test these steps in a **non-production environment** before applying them to production. +This will allow Kuzzle to connect to Elasticsearch 8 using a secure connection. \ No newline at end of file diff --git a/doc/2/guides/getting-started/authenticate-users/index.md b/doc/2/guides/getting-started/authenticate-users/index.md index 1d980fa1e1..4c9350de35 100644 --- a/doc/2/guides/getting-started/authenticate-users/index.md +++ b/doc/2/guides/getting-started/authenticate-users/index.md @@ -49,40 +49,88 @@ We saw that in the [Set Up Permission](/core/2/guides/getting-started/set-up-per ``` ::: warning -New authentication strategies are made available by [authentication plugins](/core/2/guides/write-plugins/integrate-authentication-strategy). +New authentication strategies are made available by [authentication plugins](/core/2/guides/write-plugins/integrate-authentication-strategy). -By default, only the [local strategy](/core/2/guides/main-concepts/authentication#local-strategy) is available. +By default, only the [local strategy](/core/2/guides/main-concepts/authentication#local-strategy) is available. We also provide an authentication plugin for the [OAuth strategy](/core/2/guides/main-concepts/authentication#oauth-strategy) but it's not available by default and need to be [added to your application](/core/2/guides/develop-on-kuzzle/external-plugins). ::: ### Getting an authentication token -Kuzzle uses **authentication tokens** to identify user sessions. +Kuzzle uses **authentication tokens** to identify user sessions. First we need to get one with the [auth:login](/core/2/api/controllers/auth/login) action. This action takes the `strategy` used as a mean to authenticate, and any additional information needed by that strategy. In our example we will use the [local](/core/2/guides/main-concepts/authentication#local-strategy) strategy so we have to provide a `username` and a `password`: +We previously created a user with the username `melis` and the password `password`. If you don't have this user, you can create it with the following command: + +```bash +kourou security:createUser '{ + content: { + profileIds: ["default"] + }, + credentials: { + local: { + username: "melis", + password: "password" + } + } +}' +``` + +Then we can log in with the following command: + +#### Using API + +```bash +curl -XPOST 'http://localhost:7512/_login/local' \ + -H 'Content-Type: application/json' \ + -d '{ + "username": "melis", + "password": "password" +}' + +## Response +{ + "action": "login", + "controller": "auth", + "error": null, + "headers": {}, + "node": "knode-glamorous-flaubert-1113", + "requestId": "688feaf7-d720-4d23-9ba6-cc43487f0108", + "result": { + "_id": "kuid-tricky-comedian-10492", + "expiresAt": 1729776561843, + "jwt": "kauth-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJrdWlkLXRyaWNreS1jb21lZGlhbi0xMDQ5MiIsImlhdCI6MTcyOTc3Mjk2MSwiZXhwIjoxNzI5Nzc2NTYxfQ.m_c8h3aLxqOa45afgFgowRnQ5f4uSPG3QVKDW1taYak", + "ttl": 3600000 + }, + "status": 200, + "volatile": null +} +``` + +#### Using CLI + ```bash kourou auth:login -a strategy=local --body '{ username: "melis", password: "password" }' -``` -```bash -[ℹ] Unknown command "auth:login", fallback to API method - +## Response +[ℹ] Unknown command "auth:login", fallback to API action + 🚀 Kourou - Executes an API query. - - [ℹ] Connecting to http://localhost:7512 ... - { - "_id": "62843356-d826-42fb-adf1-e930e90b6006", - "expiresAt": 1602600225701, - "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2Mjg0MzM1Ni1kODI2LTQyZmItYWRmMS1lOTMwZTkwYjYwMDYiLCJpYXQiOjE2MDI1OTY2MjUsImV4cCI6MTYwMjYwMDIyNX0.0HZF_AhyTzPCRxdaMbT6hlwLflYG4emmLlTD6YV_Nmo", + + [ℹ] Connecting to ws://localhost:7512 ... +{ + "_id": "kuid-tricky-comedian-10492", + "expiresAt": 1729776399610, + "jwt": "kauth-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJrdWlkLXRyaWNreS1jb21lZGlhbi0xMDQ5MiIsImlhdCI6MTcyOTc3Mjc5OSwiZXhwIjoxNzI5Nzc2Mzk5fQ.9rBVc4h6hV3Rsb0Z6kvLKhlZNxI-9O7xeWJnC6LfCEQ", "ttl": 3600000 - } +} [✔] Successfully executed "auth:login" ``` @@ -102,23 +150,19 @@ Now that we have a token, we must pass it to API requests, either in the **HTTP When using Kourou with `--username` and `--password` flags, the [auth:login](/core/2/api/controllers/auth/login) action is called and the received token is automatically used along with subsequent requests. ::: - -:::: tabs -::: tab Kourou +#### Using API ```bash -kourou auth:getCurrentUser -a jwt= +curl -H "Authorization: Bearer " http://localhost:7512/_me ``` -::: -::: tab HTTP +#### Using CLI -``` bash -curl -H "Authorization: Bearer " http://localhost:7512/_me +```bash +kourou auth:getCurrentUser -a jwt= ``` -::: -::: tab WebSocket +#### Using Websocket ```bash npx wscat -c ws://localhost:7512 --execute '{ @@ -128,14 +172,11 @@ npx wscat -c ws://localhost:7512 --execute '{ }' ``` -::: - -::: tab Javascript +#### Using javascript SDK ```bash kourou sdk:execute ' sdk.jwt = ""; - console.log(await sdk.auth.getCurrentUser()); ' ``` @@ -143,12 +184,9 @@ kourou sdk:execute ' ::: info Kourou is able to [execute](https://github.com/kuzzleio/kourou/blob/master/README.md#kourou-sdkexecute-code) Javascript code snippets. A `sdk` variable is exposed and refers to an instance of the [Javascript SDK](/sdk/js/7), connected to Kuzzle and authenticated if credentials are provided. -::: - -:::: +::: - diff --git a/doc/2/guides/getting-started/run-kuzzle/index.md b/doc/2/guides/getting-started/run-kuzzle/index.md index 2ea68cf754..2cbcc22b83 100644 --- a/doc/2/guides/getting-started/run-kuzzle/index.md +++ b/doc/2/guides/getting-started/run-kuzzle/index.md @@ -25,9 +25,8 @@ It is recommended to use Node Version Manager to avoid rights problems when usin You can install NVM with the one-liner script documented on [NVM Github repository](https://github.com/nvm-sh/nvm#install--update-script) ::: -- [Node.js <= 18](https://nodejs.org/en/download/) +- [Node.js >= 16](https://nodejs.org/en/download/) - [Docker](https://docs.docker.com/engine/install/) -- [Docker Compose](https://docs.docker.com/compose/install/) - [Kourou](https://github.com/kuzzleio/kourou) @@ -118,14 +117,14 @@ Now visit [http://localhost:7512](http://localhost:7512) with your browser. You ### Admin Console -You can also use the [Admin Console](https://next-console.kuzzle.io) which allows you to manage your data, your users and your rights. +You can also use the [Admin Console](https://console.kuzzle.io) which allows you to manage your data, your users and your rights. ::: info The Admin Console is a [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) written in Vue.js and using the [Javascript SDK](/sdk/js/7). No data related to your connection to Kuzzle will pass through our servers. ::: -First, we need to setup a new connection to a Kuzzle application. Open the [Admin Console](http://next-console.kuzzle.io) in your browser and then fill the form as follows: +First, we need to setup a new connection to a Kuzzle application. Open the [Admin Console](http://console.kuzzle.io) in your browser and then fill the form as follows: ![Admin Console create connection form](./admin-console-create-connection.png) @@ -154,7 +153,6 @@ The minimum rights required for an user to connect to the Kuzzle Admin Console a } } ``` - ::: Roles` section of the [Admin Console](http://next-console.kuzzle.io) @@ -53,12 +143,93 @@ You should see your newly created role in the `Security > Roles` section of the Then, we are going to create a profile which uses our newly created role. For this we will use the [security:createProfile](/core/2/api/controllers/security/create-profile) action: +#### Using the API + +```bash +curl -XPOST http://localhost:7512/profiles/dummyProfila/_create \ + -H 'Content-Type: application/json'\ + -d '{ + "policies": [ + { + "roleId": "dummyRole" + } + ] +}' + +## Response +{ + "action": "createProfile", + "controller": "security", + "error": null, + "headers": {}, + "node": "knode-debonair-sappho-15470", + "requestId": "c6e39111-e159-4f59-b9df-39ae6e7fe57d", + "result": { + "_id": "dummyProfila", + "_source": { + "policies": [ + { + "roleId": "dummyRole" + } + ], + "optimizedPolicies": [ + { + "roleId": "dummyRole" + } + ], + "rateLimit": 0, + "_kuzzle_info": { + "author": null, + "createdAt": 1729759906098, + "updatedAt": null, + "updater": null + } + } + }, + "status": 200, + "volatile": null +} +``` + +#### Using the CLI + ```bash kourou security:createProfile '{ policies: [ { roleId: "dummyRole" } ] }' --id dummyProfile + +## Response + +[ℹ] Unknown command "security:createProfile", fallback to API action + + 🚀 Kourou - Executes an API query. + + [ℹ] Connecting to ws://localhost:7512 ... +{ + "_id": "dummyProfile", + "_source": { + "policies": [ + { + "roleId": "dummyRole" + } + ], + "optimizedPolicies": [ + { + "roleId": "dummyRole" + } + ], + "rateLimit": 0, + "_kuzzle_info": { + "author": null, + "createdAt": 1729759867050, + "updatedAt": null, + "updater": null + } + } +} + [✔] Successfully executed "security:createProfile" ``` Now we have a `dummyProfile` profile which gives access to the API actions allowed by the `dummyRole` role. @@ -74,6 +245,52 @@ Finally, we need a user attached to the `dummyProfile` profile. The API action t Users need to have at least one assigned profile. We also will have to give our user some credentials to be able to log in with it. For this we will use the [security:createUser](/core/2/api/controllers/security/create-user) action: + +#### Using the API + +```bash +curl -XPOST http://localhost:7512/users/dummyUser/_create \ + -H 'Content-Type: application/json'\ + -d '{ + "content": { + "profileIds": ["dummyProfile"] + }, + "credentials": { + "local": { + "username": "melis", + "password": "password" + } + } +}' + +## Response +{ + "action": "createUser", + "controller": "security", + "error": null, + "headers": {}, + "node": "knode-debonair-sappho-15470", + "requestId": "1462ec9e-fc86-4b5c-8f56-3ae571855ae2", + "result": { + "_id": "dummyUser", + "_source": { + "profileIds": [ + "dummyProfile" + ], + "_kuzzle_info": { + "createdAt": 1729760009801, + "updatedAt": null, + "updater": null + } + } + }, + "status": 200, + "volatile": null +} +``` + +#### Using the CLI + ```bash kourou security:createUser '{ content: { @@ -86,6 +303,27 @@ kourou security:createUser '{ } } }' + +## Response +[ℹ] Unknown command "security:createUser", fallback to API action + + 🚀 Kourou - Executes an API query. + + [ℹ] Connecting to ws://localhost:7512 ... +{ + "_id": "kuid-heady-ant-28136", + "_source": { + "profileIds": [ + "dummyProfile" + ], + "_kuzzle_info": { + "createdAt": 1729759961940, + "updatedAt": null, + "updater": null + } + } +} + [✔] Successfully executed "security:createUser" ``` You should see your newly created role in the `Security > Users` section of the [Admin Console](http://next-console.kuzzle.io) @@ -111,6 +349,48 @@ The `reset` option allows to restrict `anonymous` default rights in the same tim This way you can always access the complete API through this admin account. +#### Using the API + +```bash +curl -XPOST http://localhost:7512/_createFirstAdmin/admin?reset=true \ + -H 'Content-Type: application/json'\ + -d '{ + "credentials": { + "local": { + "username": "admin", + "password": "password" + } + } +}' + +## Response +{ + "action": "createFirstAdmin", + "controller": "security", + "error": null, + "headers": {}, + "node": "knode-glamorous-flaubert-1113", + "requestId": "ea60961d-5446-42d8-8438-3d4aecff6bdf", + "result": { + "_id": "admin", + "_source": { + "profileIds": [ + "admin" + ], + "_kuzzle_info": { + "createdAt": 1729763709358, + "updatedAt": null, + "updater": null + } + } + }, + "status": 200, + "volatile": null +} +``` + +#### Using the CLI + ```bash kourou security:createFirstAdmin '{ credentials: { @@ -120,6 +400,28 @@ kourou security:createFirstAdmin '{ } } }' -a reset=true + +## Response + +[ℹ] Unknown command "security:createFirstAdmin", fallback to API action + + 🚀 Kourou - Executes an API query. + + [ℹ] Connecting to ws://localhost:7512 ... +{ + "_id": "kuid-measly-aeolus-69909", + "_source": { + "profileIds": [ + "admin" + ], + "_kuzzle_info": { + "createdAt": 1729762670215, + "updatedAt": null, + "updater": null + } + } +} + [✔] Successfully executed "security:createFirstAdmin" ``` #### Try the API as the anonymous user @@ -131,16 +433,19 @@ You should get the following error because now the anonymous user is restricted ```bash kourou server:now -[ℹ] Unknown command "server:now", fallback to API method - +[ℹ] Unknown command "server:now", fallback to API action + 🚀 Kourou - Executes an API query. - - [ℹ] Connecting to http://localhost:7512 ... - [X] UnauthorizedError: Unauthorized: authentication required to execute the action "server:now". -1 - [...Kuzzle internal calls deleted...] - at Funnel.checkRights (/var/app/lib/api/funnel.js:374:28) - status: 401 - id: security.rights.unauthorized + + [ℹ] Connecting to ws://localhost:7512 ... + [X] Error stack: +UnauthorizedError: Unauthorized: authentication required to execute the action "server:now". -1 + [...Kuzzle internal calls deleted...] + at Funnel.checkRights (/var/app/node_modules/kuzzle/lib/api/funnel.js:612:28) + +Error status: 401 + +Error id: security.rights.unauthorized (https://docs.kuzzle.io/core/2/api/errors/error-codes/security) ``` #### Try the API as an authenticated user @@ -153,9 +458,9 @@ We are allowed to use this API action because **we are now authenticated with a kourou server:now --username melis --password password [ℹ] Unknown command "server:now", fallback to API method - + 🚀 Kourou - Executes an API query. - + [ℹ] Connecting to http://localhost:7512 ... [ℹ] Loggued as melis. { @@ -166,6 +471,7 @@ kourou server:now --username melis --password password ::: info You can now reset anonymous rights to default to make the rest of this tutorial easier: + ```bash kourou security:updateRole '{ controllers: { @@ -176,7 +482,36 @@ kourou security:updateRole '{ } } }' --id anonymous --username admin --password password + +## Response + +[ℹ] Unknown command "security:updateRole", fallback to API action + + 🚀 Kourou - Executes an API query. + + [ℹ] Connecting to ws://localhost:7512 ... + [ℹ] Loggued as admin. +{ + "_id": "anonymous", + "_source": { + "controllers": { + "*": { + "actions": { + "*": true + } + } + }, + "_kuzzle_info": { + "author": null, + "createdAt": 1729763897988, + "updatedAt": 1729763897988, + "updater": null + } + } +} + [✔] Successfully executed "security:updateRole" ``` + ::: You should retrieve the following 2 documents: ```bash 🚀 Kourou - Searches for documents - + [ℹ] Connecting to http://localhost:7512 ... [ℹ] Document ID: OYgZJnUBacNMjDl2504F Content: { diff --git a/doc/2/guides/introduction/general-purpose-backend/index.md b/doc/2/guides/introduction/general-purpose-backend/index.md index 99180bfdec..49f9a714b1 100644 --- a/doc/2/guides/introduction/general-purpose-backend/index.md +++ b/doc/2/guides/introduction/general-purpose-backend/index.md @@ -18,13 +18,13 @@ Rather than developing the same standard features over and over again every time ## API First -The majority of Kuzzle's features are available via its [API](/core/2/guides/main-concepts/api) for various external clients. +The majority of Kuzzle's features are available via its API for various external clients. This **multi-protocol API** allows clients to communicate with Kuzzle and use the backend features through the **protocol that best suits their needs**: - - [HTTP](/core/2/api/protocols/http) - - [WebSocket](/core/2/api/protocols/websocket) - - [MQTT](/core/2/api/protocols/mqtt) - - Or [any IP protocol](/core/2/guides/write-protocols/start-writing-protocols) +- HTTP +- WebSocket +- MQTT +- Or any IP protocol Whether it is the creation and modification of the database or the management of users and rights, **everything is available through the different controllers of the API**. @@ -34,14 +34,15 @@ Access to every action is **centralized within the rights management system** fo ## Ready-to-use Database -Kuzzle uses Elasticsearch as a [NoSQL document store](/core/2/guides/main-concepts/data-storage). +Kuzzle uses Elasticsearch as a NoSQL document store. With Kuzzle, customers **can directly access data stored in the database** as long as they have the rights to do so. -Kuzzle exposes the [Elasticsearch Query Language](/core/2/guides/main-concepts/querying) in a secure way. It is therefore possible to **take full advantage of the possibilities of Elasticsearch** with boolean queries, aggregations, special fields, etc. +Kuzzle exposes the Elasticsearch Query Language in a secure way. It is therefore possible to **take full advantage of the possibilities of Elasticsearch** with boolean queries, aggregations, special fields, etc. It is then **no longer needed to create a new controller every time new data needs to be displayed**, and it is no longer needed to add parameters to controller actions to refine searches either: **queries are expressed directly on the client side**. + ```js // Retrieve documents matching the Elasticsearch query let result = await sdk.document.search('iot', 'sensors', { diff --git a/doc/2/guides/introduction/what-is-kuzzle/index.md b/doc/2/guides/introduction/what-is-kuzzle/index.md index 121e5c2c52..cdf97d1d12 100644 --- a/doc/2/guides/introduction/what-is-kuzzle/index.md +++ b/doc/2/guides/introduction/what-is-kuzzle/index.md @@ -9,29 +9,51 @@ meta: - name: keywords content: Kuzzle, Documentation, kuzzle write pluggins, What is kuzzle --- -# What is Kuzzle -If you reached this page, it probably is because **you are looking for a backend** for your mobile, web or IoT application. +# Why Choose a Ready-Made Backend? -You were surely thinking about **developing another backend from scratch**, or maybe using some kind of framework to code it faster. +If you're here, you're probably planning to build a backend system for your: +- Mobile application +- Web platform +- IoT project -Using a framework is handy because having predefined structures, classes and configurations will indeed make the whole process easier, however you will still have to develop the majority of the basic features you truly need like: - - Storing and searching data - - Rights management - - User authentication - - Access to data and functionalities via API +## The Traditional Approach -Developing **these features can be a huge timesink**, not only to write them but also to debug, test, secure and maintain them as well. +Your first instinct might be to: +1. Build everything from scratch +2. Use a framework to speed things up -In short, you were going to spend a consequential amount of time on code that **does not bring value to your users**, time that could have been used for many other things like: - - Development of business functionalities - - UI / UX of frontend applications - - 100% coverage by automated tests - - Implementation of DevOps best practices - - Product marketing - - ... +While frameworks provide helpful structures and patterns, you'll still need to implement fundamental features like: +- Database operations and search functionality +- Permission systems +- User authentication +- API endpoints + +## The Hidden Cost + +Building these basic components isn't just about writing code. It involves: +- Extensive debugging +- Security hardening +- Testing +- Ongoing maintenance + +This represents significant time spent on infrastructure rather than value-adding features. + +## What You Could Focus On Instead + +The time saved could be better invested in: +- Core business features +- Frontend experience +- Comprehensive testing +- DevOps optimization +- Marketing initiatives + +## The Solution: Kuzzle + +This is why Kuzzle was created - a pre-built backend platform that handles all the foundational elements, allowing developers to focus on what truly matters: building distinctive features for their users. + +Think of it as skipping the "infrastructure homework" and jumping straight to the unique aspects of your application. -To optimize our own development times and help developers around the world to get their backends running in no time, we started developing Kuzzle, **our ready-to-use backend platform**. ## How it works @@ -169,9 +191,3 @@ Our multidisciplinary team of experts is capable of addressing any type of issue You can thus pass the development and production phases with a relaxed spirit, knowing that you can rely on quality professional support. [Get a quote](https://info.kuzzle.io/contact-us) - -### Meet the community - -We federate a community of developers using Kuzzle around the world. - -Whether you want to ask a question on [StackOverflow](https://stackoverflow.com/questions/ask?tags=kuzzle), check out the [Kuzzle awesome list](https://github.com/kuzzleio/awesome-kuzzle), watch our video on [YouTube](https://www.youtube.com/channel/UCHcEzVQoH10YSyxc7jD3SMw/videos), or discuss Kuzzle on [Discord](http://join.discord.kuzzle.io), the community and the core team will be there to help you.