Gebo.ai setup guide · Step 1 of 7
Install Gebo.ai with Docker
Download the reference Docker Compose file and start Gebo.ai with the four databases it uses. Two commands, then a few minutes of downloading.
- Time
- About 15 minutes, mostly the first download of the images (a few GB).
- You need
- A server with Docker Engine and Docker Compose v2 (Linux), or Docker Desktop on Windows 10/11 or macOS. About 10 GB of memory available to Docker.
- Network
- Internet access to GitHub and Docker Hub. Port 12999 reachable from your users’ PCs.
1Prepare the server
Install Docker following docs.docker.com/engine/install (Linux) or Docker Desktop (Windows, macOS). Then check that Docker Compose v2 is there:
docker compose version
docker compose, with a space. The old docker-compose 1.x program is retired and does not read this file.2Download the compose file and start Gebo.ai
Create a folder for Gebo.ai, download the file into it and start it:
mkdir gebo-ai && cd gebo-ai curl -O https://raw.githubusercontent.com/geboai/Gebo.ai/develop/dockers/docker-compose-deploy/docker-compose.yml docker compose up -d
On Windows PowerShell write curl.exe -O instead of curl -O.
Or download it by hand: open the compose file on GitHub, click Download raw file and save it as docker-compose.yml in a folder named gebo-ai. Then, in that folder, run docker compose up -d.


docker compose up -d downloads the images, creates the data volumes and starts the five containers. Gebo.ai starts last, when its four databases are healthy.3Check that everything runs
docker compose ps

The first start of Gebo.ai takes 1-3 minutes. Then open http://<server address>:12999/ in a browser and continue with step 2.
4Good to know
- Data: everything is kept in Docker volumes named
gebo-monolith_*. They survive restarts and upgrades; onlydocker compose down -vdeletes them. Back upgebo-monolith_gebo-mongoandgebo-monolith_gebo-worktogether. - Work directory: the documents Gebo.ai mirrors, its caches, the uploads and the chat sessions live in
/opt/gebo.ai/work, thegebo-workvolume. Setup → Platform → Gebo.ai work directory shows it, already set. On a Linux package or Windows installation, choose it there once, before anything else: an empty folder the service can write to, such as/var/gebo-ai/data. - Upgrades: in the gebo-ai folder, run
docker compose pullanddocker compose up -d. - Firewall: the databases listen only on the server itself. Only Gebo.ai is reachable from the network, on port 12999: open it for your users, for example
sudo ufw allow 12999/tcp. - HTTPS: Gebo.ai answers in plain HTTP. To serve it over HTTPS follow Part A of the Gebo.ai Production Hardening Manual (
docs/GEBO-HARDENING-MANUAL.mdin the Gebo.ai repository).
5Alternative: the ready-made virtual appliance
If you prefer a virtual machine to Docker, gebo.ai/downloads offers Ubuntu Server 24.04 with Gebo.ai already installed, as VMware/ESXi (VMDK), Hyper-V (VHDX) and Proxmox/KVM (qcow2) images.
- Import the image in your hypervisor and start the virtual machine (Hyper-V: generation 1).
- Change the passwords listed in the archive’s
accounts.txt, as the downloads page explains. - Open http://<virtual machine address>:12999/ and continue with step 2.