How to Deploy Botpress with Docker: A Step-by-Step Guide

Deploy Botpress in 10 Minutes — Here's Exactly How

I remember my first Botpress deploy. I thought it would take 30 minutes, maybe an hour if the documentation was confusing. It took 8 minutes from docker pull to a working chatbot answering "hello" in my browser. Let me walk you through exactly how I did it — including the mistake that cost me 20 extra minutes so you can skip it.

Prerequisites (Keep It Simple)

Step 1: Pull the Image

This part is dead simple. The official Botpress image is about 1.2GB, so grab a coffee while it downloads.

docker pull botpress/server:latest

While that's pulling, create a directory for your Botpress data:

mkdir -p ~/botpress/data

Step 2: Run the Container

Here's the command I use. It exposes Botpress on port 8080 and persists your data to the host:

docker run -d \
  --name botpress \
  -p 8080:8080 \
  -v ~/botpress/data:/data \
  -e BP_MODULE_NLU_DUCKLING_URL=http://localhost:8080 \
  -e BP_MODULE_NLU_ENABLED=true \
  botpress/server:latest

Step 3: Check It's Running

docker ps --filter name=botpress

You should see the container with status "Up" and port 0.0.0.0:8080->8080/tcp.

Now open your browser and go to http://localhost:8080. You should see the Botpress setup wizard.

Step 4: Initial Setup (2 Minutes)

1. Create an admin account (email + password)
2. Select "Create a new bot"
3. Pick a template — I recommend starting with "Empty Bot" or the "Hello World" template
4. Give your bot a name and click Create

If you see the Botpress Studio at this point — congratulations, you're live. If not, check the container logs:

docker logs botpress --tail 20

Step 5: Add a Simple Intent

Let's train your bot to say hello back. In the Botpress Studio:

1. Go to the NLU tab
2. Create a new intent called greeting
3. Add example phrases: "hello", "hi", "hey there", "good morning", "what's up"
4. Go to the Flows tab
5. Add a new node connected to the greeting intent
6. Set the response to: Hey there! 👋 I'm running on Botpress. How can I help you?
7. Click "Train" in the NLU tab

That's it. Open the Webchat widget from the Botpress Admin panel, type "hello", and watch it respond.

Performance Notes (From My Setup)

What's Next?

Once you have the basics running, here are the next things I'd explore:

• Webchat customization — Change colors, fonts, and position in the Botpress config panel
• LLM integration — Connect GPT-4 or Claude for natural conversation fallback
• Human handover — Route specific intents to live agents
• Channel deployment — Connect WhatsApp or Telegram through the Channel tab

Botpress is one of those rare open-source projects where the self-hosted version genuinely rivals the enterprise offerings. Give it a try — I think you'll be surprised how far 10 minutes gets you.