Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.

You can adjust all of your cookie settings by navigating the tabs on the left hand side.

Cookie Name Accept
GDPR PRO - General Data Protection Regulation - ALL in 1 This modules helps the site to become GDPR Compliant by adding the law compliant features.
Cyklon Storefront
Botpress Installation Tutorial | The Quickest Way for Beginners to Get Up and Running Using Your Own Hardware

Botpress is a fantastic and powerful chatbot platform with heaps of basic as well as advanced functionality. However, to a beginner (and those with little programming experience) it can be quite daunting to get started. In this tutorial we’ll cover what I think are some important terms and a step-by-step guide to getting your first chatbot up and running.

Disclaimer: This guide is for LINUX users. Specifically Ubuntu 20.04.1 LTS. If there is enough interest, or if people request it, I’ll write a guide for Windows as well.

To be honest, Botpress is fairly easy to get the hang of once you have some knowledge about how it works and its architecture. I wanted to write this guide because I feel the official Botpress documentation is not easy to digest if you are: a) Not a programmer and, b) Aren’t already familiar with the layout and architecture of Linux-type systems. One of the main reasons I love Botpress is the fact that, if you choose, you have complete control of all the data as everything can be hosted on premises – and it’s all open-source!

In this guide we’ll cover the following:

  • Botpress quick install (under 1 minute)
    • Some core concepts
    • SQLite vs. PostgreSQL
  • Preparing your environment
    • Dependencies – none, wait what?!
  • Installation

Local Botpress server up and running in under a minute? Yes, please!

For those who:

  • Are completely new to Botpress and just want to see what it’s about
  • Are Impatient
  • Don’t need a lot of performance
  • Just want to test the latest version with no fuss


  • Visit https://botpress.com/download
  • Click the box with Linux
  • Open up your Download folder in ‘Files’
  • Right click botpress-v12_14_2-linux-x64.zip

It will look like the following:

Right Click Example Linux

  • Click ‘Extract Here’
  • Double click to enter the folder (botpress-v12_14_2-linux-x64)
  • Right click an empty section in the botpress-v12_14_2-linux-x64 folder
  • Click ‘Open in Terminal’
  • Type the following command


Press 'Enter'


Do the following commands:

wget https://s3.amazonaws.com/botpress-binaries/botpress-v12_14_2-linux-x64.zip

unzip botpress-v12_14_2-linux-x64.zip

cd botpress-v12_14_2-linux-x64/


That's it! Yes, the Botpress server is now running at http://localhost:3000

With that out the way, let’s delve into the more detailed version.

Core Concepts


Botpress is written primarily in JavaScript, well it’s written mostly in TypeScript, which allows for static checking of JavaScript, but it’s still JavaScript. When your Botpress server is running you will interact with the back-end from a web browser (http://localhost:3000) by default. It is possible to program chatbots solely through the ‘Flow’ editor (pictured below), however you will lose out on a lot of functionality if you rely on this alone. Don’t worry if you’re not fluent in JavaScript as you will pick up the necessary syntax along the way! I will explain tricks to find these syntax in another post.

Botpress Flow Editor example

Botpress Flow editor, Cyklon Helper Bot Start Node

It is recommended that you have 64GB available disk space and at least 4GB of RAM, see. A Botpress chatbot receives data from a channel (e.g. Web, Slack, Facebook Messenger), processes it and then executes flows based on rules. Below is the processed visualised courtesy of Botpress:

Botpress lifecycle

Source Botpress

If you want or need more detailed information about the whole process, visit the Botpress Docs directly. Botpress uses a database to store information. By default SQLite is used, however it is recommended (by Cyklon IT Solutions, me, and Botpress themselves) to instead use a PostgreSQL database. There are a few reasons to use PostgreSQL instead of SQLite, namely:

SQLite vs. PostgreSQL

PostgreSQL has:

  • Better performance
  • Support for JSON (JavaScript Object Notation)
    • Handy as Botpress uses JSON a lot!

Preparing your environment

Dependencies - none, wait what?!

Okay, so that’s a bit of a lie – but not really. If you used the earlier ‘quick start’ guide to get a Botpress server up and running there are no dependencies, however, by default Ubuntu does not come with PostgreSQL pre-installed.


I was originally going to include a GUI guide in this section but decided against it. It is honestly so much easier to do these next steps in the Terminal – so it’s an idea to get accustomed to using the command line.


PostgreSQL can be easily installed using the command:

sudo apt update && sudo apt install postgresql

Note: You can also install the optional package, “postgresql-contrib” but it’s not necessary. I haven’t found any benefit to installing it because all we’ll be doing is creating a PostgreSQL user and database.

Now we need to create a PostgreSQL user and database. Use the following command to switch to the PostgreSQL ‘postgres’ user account.

sudo su postgres -

To enter PostgreSQL we then type the following:


The Terminal prompt should now look like this:


Great! In order to create our Botpress user, we use the syntax:

CREATE USER botpressuser WITH PASSWORD ‘yourpasswordhere’;

It’s important to note the username does not have quotations, but the password does. Personally, I prefer only including alphanumeric characters (letters and numbers) in the password so you don’t have to worry about escaping any characters. Also, make sure you put the semicolon at the end of the command. Note down these details because we need them later. To exit PostgreSQL type:


and then:


to return to our normal Terminal prompt.

Almost there! To create the database, we use:


We’ve created a PostgreSQL user and database, but Botpress doesn’t know about it. Let’s tell Botpress where it can find this information – and to use it! In order to do this we need to create an environment file in the extracted directory of Botpress (the same folder where the “bp” executable file is). Type the following:

nano .env

This creates a file called “.env” and opens it in the ‘nano’ text editor. Type the following:

DATABASE_URL=postgres://botpressuser:[email protected]:5432/botpressdb

On the next line, put:


and finally on the next line:


Close the file by pressing ‘CTRL + X’ and press ‘Y’ to accept the changes. That’s it! When you run


Botpress will be using PostgreSQL. You can double check this by navigating to ‘Production Checklist’ in Botpress. Green check marks will appear next to ‘Use a Postgres database’ and ‘Use the database BPFS storage’, similar to the image below:

Botpress Production Checklist

Botpress ‘Production Checklist’

If you followed the above steps yours will look different to this, but don’t fret because my installation is just configured differently!

Thanks for reading and I hope this helped you!

The featured image is from Botpress

Comments (0)

No comments at this moment

New comment


You can try some popular tags here:


No account?
Create an Account