Running an Instance of the Onboardbase Platform on Your Servers

You can host the Onboardbase platform on your servers. You can do this with our obbctl tool.

After following the installation guide on the obbctl homepage, you can begin to set up Onboardbase for self-hosting.


  • Docker setup and running on the server
  • Service token to an Onboardbase organization that has the necessary environment variables
  • A Selfhost Key, you can request for a key by sending an email to [email protected]

Setting up the environments

The Onboardbase platform has both a frontend and a backend, and both of them require some environment variables to run. You will have to supply these environment variables to run the platform.

You must create two Onboardbase projects on our platform to set up the environments needed. Each for the frontend and backend.

Setting up the Backend Environment

After creating the project, you are presented with a view to add environment variables. Click on Env Option to see a drop-down of options and select Template

From the template modal, select [Self Host] Onboardbase Backend:

This will pre-populate the keys needed to set up the backend environment. You will have to provide values for those keys. After providing the values, save the changes.

The backend is a GraphQL server.

Setting up the Frontend environment

You will need to create a new Onboardbase project for the frontend. We call it obb_selfhost_frontend, you can give it your preferred name.

Select Template from the Env Option drop down as we did earlier:

This time around, we will be selecting the [Self Host]: Onboardbase Frontend template:

This will also pre-populate the keys needed for the frontend environment, the VUE_APP_API_SERVER should point to the URL the backend will be deployed to e.g

After providing the values, save the changes.

Getting a Service Token

The next step is to generate a Service Token that will grant access to the projects we created.

Click on your profile Avatar at the top right, and from the drop-down select Manage your organization:

On the settings page, scroll down to Service Token section and click on Create a token:

On the modal to create a Service Token, supply the values similar to the ones below. It is important that the Service Token has access to the two projects we created earlier:

After generating the Service Token, copy it to your clipboard

Using obbctl

It is assumed that you have installed obbctl. After installing obbctl, ensure you have Docker running on the machine.

setup command

Run obbctl setup and you will get the following prompt:

> obbctl setup

⏳ Please enter your selfhost token.: ********************************************
⏳ Please enter your ONBOARDBASE_TOKEN.: *******************************************
⏳ Please enter your onboardbase frontend project name: obb_selfhost_frontend
⏳ Please enter an onboardbase frontend project environment for (obb_selfhost_frontend): development
⏳ Please enter your onboardbase backend project name: obb_selfhost_backend
✔ ⏳ Please enter an onboardbase backend project environment for (obb_selfhost_backend): development█

Make sure the information you are providing is correct. After successfully running the setup command, obbctl will configure your machine and pull the necessary docker images to run Onboardbase locally.

start command

After setup, the next step is to run the obbctl start command. Before running this command, make sure the following ports are free and available:

  • Port 5432 for the Database
  • Port 6379
  • Port 3000
  • Port 80 for the frontend application

After running the start command, obbctl will start the frontend and backend applications. The frontend will be available on port 80 of the localhost of the machine. You can check the logs from the Docker containers being executed for progress (we are working on simplifying logs).

obbctl's journey ahead

We are dedicated to refining existing features, introducing enhancements, and ensuring a seamless user experience. Here are some updates we are working on:

  • Configuration of ports: This will allow you to supply the ports obbctl should start the services with if you don't want to use the defaults listed earlier.
  • Simplifying logs: logs command to output real-time updates from the obbctl start command.
  • Streamlining needed environment variables: This will reduce the number of environment variables needed to start the services.

We're eager to hear your feedback as we evolve. Thank you for being part of this journey with us, and If you have any queries or questions, please get in touch with us at [email protected].