Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.

Simple yet powerful hassle-free and production ready hapi.js Server boilerplate

Build Status

Hapi-Moon provides a ready to go server boilerplate for hapi applications. All you need to do is install dependencies and run npm start command.

With Hapi-Moon you'll have:

  • Production ready docker setup
  • Multi environment configs (dev/prod/test with config)
  • MongoDB (Mongoose) Models
  • Authentication
  • Rest API Support
  • CSRF validation crumb
  • Cookie Management with yar (stores sessions in Redis backend)
  • View Render Support (nunjucks)
  • Cache (Redis with catbox-redis)


With Docker

git clone
cd hapi-moon
docker-compose up

It will expose port 3009 for your hapi-moon application. You can change the port and other details from config/default.json file.

Standart NPM

git clone
cd hapi-moon
npm install
npm test
npm start

Please visit routes and controllers folders to see how to define a route and controller.

Rest Api Usage

In order to use this boilerplate as REST API, you need to send "X-CSRF-Token" information in the header. Otherwise, your request won't be allowed by the server.

Also you need to remove plugins.crumb block from your handler.

    plugins: {
        crumb: {
            restful: false

Let's say you want to implement authentication to your SPA then your auth/login handler would be like this.

exports.login = {
    auth: false,
    validate: {
        payload: validators.login
    description: 'sign in user to system',
    handler: async (request, h) => {
        const result = await User.login(, request.payload.password);
        if (result) {
            request.yar.set('auth', result.apiData());
            return {status: true, result: result.apiData()};

        return {error: 'Invalid email or password'}

To read more about this please refer to crumb documentation.

Production deployment

To use this application under production, first, create a file named production.json under the config folder. Then update the necessary variables in it.

For details about multi-environment config, please refer to config.

To start your production application, you can use any of the below definitions.

Standart Way

Install modules and then start the application

NODE_ENV=production NODE_CONFIG_DIR=./config npm start

Docker Way

Just edit your production.json file and make sure that you have the correct settings in your docker-compose.yml file, and then start your application.

docker-compose up -d


PM2 is a process manager for node and many other languages.

Install PM2

npm install pm2@latest -g
pm2 startOrRestart pm2-startup.json

Please visit PM2 documentation for other details.

PM2 & Docker

You can use PM2 with Docker as well. You will find the instructions inside the Dockerfile. Just make sure that you set the correct environment and config files.

Create User

Run npm run add-user then follow instructions