Configuration reference

Every environment variable SkillNet reads, what it defaults to, and — the part that is easy to get wrong — whether setting it in .env actually changes anything.

The rule that explains most surprises

.env never reaches a container by itself. .dockerignore keeps it out of the image, and no service in any compose file declares env_file:. The API’s pydantic-settings does say env_file=".env", but inside the container there is no such file to read.

So a variable takes effect in Docker only if the service that needs it lists it in its environment: block, as VAR: ${VAR:-default}. Compose reads .env from the repo root at docker compose up time and interpolates it there. That indirection is why a setting can be real in src/config.py, documented, spelled correctly in your .env, and still do nothing.

The Reachable in Docker column below records exactly that, per variable:

A No variable still works when the API runs outside Docker (uv run uvicorn …), because then pydantic-settings really does read .env. Only the Docker path drops it.

Required

POSTGRES_PASSWORD is interpolated into postgresql+asyncpg://user:PASSWORD@db:5432/db without escaping. A @, :, /, # or ? splits that URL, and the resulting connection error never mentions the password.

Models and providers

The 768-dimension contract

document_chunks.embedding is vector(768), pinned by hand in migration 0008. The ORM declares Vector() with no size on purpose, so the database is the only place that number lives. EMBEDDING_DIMENSIONS does not decide the schema — it tells the provider how many dimensions to return, and it has to agree with the column or every chunk insert fails.

services/embedding_check.py compares the two at startup and reports the result in GET /health, because otherwise the mismatch first appears inside an ingestion except.

Three cases:

• text-embedding-3-small / -large accept a dimensions parameter and truncate for you. SkillNet sends it, so they return 768. Nothing to do.
• A model whose native output is already 768 — nomic-embed-text, multilingual-e5-base, paraphrase-multilingual — also fits. Nothing to do.
• Any other dimension (multilingual-e5-small is 384, e5-large is 1024) needs a migration of the column and a re-ingestion of every document. That is not a .env edit.

Owner account and workspace

/setup has to be public — it is how the first account gets created — so until an owner exists, whoever reaches it first becomes the owner. That is fine on localhost and not fine behind a tunnel started before the account. When the window closes, restart the api container for another one, or use the X-Setup-Token printed in the API log at startup.

Serving, sessions and exposure

COOKIE_SECURE and the exposure overlays

docker-compose.yml reads ${COOKIE_SECURE:-false}, because the default stack speaks plain HTTP on localhost and a Secure cookie would never be sent back.

The three exposure overlays — docker/compose/caddy.yml, cloudflared.yml and quicktunnel.yml — all read ${COOKIE_SECURE:-true}, because each of them puts real TLS in front.

The :- default only applies when the variable is unset. An active COOKIE_SECURE= line in .env therefore wins over all three overlays, including a false you copied from an example and forgot. That is why .env.example ships the line commented out: leave it that way unless you specifically mean to override an overlay.

Sign in with Google

What Google may do, by workspace mode

The credentials turn the feature on. What it is allowed to do comes from the organization’s workspace_mode, not from configuration (src/services/google_oauth.py):

• organization — Google only signs in people who already have an account created by an administrator. An uninvited address is refused and no account is created. SkillNet scopes data per organization, so open registration would be a side door into a company’s data.
• individual — Google may also create the account, because in a one-person workspace there is nobody to do the inviting.

In both modes Google must report the address as verified. An unverified one is refused: matching on a claim Google does not stand behind would hand the matching account to whoever typed the address.

Get the credentials at https://console.cloud.google.com/apis/credentials → “Create credentials” → “OAuth client ID” → “Web application”. For the default local stack the redirect URI is http://localhost:3000/api/v1/auth/google/callback; Google compares the whole string, trailing slash included.

Text to speech

Without a working key the two consumers degrade differently. The mascot’s live voice (POST /api/v1/tts/synthesize) hard-fails with 500 and does not fall back to the offline voice; the frontend swallows it, so the learner simply gets no audio. Podcast generation falls back ElevenLabs → Azure → offline eSpeak NG, so a podcast is always produced, only robotic.

Media is baked at seed time and stored content-addressed: learners hear whatever voice was generated when the seed ran, not a per-user render.

Images and media artifacts

MEDIA_ASSETS_DIR and TTS_CACHE_DIR default to paths relative to the working directory, which is image filesystem. Compose overrides both to /data/... so the named volumes hold them; without that, every --build threw the generated media away.

Without an image key the capability is refused up front with a reason, rather than accepted and failed later.

Provider retries and reasoning models

None of these reach the container. They are listed because they are real settings that work outside Docker, and because the gap is worth knowing before you spend an afternoon on it.

A reasoning model bills its chain of thought against the same max_tokens as the answer, so without headroom it can spend the whole budget thinking and return empty content, which the runtime reads as an invalid program.

Dynamic courses and the render pipeline

A course is served by v2 when it has delivery_mode='dynamic' and schema_status='validated'. There is no global flag; src/services/course_delivery.resolve_delivery is the single decision point.

Running on a local model

Used by docker/compose/ollama.yml, which is an overlay rather than a profile because it has to rewrite api’s environment, and a profile cannot do that.

docker compose -f docker-compose.yml -f docker/compose/ollama.yml up -d --build

The two prefixes differ on purpose. ollama_chat/… and ollama/… are litellm’s native Ollama providers: litellm appends /api/chat or /api/embeddings itself, so the base URL carries no /v1. Mixing a /v1 base with an ollama/ prefix produces a 404.

On CPU this is slow — roughly 185 s to render one lesson screen with a 7B model, measured 2026-07-27. Useful offline; not comfortable for real use.

Optional services

api-fixtures shares SECRET_KEY and the database with api, so it is not a sandbox — its session cookies are valid against the real API. It is published on 127.0.0.1 for that reason. The bundled nginx proxies to api unconditionally, so the SPA never uses it: to run the whole stack keyless, set LLM_MODEL=fixture/local and EMBEDDING_MODEL=fixture/local instead.

Do not set

These are in src/config.py and in some compose files, and setting them in .env is either inert or a way to break the install. They are deliberately absent from .env.example.

Related

• RUNNING.md — the five steps to start the project.
• docker-deployment.md — the services and what each one does.
• security.md — the threat model behind the defaults above.
• tuning.md — generation-quality dials, most of which are code, not env vars.