/zoinx

Zoinx Node Modules

Primary LanguageJavaScriptMIT LicenseMIT

Zoinx

An Opinionated Framework based on NodeJS, Mongo and Kafka
to simplify creating event driven, full-featured microservice applications.
Explore the WIKI »
Report Bug · Request Feature

Table of Contents
  1. About Zoinx
  2. Getting Started
  3. Optional Tools Links

About The Project

A core vision for Zoinx is the ability to create REST API endpoints fully CRUD (Create, Read, Update, Delete) enabled and secure in minutes and fully instrumented.
The framework is primarily geared to creating event driven microservices. It is usable for any purpose desired as it's based on industry standard technology.

Why use Zoinx:

  • Focus on what matters, business logic and not mundane details most applications need
  • Easily add Entities and Features
  • Built in application telemetry
  • Built in configuration based testing
  • Built in configuration for role based security
  • Event driven using Kafka by default
  • Built in CLI

Built With

Zoinx is based in NodeJS with MongoDB as the main datastore. It does not support using any SQL based datastore for the primary datastore.
It is of course possible to add connectivity to any SQL datastore but that is a per-project decision.

Zoinx is event driven out of the box. To support an event driven architecture, Kafka is used to produce and consume messages. Kafka is more than pub/sub messaging but Zoinx does not dictate how it can be used but sets up the basic functionality inside of Docker.

(back to top)

Getting Started

Getting up and running with any framework can be clumsy but Zoinx works to make this process painless and as fast as your development machine will allow.

The development setup is based in Docker which can be resource intensive. The NodeJS container can be turned off and run from an IDE where the NodeJS app can connect to and make use of the resources inside Docker. This will be covered later along with env vars.

Prerequisites

Zoinx requires certain applications and environments to be ready to use. If you are already developing NodeJS and Docker based applications, you might already have what is needed.

  • GIT
  • npm/node version 20+
  • nvm (suggested not required)
  • Docker Desktop or a Docker environment
  • Shell environment (specifically on Windows use GitBash, PowerShell or CMD will not work)
  • Mongo Compass (suggested not required)
  • API Platform i.e. Postman, Insomnia, etc.
  • Kafka client (akhq is included but not installed to Docker by default)

(back to top)

NPX Installation

There are 2 options for installing the Zoinx framework. Installing via npx will ask you a number of questions and setup the entire environment, including Docker, Mongo and Kafka. This will also populate Mongo with some initial data and setup local account access. 

mkdir <project name>
cd <project name>
npx trozlabs/zoinx

This will run and walk you thru questions that are used to setup the needed components. Once all the questions have been answered and the dependencies installed, run the command it states (shown below)

npm run docker:build-start

Once the Docker environment is running, a picklists endpoint will already be in place and functional and have data. To test this, use your API client for this endpoint

http://localhost:3000/picklists/typelist

Because security is built in, the local account created after running the npx installer will need to be added to the request.

This means:
add a Basic Auth Header with the local account username and password. Default account is ROOT.



Basic Installation

Doing a basic installation is also available but will not set up all the needed details.

mkdir <project name>
cd <project name>
npm init
npm install trozlabs/zoinx

This will get Zoinx downloaded to your project but will not include any config or setup.

(back to top)

Optional Tools

(back to top)