Reference

Configuration

Every setting lives in .env. Copy .env.example to .env and fill in your values. Change only what you need — sensible defaults are already filled in.

Services and Ports

ServiceURLLogin
SmartKMS apphttp://localhost:8000see User Manual
API documentationhttp://localhost:8000/api/docsnone
Health checkhttp://localhost:8000/healthnone
MinIO console (MinIO backend only)http://localhost:9001minioadmin / minioadmin
ONLYOFFICE editorhttp://localhost:8080internal
PostgreSQLlocalhost:5432postgres / your password
Ollamahttp://localhost:11434internal

Environment Variables

Database

# PostgreSQL connection string
# Format: postgresql+asyncpg://USER:PASSWORD@HOST:PORT/DATABASE
DATABASE_URL=postgresql+asyncpg://postgres:CHANGE_ME_PASSWORD@localhost:5432/dbskms

JWT Authentication

# start.bat / start.sh replace this placeholder with a random key
# (or generate one yourself: openssl rand -hex 32)
SECRET_KEY=CHANGE_ME_GENERATE_SECURE_KEY

# JWT signing algorithm (default: HS256)
ALGORITHM=HS256

# Token expiration times
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# Brute-force protection: this many wrong passwords in a row locks the
# account for LOCKOUT_MINUTES (defaults shown)
# MAX_LOGIN_ATTEMPTS=5
# LOCKOUT_MINUTES=15

LLM Configuration (Ollama — Local, Free)

Everything "AI" goes through Ollama: semantic search and related documents use the embed model; the AI summary, key points, automatic tags, chat answers and chat titles use the chat model; OCR of scans and photos uses the vision model. Folder suggestions reuse the stored embeddings. If Ollama is down, uploads still succeed — they just get no summary, tags or embedding until re-processed.

# Ollama server URL
# Docker: use http://host.docker.internal:11434 when Ollama runs on host
# Native: use http://localhost:11434
OLLAMA_BASE_URL=http://localhost:11434

# Models. start.bat / start.sh pull all three on first run; by hand:
#   ollama pull qwen2.5:3b
#   ollama pull nomic-embed-text
#   ollama pull llava
OLLAMA_CHAT_MODEL=qwen2.5:3b
OLLAMA_EMBED_MODEL=nomic-embed-text
# OLLAMA_VISION_MODEL=llava

# Not used - every AI feature runs on Ollama. Exists only so a stray
# OPENAI_API_KEY in the environment doesn't break startup.
# OPENAI_API_KEY=
Don't change the embed model once documents exist. Every document's stored embedding was produced by OLLAMA_EMBED_MODEL, and vectors from different models aren't comparable — switching silently breaks semantic search, related documents and folder suggestions for everything already uploaded until each file is re-processed. A bigger chat model (e.g. qwen2.5:7b) can be swapped in freely; it gives better summaries and tags at the cost of speed and ~8 GB RAM.
Content-moderation models Sensitive-content screening runs once per approval, not per chat message, so it can afford a slower/more accurate model than day-to-day chat. If it's flagging documents that clearly aren't sensitive, point these at a stronger model (pulled separately, e.g. ollama pull qwen2.5:7b) without changing the faster model used for chat.
OLLAMA_MODERATION_MODEL=qwen2.5:3b
OLLAMA_MODERATION_VISION_MODEL=llava
AI on another server OLLAMA_BASE_URL can point at an Ollama on another machine, such as a GPU server on the campus network (http://192.168.x.x:11434); it needs the same three models pulled. That Ollama has no password, so keep its port 11434 off the internet (firewall it to the SmartKMS server). To move only the chat model, set an OpenAI-compatible server, such as vLLM or another Ollama's /v1; while it doesn't answer, chat falls back to the chat model on OLLAMA_BASE_URL:
CHAT_API_URL=http://192.168.1.50:8000/v1
CHAT_API_MODEL=Qwen/Qwen2.5-3B-Instruct
CHAT_API_KEY=

NudeNet Image Screening

# The NudeNet nudity classifier runs as its own container (skms_nudenet)
# and is called over HTTP - see nudenet_service/
NUDENET_SERVICE_URL=http://localhost:8001

Started automatically by the launchers and by docker compose up. If the service is unreachable, image uploads are still screened by the vision model alone; if that also can't complete, the image is held in pending for manual review rather than auto-approved.

Document Storage — MinIO, Google Drive or SharePoint

Uploaded files live in one of three places. start.bat / start.sh ask which on a fresh install and set this for you; MinIO isn't even started when Drive is picked.

minio (default)google_driveonedrive
What it isAn S3-compatible bucket run locally in DockerA folder in an organization's existing Google Drive, accessed by a service accountA SharePoint site's Documents library (or one person's OneDrive) in the university's Microsoft 365, through Microsoft Graph
Cost / limitsFree; limited only by your diskAPI is free, but storage counts against that Google account's quota — 15 GB free on a personal account, a Workspace Shared Drive for anything realFree with Microsoft 365; the site's storage quota applies
DownloadsBrowser fetches straight from MinIO via short-lived presigned linksProxied through the app (Drive's own share links never expire, so they can't be handed to the browser)Proxied and streamed through the app, the same way
UsesS3_* settings belowGOOGLE_DRIVE_* settings belowONEDRIVE_* settings below
STORAGE_BACKEND=minio
Switching later is safe. A document remembers which backend it was stored in, so files uploaded before a switch keep working — only new uploads go to the new place. Keep the old storage running until you move those files: the startup log says how many are left there, and python scripts/move_files.py moves them into the current storage (it copies each file, checks the copy, points the document at it, then deletes the old one; --dry-run only lists them). On the Docker deployment, run it with docker compose --env-file .env.deploy -f docker-compose.deploy.yml exec api python scripts/move_files.py.

Google Drive (only read when STORAGE_BACKEND=google_drive)

The launcher prompts for both values when you choose Drive — paste or drag in the downloaded key file (it's copied to the git-ignored secrets/ folder and the account's e-mail is printed for step 5) and paste the folder's URL — and writes them to .env. If it finds an .env that says google_drive with either still blank, it asks again on the next run. To set them up by hand:

  1. console.cloud.google.com → create/select a project → APIs & Services → Library → enable Google Drive API.
  2. APIs & Services → Credentials → Create credentials → Service account → open it → Keys → Add key → JSON. A .json file downloads.
  3. Save it as secrets/google-drive-key.json in the project (or anywhere — absolute paths work) and point GOOGLE_DRIVE_CREDENTIALS_FILE at it.
  4. In Drive, create the folder documents should go in — ideally inside a Workspace Shared Drive. A service account has no storage quota of its own, so a folder in someone's My Drive stops accepting uploads the moment that person's own quota is full; a Shared Drive's quota belongs to the whole Workspace.
  5. Share that folder with the service account's e-mail (the client_email field inside the JSON, name@project.iam.gserviceaccount.com) as Editor / Content manager.
  6. Copy the folder id from its URL — the part after /folders/.
GOOGLE_DRIVE_CREDENTIALS_FILE=secrets/google-drive-key.json
GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz0123456   # from drive.google.com/drive/folders/<this>

One sub-folder per organization (named by its short code, e.g. CIT) is created under that folder automatically on first upload.

SharePoint or OneDrive (only read when STORAGE_BACKEND=onedrive)

SmartKMS signs in as an Azure app of its own (nobody has to stay signed in) and stores each file as <unix time>_<month>_<year>_<md5>.<ext> in one folder, created on first use. Files over 4 MB upload in 10 MB pieces, so the 500 MB limit works.

  1. Microsoft Entra → App registrations → New registration, Accounts in this organizational directory only. Note the Application (client) ID and Directory (tenant) ID.
  2. Certificates & secrets → New client secret. Copy its Value, not its Secret ID.
  3. API permissions → Microsoft Graph → Application permissions → Files.ReadWrite.All → Grant admin consent. (Files.ReadWrite.All reaches every library in the tenant; Sites.Selected limits the app to the one site, which is safer.)
  4. Create the SharePoint site for SmartKMS, or pick one.
STORAGE_BACKEND=onedrive
ONEDRIVE_TENANT_ID=
ONEDRIVE_CLIENT_ID=
ONEDRIVE_CLIENT_SECRET=
# or keep the secret out of .env: a file holding only the secret
# ONEDRIVE_CLIENT_SECRET_FILE=secrets/onedrive-secret.txt
ONEDRIVE_SITE=https://your-tenant.sharepoint.com/sites/KSMS-UPLOADS
# no site: one person's OneDrive instead
# ONEDRIVE_USER=someone@school.edu
ONEDRIVE_FOLDER=ksms_uploads
Never paste the secret into a chat, an AI tool or a ticket. Microsoft scans for leaked secrets and can revoke them. Put it in .env or its own file.

MinIO (only read when STORAGE_BACKEND=minio)

# host:port of the MinIO API (not the web console, which is 9001)
S3_ENDPOINT=localhost:9000

# Must match what the MinIO container was started with. The local
# docker-compose.yml uses minioadmin / minioadmin (also the console login).
# Production (.env.deploy) must use its own long random pair - setup_db.py
# refuses to start a production stack on these.
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

# Bucket name (created automatically if it doesn't exist)
S3_BUCKET=smartkms

# true only if the API server reaches MinIO over https
S3_SECURE=false

# The address the BROWSER uses for downloads/previews. Same as S3_ENDPOINT
# when everything is on one machine; otherwise:
#   other devices on the LAN open the app    -> this machine's IP:9000
#   app in Docker, browser on the host       -> host.docker.internal:9000
#   production behind a reverse proxy        -> files.your-domain.edu
S3_PUBLIC_ENDPOINT=localhost:9000
# Whether THAT browser-facing address is https (defaults to S3_SECURE) -
# set when a TLS-terminating proxy sits in front of MinIO
# S3_PUBLIC_SECURE=false

Redis

# Started by docker-compose.yml and reserved for shared state between API
# workers; the app does not read this yet. Docker deploy: redis://redis:6379
REDIS_URL=redis://localhost:6379

CORS

# Allowed origins (JSON array format)
BACKEND_CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:5500","http://localhost:5500","http://localhost:8000"]

Application

# development | staging | production
#   development  SQL statements are echoed to the console
#   production   login cookies are marked Secure (https only); setup_db.py
#                refuses CHANGE_ME secrets and creates no demo accounts
APP_ENV=development

# Largest single upload the server accepts, in megabytes
MAX_UPLOAD_SIZE_MB=500

# Admins see a "Storage is N% full" banner from this point; an upload that
# would leave less than STORAGE_RESERVE_MB free is refused with a message
STORAGE_WARN_PERCENT=80
STORAGE_RESERVE_MB=512

The Documents page reads the limit from the server, so its own size check and "Max … MB" text follow MAX_UPLOAD_SIZE_MB. Behind Caddy (the Docker deployment), also raise request_body max_size in deploy/Caddyfile above 500. Files over about 200 MB upload, search and download normally but can be slow to preview or edit in the browser.

Storage space. MinIO reports its disk, and SharePoint or OneDrive their quota. From STORAGE_WARN_PERCENT full, administrators see a banner on every page with the space used; when an upload would leave less than STORAGE_RESERVE_MB free, it is refused before anything is stored, the uploader is told to ask an administrator, and the Activity Log records it. Unknown capacity (a Google Drive with pooled storage) never blocks an upload.

ONLYOFFICE — Live Document Editing

One secret, set in one place

ONLYOFFICE_JWT_SECRET lives only in .env. docker-compose.yml passes the same value to the onlyoffice container and the API, so the two can't drift apart. start.bat / start.sh replace the CHANGE_ME placeholder with a random value on first launch and recreate the onlyoffice container to pick it up.

Don't keep the placeholder: it's public, and anyone who knows it can forge editor download and save tokens.

# Browser-facing URL for the editor's JS API
ONLYOFFICE_URL=http://localhost:8080

# Callback URL for document saving
# - Local development (API on host): http://host.docker.internal:8000 (Docker Desktop)
# - Linux with --add-host: http://host.docker.internal:8000
# - Production (API in Docker): http://api:8000
ONLYOFFICE_INTERNAL_CALLBACK_URL=http://host.docker.internal:8000

# JWT secret shared with the onlyoffice container (the launcher generates it)
ONLYOFFICE_JWT_SECRET=CHANGE_ME_ONLYOFFICE_SECRET

# Enable/disable JWT authentication
ONLYOFFICE_JWT_ENABLED=true

ONLYOFFICE_S3_ENDPOINT, present in older .env files, is no longer read: ONLYOFFICE fetches document bytes through the API (/api/documents/{id}/office-download) rather than from MinIO directly — which is also what lets it work with the Google Drive backend. It's harmless to leave in place. See Document Editing (ONLYOFFICE) for how these fit together.

Sign in with Microsoft (optional)

Lets people use their school Microsoft 365 / Entra ID account instead of a password. The login page only shows the button when MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET are set.

  1. Azure portal → Microsoft Entra ID → App registrations → New registration. For a school, "accounts in this organizational directory only" (single tenant) is usually right.
  2. Redirect URI (type Web): <the URL users open the app at>/api/auth/microsoft/callback — e.g. http://localhost:8000/api/auth/microsoft/callback while testing.
  3. API permissions → Add → Microsoft Graph → Delegated: openid, profile, email, User.Read (grant admin consent if your tenant requires it).
  4. Certificates & secrets → New client secret — copy the Value column (not the Secret ID). It expires; sign-in stops working when it does.
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=

# Who may sign in, on the Microsoft side:
#   common          any Microsoft account, personal or work/school
#   organizations   any work/school (Entra) account, from any tenant
#   <tenant GUID>   only accounts in that one directory  (recommended;
#                   "Directory (tenant) ID" on the registration's Overview)
MICROSOFT_TENANT_ID=common

# Only when the app is reached through a proxy/tunnel and the derived
# callback is wrong; must match the Redirect URI in Azure exactly
# MICROSOFT_REDIRECT_URI=

# Comma-separated e-mail domains allowed to sign in this way; blank = any
MICROSOFT_ALLOWED_DOMAINS=

# Blank: users with no SmartKMS account are refused. An org short code
# (CIT, CAS, ...): an account is auto-created there with the read-only
# Researcher role; an admin can promote it later.
MICROSOFT_AUTO_PROVISION_ORG=

Sign in with Google (optional)

Lets people use their school Google Workspace account (or a Gmail account) instead of a password. The login page only shows the button when GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET are set. This is a separate OAuth client, not the Google Drive service account.

  1. Google Cloud console → APIs & Services → OAuth consent screen: user type Internal limits sign-in to your Workspace domain; the only scopes needed are openid, email and profile.
  2. Credentials → Create credentials → OAuth client ID → Web application, with the authorized redirect URI <the URL users open the app at>/api/auth/google/callback, e.g. http://localhost:8000/api/auth/google/callback while testing.
  3. Copy the client ID and client secret into .env.
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=
# GOOGLE_OAUTH_REDIRECT_URI=
# Comma-separated e-mail domains allowed, e.g. "uls.edu.ph". Blank = any.
GOOGLE_OAUTH_ALLOWED_DOMAINS=
# Blank = only existing SmartKMS accounts; an org short code = create a
# Researcher account in that organization on first sign-in.
GOOGLE_OAUTH_AUTO_PROVISION_ORG=
Which Google accounts are trusted An address outside gmail.com is accepted only from a Google Workspace account managed by that same domain. A personal Google account registered with a school address is refused, because that address may since have been given to someone else.

Import from Google Drive / OneDrive (optional)

Adds or import from Google Drive and OneDrive buttons to the Documents upload area. People connect their own drive in a popup, pick files in SmartKMS's own file list, and the server copies them through the normal upload checks: file type, the 100 MB limit, sensitive-content screening, tags and search. Google Docs, Sheets and Slides are converted to Word, Excel and PowerPoint. Up to 20 files per import.

Each one reuses the sign-in client above, which must be set up first (Google, Microsoft), and needs two more things:

  • Google: enable the Google Drive API; on the OAuth consent screen add the scope https://www.googleapis.com/auth/drive.readonly; add the authorized redirect URI <the URL users open the app at>/api/import/google/callback.
  • Microsoft: in the app registration, API permissions → Microsoft Graph → Delegated → Files.Read; under Authentication add the Web redirect URI <the URL users open the app at>/api/import/microsoft/callback.
GOOGLE_DRIVE_IMPORT=true
ONEDRIVE_IMPORT=true
Read-only, for about an hour, nothing stored SmartKMS only asks to read files. The connection lasts as long as the provider's access token (about an hour) and is kept in the server's memory, never in the database: no refresh token and no password. Disconnect in the import window ends it at once. Restarting SmartKMS ends every connection.
Google's restricted scope drive.readonly is a restricted scope. With user type Internal (your Workspace domain only) it works straight away. An External app works only for its listed test users until Google verifies it.

Public Ask page (optional)

A full-page question-and-answer page at /ask (for example https://skms.dev/ask) that anyone can open without signing in, such as from a link on the university website. It answers only from approved documents in folders with the name you set below, so internal documents never reach the public, whatever their visibility inside SmartKMS.

  1. Signed in as an administrator, create a folder named, for example, Public Ask, and move into it the documents meant for the public: enrollment calendars, fee schedules, scholarship guides and the like. Only folders an administrator created count, so nobody else can publish documents by naming a folder the same way.
  2. Set the folder name in .env and restart SmartKMS.
  3. Link to https://<your SmartKMS address>/ask from the university website.
# Blank = the page is off (it answers "not available").
PUBLIC_ASK_FOLDER=Public Ask
# Questions one visitor (IP address) may ask per 10 minutes.
PUBLIC_ASK_RATE=20
Nothing is stored Visitors don't sign in and their questions aren't saved. A source link in an answer opens only documents in the public folder.
Check the server log after a restart SmartKMS logs ✅ Public Ask (/ask): N approved document(s) … when it starts. A ⚠️ Public Ask line means a folder with that name is ignored because no administrator created it (or its creator is no longer an administrator), or that there is no such folder yet. Have an administrator create the folder and move the documents into it; no restart is needed for that.

Branding (Customization)

These settings let you replace SmartKMS's default logo, title, and favicon without touching any HTML files. They're server-side only — there's no in-app UI for editing them; whoever controls the server's .env sets them.

Defaults match the original look Leaving all of these commented out or unset changes nothing — the app falls back to the default SmartKMS branding.
# Shown in every page <title> (page-specific part is kept, e.g. "Documents
# — Your School Name") and used as the alt text for the main logo.
# BRAND_TITLE=SmartKMS

# Path or absolute URL to the main logo. Anything under /images/ (served
# from static/images/) works as-is, e.g. /images/my-school-logo.svg — drop
# the file in there and point this at it.
# BRAND_LOGO_URL=/images/logo.svg

# Optional second/partner logo shown immediately to the left of the main
# logo, on the landing page and sidebar only. Leave unset for neither —
# nothing renders for that slot at all.
# BRAND_LOGO_SECONDARY_URL=/images/partner-logo.svg

# Path or absolute URL to the favicon (.ico or .png both work).
# BRAND_FAVICON_URL=/images/favicon.ico

How it works: The frontend fetches these from the public /api/branding endpoint and applies them automatically. Every page (login, landing, app, terms, support, etc.) picks up the configured logo/title/favicon via a retroactive DOM patch — no need to edit individual HTML files. The secondary logo appears only on the landing page and app sidebar, immediately to the left of the main logo with a divider line, and hides when the sidebar is collapsed.

Share Online — Cloudflare Tunnel (optional)

Used by scripts/share.py (launcher option Share Online, and Quick Start's --auto path). Leave all four blank to get a random https://….trycloudflare.com link per run; fill in the hostnames for a fixed public address. Requires a domain on your Cloudflare account and a tunnel created in Zero Trust → Networks → Tunnels with three Public Hostnames pointing at localhost:8000 / 8080 / 9000.

# Connector token from the tunnel's "Install and run a connector" page.
# Not needed when cloudflared is installed as a service (cloudflared service install <token>).
CLOUDFLARE_TUNNEL_TOKEN=

# Public hostnames — must match the tunnel's Public Hostname routes exactly
CLOUDFLARE_APP_HOST=skms.example.edu           # -> localhost:8000
CLOUDFLARE_OFFICE_HOST=office.skms.example.edu # -> localhost:8080 (ONLYOFFICE)
CLOUDFLARE_FILES_HOST=files.skms.example.edu   # -> localhost:9000 (MinIO)

Security Headers

No settings — every response carries a Content-Security-Policy and the related headers automatically (app/core/security_headers.py). The policy allows scripts only from the app itself (inline blocks via a per-response nonce) and ONLYOFFICE_URL, and frames/images only from the app, ONLYOFFICE and the public MinIO host — so if you change ONLYOFFICE_URL or S3_PUBLIC_ENDPOINT, the policy follows. Inline onclick="…" attributes are blocked by design; page code uses data-onclick="fn" instead (see the note at the bottom of static/js/app.js).

Only settings listed on this page exist. Every one of them is a field in app/config.py; anything else in .env is silently ignored. Earlier versions of this page (and of .env.example) listed DB_POOL_SIZE, DB_TIMEOUT, RATE_LIMIT_PER_MINUTE, LOG_LEVEL, API_DOCS_ENABLED, SESSION_TIMEOUT_MINUTES, DATA_DIR and LOGS_DIR — none of those were ever read by the app.

Docker Compose Environment Variables

Some settings are split between .env and docker-compose.yml. Here's what goes where:

VariableWhereWhy
ONLYOFFICE_JWT_SECRET.env (read by docker-compose.yml)The API signs editor requests with it and ONLYOFFICE verifies them; one value, so they always match
ONLYOFFICE_INTERNAL_CALLBACK_URL.envONLYOFFICE container calls back to the API on the Docker network (http://api:8000 in production, http://host.docker.internal:8000 in dev)
WATCHFILES_FORCE_POLLINGdocker-compose.ymlForces uvicorn's file watcher to use polling instead of native events — needed on Windows for hot reload to work across bind mounts
ALLOW_PRIVATE_IP_ADDRESSdocker-compose.ymlLets ONLYOFFICE call the API back on a private Docker/host address (host.docker.internal, api) to fetch documents and report saves; otherwise its SSRF protection blocks it

Running Tests

# One-time: create the test database
psql -U postgres -c "CREATE DATABASE dbskms_test;"
psql -U postgres -d dbskms_test -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Run all 231 tests (Ollama and MinIO are mocked — not needed)
uv run pytest

# Run a specific file
uv run pytest tests/test_auth.py -v

# Run only the unit tests (no database needed)
uv run pytest tests/test_storage_validation.py -v

# Run with coverage
uv run --with pytest-cov pytest --cov=app --cov-report=term-missing
On this page