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
| Service | URL | Login |
|---|---|---|
| SmartKMS app | http://localhost:8000 | see User Manual |
| API documentation | http://localhost:8000/api/docs | none |
| Health check | http://localhost:8000/health | none |
| MinIO console (MinIO backend only) | http://localhost:9001 | minioadmin / minioadmin |
| ONLYOFFICE editor | http://localhost:8080 | internal |
| PostgreSQL | localhost:5432 | postgres / your password |
| Ollama | http://localhost:11434 | internal |
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=
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.
ollama pull qwen2.5:7b) without changing the faster model used for chat.
OLLAMA_MODERATION_MODEL=qwen2.5:3b
OLLAMA_MODERATION_VISION_MODEL=llava
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_drive | onedrive | |
|---|---|---|---|
| What it is | An S3-compatible bucket run locally in Docker | A folder in an organization's existing Google Drive, accessed by a service account | A SharePoint site's Documents library (or one person's OneDrive) in the university's Microsoft 365, through Microsoft Graph |
| Cost / limits | Free; limited only by your disk | API is free, but storage counts against that Google account's quota — 15 GB free on a personal account, a Workspace Shared Drive for anything real | Free with Microsoft 365; the site's storage quota applies |
| Downloads | Browser fetches straight from MinIO via short-lived presigned links | Proxied 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 |
| Uses | S3_* settings below | GOOGLE_DRIVE_* settings below | ONEDRIVE_* settings below |
STORAGE_BACKEND=minio
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:
- console.cloud.google.com → create/select a project → APIs & Services → Library → enable Google Drive API.
- APIs & Services → Credentials → Create credentials → Service account → open it → Keys → Add key → JSON. A
.jsonfile downloads. - Save it as
secrets/google-drive-key.jsonin the project (or anywhere — absolute paths work) and pointGOOGLE_DRIVE_CREDENTIALS_FILEat it. - 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.
- Share that folder with the service account's e-mail (the
client_emailfield inside the JSON,name@project.iam.gserviceaccount.com) as Editor / Content manager. - 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.
- Microsoft Entra → App registrations → New registration, Accounts in this organizational directory only. Note the Application (client) ID and Directory (tenant) ID.
- Certificates & secrets → New client secret. Copy its Value, not its Secret ID.
- API permissions → Microsoft Graph → Application permissions → Files.ReadWrite.All → Grant admin consent. (
Files.ReadWrite.Allreaches every library in the tenant;Sites.Selectedlimits the app to the one site, which is safer.) - 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
.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
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.
- Azure portal → Microsoft Entra ID → App registrations → New registration. For a school, "accounts in this organizational directory only" (single tenant) is usually right.
- Redirect URI (type Web):
<the URL users open the app at>/api/auth/microsoft/callback— e.g.http://localhost:8000/api/auth/microsoft/callbackwhile testing. - API permissions → Add → Microsoft Graph → Delegated:
openid,profile,email,User.Read(grant admin consent if your tenant requires it). - 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.
- Google Cloud console → APIs & Services → OAuth consent screen: user type Internal limits sign-in to your Workspace domain; the only scopes needed are
openid,emailandprofile. - 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/callbackwhile testing. - 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=
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
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.
- 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.
- Set the folder name in
.envand restart SmartKMS. - Link to
https://<your SmartKMS address>/askfrom 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
✅ 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.
# 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).
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:
| Variable | Where | Why |
|---|---|---|
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 | .env | ONLYOFFICE container calls back to the API on the Docker network (http://api:8000 in production, http://host.docker.internal:8000 in dev) |
WATCHFILES_FORCE_POLLING | docker-compose.yml | Forces 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_ADDRESS | docker-compose.yml | Lets 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