Prepare the runtime layers before you start individual services.
The setup pages assume you have the required runtimes and can reach the services they describe. This docs repository does not contain the services themselves.
Current Docker Reality
The setup instructions below are intentionally high level. Use them as a checklist before following the service-specific pages.
Local tools you need before containers
Runtime
Node.js
22.x
Required for the backend and the Vite-based client applications.
Runtime
Python
3.11 preferred
Required for the AI service setup page.
Containers
Docker Engine + Compose
Docker v24+ and Compose v2+
Best used for infrastructure services like MongoDB, Redis, MinIO, and InfluxDB.
Source control
Git + npm
repo checkout and package installs
Needed to fetch the repo and install application dependencies that are not being built inside containers.
Containers the codebase actually expects
These are the backing services that appear in the current runtime code, service configuration, and Compose files. Some are hard requirements, others are feature-specific.
Layer | Container | Why it exists | Requirement level |
|---|---|---|---|
Core data | MongoDB | Primary datastore for the backend and also used by the AI service for session, voice, and chat persistence. | Required |
Queueing | Redis | Required by the AI service startup checks and used for RQ-backed chat, reports, and worker flows. Also supports optional backend session storage. | Required for AI runtime |
Time-series | InfluxDB | Used by the AI service for EEG metrics, training events, and other time-series data paths. | Required for AI runtime |
Object storage | MinIO | Used by the backend file upload service by default and also used by the AI service for artifacts, models, datasets, and reports. | Strongly recommended |
Messaging | Mosquitto | Supports MQTT-based notifications and device integration paths in the backend. | Optional |
Recommended Docker-first setup by layer
Treat infrastructure as the Docker boundary first. Then run the backend and AI service either directly on the host or in their own containers once the data layer is stable.
Layer 1
Foundation Containers
MongoDB, Redis, InfluxDB, MinIO
Start these first. They are the common backing services referenced by the backend and the active AI runtime.
Layer 2
Optional Messaging
Mosquitto
Add MQTT only if you need notification or device-message flows during local development.
Layer 3
Application Services
backend and AI service
Run these after the dependency layer is reachable. They each have their own environment and startup assumptions.
Layer 4
Client Applications
platform or webapp
Start a client only after the backend is healthy and the AI service is available for any required analysis or chat flows.
What the current Compose files tell us
backend stack
Broad dependency stack, but stale AI wiring
It defines MongoDB, Redis, MinIO, InfluxDB, Mosquitto, backend, and an AI service. But the AI build context is not aligned with the docs repository, so this file should not be treated as a trustworthy full-stack source of truth as-is.
AI service stack
Better AI-specific stack, but missing MongoDB
It defines Redis, InfluxDB, MinIO, the API, the worker, and optional Nginx. But the AI service code initializes MongoDB and blocks startup on MongoDB by default, while this Compose file does not include a MongoDB service.
Containers to pull if you want the least-fragile starting point
Suggested images
Infrastructure images used by the current stack
mongo:7.0
redis:7-alpine
influxdb:2.7
minio/minio:RELEASE.2024-01-31T20-20-33Z
eclipse-mosquittoUse Compose Files Carefully
The current docs should not tell users to run a root docker compose up from
the repository because there is no accurate root Compose file. Use Docker to
bring up the infrastructure layer, then start the backend and AI service with
verified environment settings.