Home Konversio 101 Quick start with Docker Compose

Quick start with Docker Compose

Last updated on Jun 05, 2026

Quick start with Docker Compose

The fastest way to run Konversio is with Docker Compose. This guide covers the minimal steps to get a working instance on a single server.

Prerequisites

  • Docker and Docker Compose installed on your server
  • A server with at least 2 GB RAM (4 GB recommended if you plan to run Pilot)
  • Ports 3000 (or 80/443 if you set up a reverse proxy) accessible

You do not need Ruby, Node, or any other runtime installed locally. Everything runs inside containers.

Step 1: Copy the environment file

Clone the repository and copy the example environment file:

git clone https://github.com/Konversio-Org/konversio.git
cd konversio
cp .env.example .env

Open .env and set the values that matter for a first run. At minimum, review SECRET_KEY_BASE (generate one with openssl rand -hex 64) and the database credentials. You can leave most other values at their defaults for a local test.

Step 2: Start the containers

docker compose up -d

This pulls the images and starts the application, Sidekiq worker, PostgreSQL, and Redis. The first pull takes a few minutes. Subsequent starts are fast.

Step 3: Prepare the database

docker compose exec rails bundle exec rails db:chatwoot_prepare

This creates the database schema and seeds the initial data, including the default administrator account.

Step 4: Access the interface

Open your browser at http://localhost:3000. You should see the Konversio login screen.

Default credentials

The seed creates a default administrator account:

  • Email: admin@example.com
  • Password: administrator

Change this password immediately after logging in. See the next article for a first-login checklist.

What to do next

At this point you have a running instance with no inboxes, no agents, and a default password that needs changing. The practical next steps are:

  1. Change the default admin password and email
  2. Create your first inbox
  3. Invite agents
  4. Optionally configure Pilot

These are covered in detail in First login: what to set up first.

Production considerations

For anything beyond a local test, you will want to:

  • Put a reverse proxy (nginx or Caddy) in front with TLS
  • Set a real FRONTEND_URL in .env so email links resolve correctly
  • Configure an SMTP server for outbound email (SMTP_ADDRESS and related variables)
  • Set up regular PostgreSQL backups

The Docker Compose setup is production-capable for small to mid-sized teams. For larger deployments, consider separating the database and Redis onto dedicated hosts.