Lumber: The admin microservice generator

Lumber is an opensource tool to generate an admin microservice. It serves a REST API hooked directly into your database (MySQL and Postgres for now).

• Install
• Usage
• Deploy to production

DISCLAIMER: Lumber is a project from Forest. Your Lumber-generated app gives you a free pass to all the powerful features of Forest, as per our Hacker plan.

Install

$ npm install -g lumber-cli

NOTICE:

• You may need to use sudo depending on your platform.

Usage

• Quickstart
• List of commands
• Adding relationships
• Creating actions

Quickstart

$ lumber generate

NOTICE:

• Your database credentials are safe. They are only stored in the Lumber generated microservice.
• You may need to use the option --ssl if your database uses a SSL connection.

Full demo video: https://www.youtube.com/watch?v=2cKSsBxrvR8

Commands

$ lumber [command]

• generate generate your admin microservice
• user show your current logged user
• login sign in to your account
• logout sign out of your account
• action create a new action button on your admin
• heroku-deploy deploy your admin on production

Advanced

Relationships

As Lumber generates an admin microservice from the database schema, it only creates belongsTo relationships, based on all your foreign keys. Please note that some ORMs do not create foreign key constraints. This means that in some cases, you will have to add belongsTo relationships manually. Lastly, as databases don't have the notion of inverse relationships, you will need to add hasMany or hasOne relationships manually.

The generated admin microservice uses the ORM Sequelize. Check out their documentation for advanced model customization.

Adding belongsTo relationships

Open the model file you want in the models directory and declare the belongsTo relationship in the associate function.

Syntax:

Model.belongsTo(<targetModel>, {
  foreignKey: '<foreignKey>',
  // ...
));

Available options can be found in the Sequelize documentation.

Example:

module.exports = (sequelize, DataTypes) => {
  let models = sequelize.models;

  var Model = sequelize.define('users', {
    // ...
  }, {
    classMethods: {
      associate: () => {
        // BelongsTo relationships
        Model.belongsTo(models.addresses);
      }
    },
    // ...
  });

  return Model;
};

Adding inverse of relationships (hasOne, hasMany, …)

Open the model file you want in the models directory and declare the hasMany (hasOne is very similar) relationship in the associate function.

Syntax:

Model.hasMany(<targetModel>, {
  // [options]
  // ...
));

Available options can be found in the Sequelize documentation.

module.exports = (sequelize, DataTypes) => {
  let models = sequelize.models;

  var Model = sequelize.define('users', {
    // ...
  }, {
    classMethods: {
      associate: () => {
        // hasMany relationships
        Model.hasMany(models.books);

        // hasOne relationships
        Model.hasOne(models.car);
      }
    },
    // ...
  });

  return Model;
};

Actions

Common actions such as CRUD, sort or search are implemented by default. You will probably want to provide your admin with actions to perform operations that are specific to your application. Moderating comments, logging into a customer’s account (a.k.a impersonate) or banning a user are typical examples of specific actions.

The following command will automatically generate an approve action on the comments collection.

$ lumber action comments approve

Declaration: /forest/comments.js

'use strict';
var liana = require('forest-express-sequelize');

liana.collection('comments', {
  actions: [
    { name: 'approve' },
  ]
});

Implementation: /routes/comments.js (customize the business logic here).

'use strict';
var express = require('express');
var router = express.Router();
var liana = require('forest-express-sequelize');

router.post('/actions/approve', liana.ensureAuthenticated,
  (req, res) => {
    // Your business logic here.

    res.send({
      success: 'Comments successfully approved!'
    });
  });

module.exports = router;

Deploy to production

Lumber provides the command heroku-deploy to push your local admin interface to your Production environment.

1. Create a new Github repository.
2. Push your generated admin microservice on your new Github repository.
3. Ensure you have a Heroku (free) account and the Heroku CLI installed.
4. Login to your Heroku account using the command-line: $ heroku login.
5. 🎉 Deploy your admin microservice on production: $ lumber heroku-deploy -c. 🎉

Watch video:

License

GPL