.env file at the root of the project. Copy the provided example file to get started, then adjust values for your environment. All settings have sensible defaults for local development — production deployments will need at minimum a real database URL and a model provider.
Getting started
1
Copy the example file
2
Edit .env for your environment
Open
.env in your editor and update values as described below. At a minimum, set DEFAULT_SOURCE_DATABASE_URL, DEFAULT_MODEL_PROVIDER, and the corresponding API key or Ollama settings.3
Restart the stack
Docker Compose does not hot-reload environment variables. After saving
.env, bring the stack back up:App settings
General application identity and server configuration.string
default:"development"
Runtime environment label. Set to
production in production deployments. Affects logging verbosity and error detail.string
default:"0.0.0.0"
Host address the API server binds to. The default binds to all interfaces inside the container.
integer
default:"8000"
Port the API server listens on inside the container.
string
default:"BoardPulse AI API"
Display name returned in API metadata responses.
string
default:"/api/v1"
URL prefix for all v1 API routes.
string
default:"http://localhost:3000,http://localhost:3001"
Comma-separated list of allowed CORS origins. Add your frontend domain here for production deployments.
Database
Settings that control the BoardPulse internal database and the client source database it queries.string
SQLAlchemy connection URL for the BoardPulse internal database. This stores workspaces, query history, and schema cache — not your business data.
string
default:"default"
Identifier for the default workspace created on first boot. Used when no workspace is explicitly specified in a request.
string
default:"same as DATABASE_URL"
SQLAlchemy connection URL for the source database BoardPulse AI queries. This is your business data. Falls back to
DATABASE_URL if not set. See Connecting a database for supported URL formats.string
default:"public"
Database schema to inspect and query. Leave blank to use the database default (
public for PostgreSQL).string
default:"sales_orders,invoices,inventory_items"
Comma-separated allowlist of table names the AI may query. Only these tables are exposed to the model and the SQL guardrail layer.
integer
default:"200"
Maximum number of rows returned by any single query. Increase with caution on large datasets.
string
default:"/tmp/boardpulse-exports"
Directory where CSV and XLSX export files are written before download. Make sure this path exists and is writable inside the container.
boolean
default:"true"
When
true, the API seeds sample sales, invoice, and inventory data into the internal database on first boot. Useful for evaluating BoardPulse AI without connecting a real database.Redis
string
default:"redis://redis:6379/0"
Connection URL for the Redis instance used for caching and background task queuing.
Model providers
Controls which AI provider generates SQL queries. See Configuring model providers for detailed setup.string
default:"mock"
Default provider used when a request does not specify one. Valid values:
mock, cloud, local.string
default:""
API key for OpenAI or any OpenAI-compatible provider. Leave blank when using
mock or local mode.string
default:"gpt-4.1-mini"
Model name passed to the OpenAI-compatible endpoint.
string
default:"https://api.openai.com/v1"
Base URL for the OpenAI-compatible API. Override to point at a different provider such as Azure OpenAI or a local proxy.
boolean
default:"false"
Enable the Ollama local model backend. Set to
true when running Ollama alongside the stack.string
default:"http://ollama:11434"
URL of your Ollama instance. Inside Docker Compose this points to the
ollama service.string
default:"qwen3:8b"
Ollama model tag to use for query generation.
Open WebUI
Variables used by the OpenAI-compatible endpoint and the Open WebUI integration.string
default:"boardpulse-dev-key"
Bearer token clients must send to the BoardPulse OpenAI-compatible endpoint. Change this to a strong random value in production.
string
default:"replace-me-with-a-long-random-secret"
Secret key used by Open WebUI for session signing. Must be a long, random string in production.
boolean
default:"false"
When
true, Open WebUI also exposes the Ollama native API alongside the OpenAI-compatible interface.Frontend
string
default:"http://localhost:8000/api/v1"
API base URL used by the Next.js frontend at build time and in the browser. Must be reachable from the user’s browser — not the Docker network name.
string
default:"http://api:8000/api/v1"
API base URL used by server-side Next.js code. Uses the Docker Compose service name (
api) so requests stay on the internal network.Postgres
Credentials for the managed PostgreSQL container included in the Docker Compose stack.string
default:"boardpulse"
Database name created inside the Postgres container.
string
default:"boardpulse"
Username for the Postgres container.
string
default:"boardpulse"
Password for the Postgres container. Change this to a strong, unique value in any non-local environment.