Getting started

What you need

  1. You need Node.js v14.x or greater installed
  2. You need a Database for your data. You can use either postgres (recommended), mysql2, mariadb, sqlite3 or mssql.


Install helpkb:

  1. git clone
  2. cd helpkb


You will need to setup your database before you get going. If you have an existing database then you can simply setup your database environment variables.

They are:


We have a config file located here /api/dbConfig.js which can further extend your connection, enable logging, timeout, pooling, retries etc etc.

The default file looks like this. It's setup for postgres by default and may need tweaking depending on your chosen database.

const get = () => {
    return {
        host: process.env.DB_HOST,
        port: process.env.DB_PORT,
        dialect: 'postgres',
        logging: (process.env.DB_LOGGING === 'true'),
        pool: { maxConnections: 5, maxIdleTime: 30 },
        language: 'en'

module.exports = {

Once setup and configured, when you startup the application all tables and schema will be created and be ready to use by the application.

Starting development

You can start helpkb in dev by running:

$ npm run dev

This will startup helpkb on the ports and host setup in your environment variables.

Generally your UI will be accessible at: http://localhost:3000 and API will be at http://localhost:4000 unless changed.

Starting production

You can start helpkb in prod by running:

$ npm start

Login / Authentication

Before logging in you will need to setup a Github OAuth app. You will then be able to authenticate using your Github account at your helpkb login page here: http://localhost:3000/login. See our guide here.


Building is done automatically in development and deploy but if needed can be ran with:

$ npm run build

Application structure

The application is split into two main folders.

  1. /ui
  2. /api

The API is an Express.js server which manages all our config, DB etc.

The UI is a Next.js frontend which is very familiar to anyone who has used React before.


Tests are ran with:

$ npm run test