Collectio-cms NPM

CollectIO

Build Status Azure DevOps coverage Azure DevOps tests npm

A lightweight headless CMS built on top of the classic KeystoneJS. The main purpose is to providing convenient services in order to automate following features:

auth management
token management
providing model mapping
security management
service connections

As mentioned before, this framework is based on the classic version of Keystone.js offering nested lists.

The server is customized so that the system is maintainable easily by the admin panel.

Getting Started

Installation

git clone https://github.com/AhmetCavus/Collect.IO.git

git clone git@github.com:AhmetCavus/Collect.IO.git

cd .\Collect.IO\

cd Collect.IO

npm i

Configuration

First of all, you have to provide an env file '.env' in your project root folder. This file should contain following keys:

Mandatory fields

MONGO_URI=mongodb://user:pass@host:port/collection?authSource=admin
JWT_SECRET=do.not.read.it.is.jwt.secret
VERIFY_SIGNATURE=i.can.open.doors
CLIENT_ID=alone.i.am.useless
SECRET_ID=do.not.read.it.is.client.secret

Fields for cloudinary

COOKIE_SECRET=do.not.read.it.is.cookie.secret
CLOUDINARY_NAME==cloudinary
CLOUDINARY_API_SECRET=secret
CLOUDINARY_URL=cloudinary://sample
API_KEY=apikey

Be aware of commiting this file in the repository!!!

Database

Check this README for setting up the database.

Initial Data

Before running the server for the first time, you can initially add data to the database by providing a js script under the updates folder. Here you can add more scripts in order to update the database. Therefore, consider the semantic versioning.

A sample is already placed in this directory initdata

Architecture

Here you can see a briefly sketch of the architecture:

Running the server

npm start, nodemon start or from VS Code select dev start or prod start.

Usage

const CollectIO = require("../core/collectio.app")
const collectio = new CollectIO.App()

collectio.start({autoDbStart: false, adminPort: 8181}).then(() => {
  console.log("Collectio is up and running")

  collectio.config((app, express) => {
    app.get("/test", (req, res) => {
      res.sendFile(__dirname + "/core/public/index.html")
    })
  })
})

For more information check the unit test project folder.

Options

In order to configurate the server and ports, you can specify following values on startup:

collectio.start(options)

Key	Description	Default
adminPort	Specify the port for the admin panel	3000
restPort	Specify the port for the rest API	8080
autoDbStart	Whether auto start the db engine or not	false
autoUpdate	Whether auto update the db with the scripts from the updates folder or not	false
updatePath	The path of the directory, where the update scripts are placed	updates
nav	A JSON Object representing the nav graph regarding to the models	{ account: "admins", "clients", "roles"}
modelPath	The path of the models, that should be registered in the db
secureRestApi	Whether to auto secure the Rest API with the secrets in the environment	true

Open the Admin panel

In order to get access into the admin panel, you have to open following link

admin panel(http://[host]:[specified admin port]/keystone/signin)

The credentials are the one you have provided in the script placed in the updates folder. Moreover, if you customized the admin port, you have to set the correct port number.

Accessing to collections

In order to access the collection provided in the models, you can simply call the code below

const device = collectio.collection("device")
// device.model is the mongoose schema

After that, collectio provides you convenient methods to notify observers

Function	Description
sendBroadcast(message, channelName)	Send a broadcast to all oberservers registererd to the given channel name
notifyAddItemCollection(schema, item)	Notify all oberservers listening to changes for the given schema and provide the new created item
notifyRemoveItem(schema, item)	Notify all oberservers listening to changes for the given schema and provide the removed item
notifyUpdateCollection(schema, items)	Notify all oberservers listening to changes for the given schema and provide the items of the changed collection
notifyUpdateCollectionItem(schema, item)	Notify all oberservers listening to changes for the given schema and provide the updated item of the collection

For every model schema in your models path, a collection will be created in the database. In addition, it will be supplied with bi-directional communication through sockets. You can get further detail in the API calls section.