ninoxdatabase/ninox-on-premise

Ninox Monorepo

This is a quick documentation intended to give a rough overview of the repo, for a more thorough documentation go to confluence

Prerequisites

• Node.js 18.20 (LTS)
• nvm
• Docker (optional but recommended)

1. Development Container (Recommended)

This repository includes a fully configured development container that provides a consistent development environment across different machines and operating systems.

Prerequisites

• Docker and Docker Compose
• VS Code or a VS Code compatible editor (like Cursor, https://github.com/features/codespaces, etc.)
• Dev Containers extension for VS Code

Getting Started

1. Open the repository in VS Code

   bash
   code .
   
   # Before opening your container, initialize the project
   just setup private $NPM_TOKEN $LICENSE_TOKEN
   

2. Reopen in Container

   • Press F1 (or Cmd+Shift+P on macOS)
   • Select "Dev Containers: Reopen in Container"
   • Wait for the container to build and start (first time may take several minutes)

3. The container will automatically:

   • Install all dependencies
   • Configure git and npm
   • Set up the development environment
   • Install recommended extensions

Inside the devcontainer, you can use just commands or docker compose directly:

bash
# Start services
just start

# View logs
just logs deps

# Stop services
just stop

2. Quick usage with Docker and Docker Compose:

You need docker and docker compose installed and at least 8G of RAM and 4CPUs.

Just task runner

We include a justfile to automate common tasks (setup, start, stop, build, logs, etc). just is a small CLI to run those recipes.

Install:

• macOS: brew install just
• Linux (Debian/Ubuntu): sudo apt-get install just (or cargo install just)
• Windows: choco install just or scoop install just

Start services:

• just — list available commands
• just check - check deps
• just setup private $NPM_TOKEN $LICENSE_TOKEN — set config files and env files
• just build - build base docker image
• just start — run services (the first time it will take some times because of npm deps installation)
• just logs deps logs of the dependencies service

If you want more flexibility to override docker-compose and change the starting commands, you can duplicate docker-compose.yaml -> docker-compose.override.yaml. Then you can override that file, it's ignored.

After the installation is completed go to http://localhost:9000 -> you can use root as username and password.

NOTES ⚠️:

• NPM_TOKEN: npm token for pulling private packages
• LICENSE_TOKEN: token for getting the license
• This setup only works for private cloud (public cloud in progress)

3. How to get start without Docker

1. Set the node.js version:

bash
nvm use

If not found then nvm install then nvm use to install the correct NodeJS version

2. Install the npm token to allow access to our private NPM registry - ask your colleagues for the token

echo "//registry.npmjs.org/:_authToken={ninox_npm_token}" > ~/.npmrc

3. Install the packages

npm run bootstrap

Note: if bootstrap doesn't work try npm ci

The command above will install all the dependencies and build the local dependent packages. Tt's recommended on the first use.

However you can install dependencies only for a specific package by changing your working directory to the package directory and running npm install.

Scripts and Commands

🚀 Get Up and Running

To start the server and the client you need to run the following commands:

bash
# Terminal 1
npm run core:start

bash
# Terminal 2
npm run server:start

bash
# Terminal 2
npm run client:start

To run a private cloud locally for easier development, you can use npm run client:watch:web:private. And for public cloud you can run npm run client:watch:web:dev.

Ninox Server

To start the ninox server, you need to create server-config.json first, and then run the server command from the root folder:

• npm run server:build: runs the server build script
• npm run server:start: runs the server dev script

• npm run server:start:dev:debug: runs the start:dev script under ninox-server with --inspect-brk flag.
• npm run server:test: runs the server test script.
• diff: shows the diff of all packages since the last release
• release: creates a new release, also it will bump the version of all packages and add the changes to the changelog file.

Log Configuration

The server supports configurable log output format via server-config.json or environment variables:

Defaults: pretty in development, json in production (optimal for log aggregation).

Example - Enable pretty logs in production:

json
{
  "logLevel": "info",
  "logTransport": "pretty"
}

See Server Configuration Documentation for full details.

Ninox Client

With all the client scripts in the mono-repo, you can run them from the root by prefixing them with client:.

To run client:watch:web:dev from root you can simple run npm run client:watch:web:dev

Ninox Core

The same as ninox-client all core scripts are prefixed with core:

To run the ninox-core build script from the root folder, you to run npm run core:build

Ninox iOS app

For instructions on how to run the iOS app, please refer to the Ninox iOS app README

Ninox Mac app

For instructions on how to run the Mac app, please refer to the Ninox Mac app README

Other scripts

• prettier:check: runs prettier check for all packages
• prettier:fix: runs prettier write for all packages except the ignore files in the .prettierignore
• lint: runs the eslint check script for all packages

Triggering staging deployment

The setup_deployment_workflows job in the CircleCI pipeline is responsible for generating dynamic configurations for deployment workflows. This job can be triggered based on specific conditions or parameters.

Conditions for Triggering

The setup_deployment_workflows job will run if:

• The workflow is not a rerun.
• The DEPLOY_STAGING parameter is set to true.
• The latest commit message contains the #deploy-staging tag.

Deploy Using Commit Message Tag

Include #deploy-staging in your commit message:

git
git commit -m "<Your commit message> #deploy-staging"

If there are no file changes, yet the deployment is required, you can use the --allow-empty flag:

git
git commit -m "<Your commit message> #deploy-staging" --allow-empty

How to set up tilt for a happy dev environment

[NO LONGER SUPPORTED]

Tilt is an amazing tool for running services locally, using Kubernetes, docker-compose, or even run local resources as our setup for this project. If you are tired of splitting your terminal, and all the time you need to open the package.json to search for a specific script, Tilt will solve all your troubles. Just a single command: tilt up and all magic happens in your browser. Now, there's no need to locate a terminal or doing some crazy search for logs or even remembering all the commands.

Install tilt

Installing the tilt binary is a one-step command.

macOS/Linux

bash
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash

Windows

bash
iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.ps1'))

Docker

Use the following command to build the image, replacing "my-token" with the actual NPM token you want to use:

sh
export NPM_TOKEN=my-token
docker build --build-arg NPM_TOKEN=${NPM_TOKEN} --platform=linux/amd64 -t ninoxdb .

You can verify that the docker works by running the service as such:

sh
docker container run -d \
    --name ninoxdb \
    -v NX-DATA:/var/nxdb \
    -p 80:8080 ninoxdb

Navigate to your browser and use your local ninox! You can inspect the logs with

sh
docker logs ninoxdb -f

For specific package managers (Homebrew, Scoop, Conda, asdf), see the Installation Guide.

Try it! Run

Starting tilt is so simple:

bash
cd ninox
tilt up

Tilt will open a browser showing the web UI, a unified view that shows you resources status and logs. Your terminal will also turn into a status box if you’d like to watch your server come up there.

Contributing

We opt to use Gitflow Workflow that helps with continuous software development and implementing the DevOps best practice of continuous delivery.

How it works

1. The development branch is created from master
2. The release branch is created from development. (e.g. release/3.5.0)
3. The feature branches are created from development. (e.g. feature/DN-111[-set-up-code-style])
4. The bugfix branches are create from development. (e.g. bugfix/DN-112[-fix-rendering-issue])
5. When the release branch is done it is merged back into development and master
6. If an issue in master is detected a hotfix branch is created from master (e.g. hotfix/3.5.1)
7. Once the hotfix is complete it is merged to both development and master.

Example

Let us imagine a feature ticket in Jira with an ID DN-123 assigned to you, something like Setting up OAuth 2.0 within Ninox Server, and let us assume that you have the mono repo cloned somewhere in your machine.

The first thing to do is to checkout to the development branch and make a pull from the origin

git checkout development
git pull

Then you create your feature branch from the development branch as follow:

git checkout -b feature/DN-123-setting-up-oauth2

All magic happened, and you finished the implementation, congratulation! Now it's time to create a pull request in Github by pushing your feature branch and providing a meaningful title for your PR, something like feat(server): [DN-123] Setting up Oauth 2.0 within Ninox Server and assign a reviewer to the PR.

git push origin -u feature/DN-123-setting-up-oauth2

ℹ️ Note: As a reviewer, I need to ensure that the PR title and branch name respect our naming conventions as a part of your review.

After fixing all review feedbacks, now your feature is ready to be merged into the development branch. The same procedure applies to bugfix.

Creating a pull request

The pull request title must follow the conventional commits guide. It's a specification for adding human and machine-readable meaning to our commit messages.

A title must contain the following structural elements:

1. feat: a PR of the type feat introduces a new feature to the codebase (this correlate with MINOR in Semantic Versioning).
2. fix: a PR of the type fix patches a bug in your codebase (bugfix or a hotfix branch) (this correlates the PATCH in Semantic Versioning).
3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
4. types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.

ℹ️ Note: A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(server|core|client):

Reviewer Scope

⚠️ As a part of a review, the reviewer needs to ensure that the branch name and PR title follow our conventions.

How do i run x in worskpace y

npm run x --workspace=y ex.: npm run start --workspace=@ninox/ninox-client

References

• Conventional Commits
• keep a changelog
• Gitflow Workflow
• DevOps Best Practices
• https://danielkummer.github.io/git-flow-cheatsheet/

Resources

• https://danielkummer.github.io/git-flow-cheatsheet/