A lightweight, configurable CMS build using Koa, MongoDB, Pug, Vue.js and Stylus.
Setting up and configuring this application will provide you with a simple interface to manage (create, edit, delete, ..) data entries based on a custom JSON schema.
Mandi can be cloned or be installed as an npm module and integrated with a pre-existing node application or HttpServer.
- Node.js (v7.0.0+)
- MongoDB (v3.2.0+)
Install mandi using npm:
npm install --save mandi
Create a Mandi instance and integrate it onto a pre-existing http node server:
const Mandi = require('../lib/Mandi')
const http = require('http')
// Create a simple configuration
let config = {
mongo : { url: 'mongodb://localhost/mandi-cms' },
basePath : '/admin',
publicUrl : 'http://localhost:8000/admin'
}
let schema = {
title: 'My simple blog',
types: {
posts: {
label: 'Post',
schema: {
cover: { extends: 'image', label: 'Cover' },
name: { extends: 'name' },
content: { extends : 'content' }
}
}
},
statics: {
title: { extends: 'title', label : 'Website title' },
description: { extend: 'content', label: 'Website description' }
}
}
// Instanciate Mandi
let mandi = new Mandi(config, schema)
// Instanciate a HTTPServer using Mandi's middleware function
let server = http.createServer(mandi.middleware())
// Start server on port 8000
server.listen(8000)
// The Mandi interface should now be available at localhost:8000/admin
mandi.util.log.info('Running Mandi on', 'http://localhost:8000/admin')
Create a Mandi instance initialise it on its own
const Mandi = require('../lib/Mandi')
const http = require('http')
// Create a simple configuration
let config = {
port : 8000
// ...
}
let schema = {
// ...
}
// Instanciate Mandi
let mandi = new Mandi(config, schema)
// Instanciate a HTTPServer using Mandi's middleware function
mandi.listen()
To setup this codebase on your development environment please follow these steps:
git clone https://www.github.com/workshape/mandi
cd mandi
npm install
npm run build
Before running the app, you still have to
- Confgure the app (Basic configuration)
- Write the CMS JSON schema in
./schema.json
(use./schema.default.json
as reference)
Then, you just need to run the server:
npm start
config
(Object) - an object containing server / db configuration (see 'Basic configuration')schema
(Object) - an object containing the data structure of the CMS (See JSON schema configuration)
.listen( port : String )
Listen on given port - if port is not passed, will default to port specified the config Object passed to the constructor.middleware()
Gets callback Function to be attached to a HTTP server (seecallback()
method on Koa documentation).on( eventName : String, callback : Function )
Bind a callback to a specified event
Mandi is an EventEmitter
- event:
log
- args: [message : String
] Mandi emits events for each of its logs - the app can also be muted using thequiet
configuration option, so that it's possible to manage logs in a custom way
The configuration defaults to the one in config/default.json
but it passed to the Mandi
constructor
publicUrl
(Env.PUBLIC_URL
) The base URL the CMS will be served at (without trailing slash)basePath
The base path the CMS will be served at (useful if mounting an instance of Mandi on a pre-existing HttpServer)secret
(Env.SECRET
) A secret used to hash passwordsport
(Env.PORT
) The port the website is gonna be served at by Node.jsmongo.url
(EnvMONGO_URL
) The URL of the mongo database (by default `mongodb://localhost/mandiaws.key
(Env.AWS_KEY
) Your Amazon Web Services key (optional - AWS configuration is used for S3 file uploads, but will fall back on local file system if not setup)aws.secret
(Env.AWS_SECRET
) Your Amazon Web Services secretaws.bucket
(Env.AWS_S3_BUCKET
) Your Amazon Web Services S3 Bucket nameaws.region
(Env.AWS_REGION
) Your Amazon Web Services S3 Bucket region (defaults tous-standard
)uploadsDir
(Env.UPLOADS_DIR
) Absoute path used to customise the uploads directoryquiet
(Env.QUIET
) Mute all the logs (they can still be detected binding listening to events with.on('log', msg => { /* ... */ })
)
All data types that will be managable through the CMS are defined in a simple JSON schema that can be created by the user.
This schema needs to be created under the website.json
filename in the root directory - and it will extend the default configuration file website.default.json
The default file contains an example of a basic posts
type that can be used - for example - creating a blogging system
You can use this file as a refence for your website.json
file
You can override the following properties in the Object exported by website.json
:
title
String - The admin website's title as it will be displayed in the interfacetypes
Object - The value under each key of this Object contains the JSON schema assigned to the DB collection named with its key
Types are basically validation schemas that will determine the UI the CMS generates to administer the various of data entries that will be managed through the CMS
Here's the type you can find in the default CMS configuration website.default.json
:
{
"types": {
"posts": {
"label": "Post",
"schema": {
"cover": {
"extends" : "image",
"label" : "Cover"
},
"name": {
"extends" : "name"
},
"excerpt": {
"extends" : "content",
"label" : "Excerpt",
"tip" : "Plane text - short and descriptive"
},
"content": {
"extends" : "html",
"label" : "HTML content"
}
}
},
},
"statics": {
"title": {
"extends" : "title",
"label" : "Website title"
},
"description": {
"extends" : "content",
"label" : "Website description"
}
}
}
Each type contains the following properties:
label
The display name for an individual entry of this typeschema
An Object containing the validation schema for given type
Each field in the schema should extend from a basic validator-preset
- you can set the extends
property to do so, and every other field is gonna extend the schema it refers to
To learn more about the properties you can override you can look at how the base type presets are defined in common/util/validator-presets.js
When defining the CMS types, you can chose to extend from the following presets (defined in common/util/validator-presets.js
email
A required 4-100 characters long valid email Stringurl
A required valid url Stringpassword
A required 6-100 characters long valid Stringname
A required 1-100 characters long valid Stringtitle
A required 1-150 characters long valid Stringcontent
A 0-1500 characters long valid Stringfile
Any fileimage
A file of mime type matching one ofimage/jpeg
,image/png
orimage/gif
Now that you configured the app and the JSON schema, you need to start the CMS - run
npm start
The interface should now be running on localhost:4000
By default, a overlord user will be created with the following credentials:
Username: admin
Password: foobar
When logged in you will be able to change your password
The following npm tasks are available to support development workflow:
npm run watch-server
Watch for changes on the server-side codebase and restart server when necessarynpm run watch
Watch for changes in the client-side codebase and rebuild what's been changednpm run build
Re-build the codebasenpm run dev
Runwatch-server
andwatch
together
Copyright (c) 2017 WorkShape.io Ltd. - Released under the MIT license