Kuzzle IoT Platform Project

This repo is a template to create a project using the Kuzzle IoT Platform, like our mantra for kuzzle, we value your time, so rather than developping your own platform, you can start from our work and add high-level, high-value business functionalities. Have a look at our documentation and how to get started.

Important Notes

This is a product under license that require private packages in order to work. You need to have a valid license to use it. If you don't have one, you can request a license here.

Installation and run

Requirement:

• Node.js >= 22
• NPM = 11.6.2
• Docker
• Docker Compose

What's inside?

Monorepo

This monorepo uses npm as a package manager. It includes the following apps:

2 applications

• api: a Kuzzle IoT Backend application
• web: a Kuzzle IoT Console application

Install dependencies

Log to Kuzzle npm private repository: https://docs.kuzzle.io/paas-console/1/guides/access-private-plugins/

Run the stack

Starting the stack the first time might take some time as it needs to download the docker images and the dependencies. All of that will be cached by Docker for the next runs.

docker compose up --build --watch

Release process

The release process is being done automatically using CI/CD workflows. When commits are being pushed into specific branches, a workflow will be triggerd which will build the application and then create a GitHub (pre)release. Once released, another workflow will deploy to an environment (uat, staging, production). Deployment may require manual intervention in some branches (e.g. X-dev branches) while other branches (X-stable) may not.

Inside the workflow, it is semantic-release that is responsible of bumping the version and publishing the packages. The behavior of this tool changes based on the commit branch. This template provides a basic configuration that must be modified to fit your needs (branch names, npm registries, ...).

Note

By default semantic-release will try to publish the packages to an npm registry. In order to prevent this behavior, the field private must be set to true in the package.json file(s).

Out of the box configuration

The provided configuration looks like this:

Branch	Release type	Version example	Environment
stable	Release	1.0.0	production
beta	Pre-release	1.0.0-beta.0	staging
dev	Pre-release	1.0.0-dev.0	uat

Here's a representation of what's happening:

Going further

To-do list after cloning

In the beginning, you will only have a single branch (stable). Make sure to add the other branches (beta and dev) and set stable to be the default branch when starting a new project. Most automations (CI/CD workflows) are disabled or require manual intervention for the development branch.

Adding other versions

Later, you may have the need to add other versions (e.g. 2-dev, 2-beta, ...). To do this, you need to edit the .releaserc.mjs in the root folder of the project and your new branches there. semantic-release's documentation is available here.

For example, you might want to start working on version 2. Therefore, you'll need to create the three branches (2-dev, 2-beta and 2-stable). After that, you will need to add them to semantic-release's configuration.

export default {
  [...],
  branches: [
    [...],
    '2-stable',
    { name: '2-beta', prerelease: 'beta' },
    { name: '2-dev', prerelease: 'dev' },
  ],
};

Important

If you need to work on both version at the same time, you will need to adapt the workflows so the two versions don't interfere with each other. You don't want to your version 2 to override version's 1 staging environment.

Publishing to npm

By default, the release workflow will not publish the packages to npm. If it is something you desire, you can do so by removing the private field in the package.json of your workspace.

Notes on semantic-release

The configuration in this template extends a global one that we use for all of our projects. See kuzzleio/semantic-release-config-kuzzle. This preset does a few things for you:

• Automates changelogs
• Optional GitHub/npm/Slack integration (via webhooks)
• Automates version bumps of your workspaces

For more information, read the repository README.md.

Building container images

The .npmrc is mounted as a secret only during build time so the container can download necessary npm packages from our private repository. If your .npmrc is living somewhere else than in your home directory, change its path.

API

When building the api image, you need to define which environment to copy in the image. Possible values are the folder names in the api/lib/environments folder.

docker build \
  --secret id=npmrc,src=$HOME/.npmrc \
  --build-arg KUZZLE_ENV=local \
  -f ./apps/api/Dockerfile .

You can define additional build arguments:

Name	Description
KUZZLE_VAULT_KEY	Key to decrypt the Kuzzle vault.

Web

When building the web image, you need to specify which backend the frontend will connect to. Possible values are the keys of the object backends in web/src/config.ts.

docker build \
  --secret id=npmrc,src=$HOME/.npmrc \
  --build-arg VUE_APP_BACKEND=local \
  -f ./apps/web/Dockerfile .

Useful Links

Learn more about the power of Kuzzle

• Getting Started with Kuzzle
• API
• Data Storage
• Querying
• Permissions
• Authentication
• Realtime Engine
• Discover our SDKs
• Release Notes