Skip to main content
BoardPulse AI ships as a set of Docker Compose services that start together with a single command. This page covers every service in the stack, the startup sequence, port mappings, and how to manage the running environment.

​
Services

The docker-compose.yml defines six services. The ollama service is gated behind the local-models profile and only starts when you opt in.

api

FastAPI backend on port 8000. Handles chat queries, SQL execution, workspace management, and the OpenAI-compatible endpoint.

admin

Next.js admin panel on port 3001. Use it to verify your database connection and inspect the detected schema.

postgres

PostgreSQL 16 on port 5432. Stores BoardPulse AI’s internal data and, by default, seeds demo business data on first run.

redis

Redis 7 on port 6379. Used by the API for caching and task coordination.

openwebui

Open WebUI on port 3002. The primary chat interface for end users, pre-configured to talk to the api service.

ollama

Ollama on port 11435 (optional). Serves local AI models. Only starts when you use the local-models profile.

​
Port mapping

​
Starting the stack

1

Copy and configure the environment file

Copy .env.example to .env and open it in your editor:
At minimum, set DEFAULT_SOURCE_DATABASE_URL to point at the database you want BoardPulse AI to query. All other values have sensible defaults for local development.
2

Build and start all services

Run the following command from the repository root. This builds the api and admin images and starts all services in the background:
To include the Ollama local-model service, use the local-models profile instead:
3

Verify all services are running

Check that every container is healthy before proceeding:
All listed services should show a running status. If any container has exited, check its logs with docker compose logs -f <service>.
Always use docker compose up -d to apply changes from .env — not docker compose restart. The restart command does not reload environment variable changes.

​
Viewing logs

Stream live logs from any service using the -f flag:
Replace api with any service name (admin, postgres, redis, openwebui, ollama) to tail its output.

​
Stopping the stack

To stop all running containers without removing their data volumes:
To also delete all persistent data (database, Redis, Open WebUI, and Ollama model files), add the -v flag:
Running docker compose down -v permanently deletes all stored data, including the PostgreSQL database and any Ollama models you have pulled. Only use this flag when you intentionally want a clean state.