Get Started

Installation

Everything needed to get SmartKMS running locally, from a bare machine to a working login screen.

Quickest Way — start.bat / start.sh

The easiest way to install and run SmartKMS. One command — start.bat on Windows, start.sh on macOS and Linux — does all of the project setup in Part 2 (Steps 3–9) for you.

Before the first run You still need the programs from Part 1 (PostgreSQL with pgvector, Docker Desktop and Ollama) and to copy .env.example to .env and edit it (Part 2, Step 5). For a first run choose 2) Full Install; after that, 1) Quick Start.

Run it from the project folder:

start.bat

Both scripts open with the same prompt:

1) Quick Start  - everything already set up, just launch it
2) Full Install - first run: install uv + packages, pull Docker
                   images + Ollama models, then launch
3) Docker Deployment - full containerized stack for hosting online (VPS)
4) Clean - remove .venv, stop Docker containers, and clean up
  • Quick Start — verifies the .venv (re-syncing from uv.lock if anything is missing), starts Docker Desktop if it's closed (and waits up to 3 minutes for it), starts MinIO/Redis/ONLYOFFICE/NudeNet and waits for MinIO, starts Ollama if it isn't already running, runs setup_db.py --update, then starts the app. --update applies what a new version added to the database but never creates the database or adds accounts. This is what you'll use day to day, and after updating SmartKMS.
  • Full Install — does everything Quick Start does, plus: installs uv if it isn't on PATH, runs uv sync so the environment matches uv.lock exactly, runs docker compose pull before bringing services up, and pulls all three Ollama models (qwen2.5:3b, nomic-embed-text, llava). Use this the first time you run the script, or any time you want to make sure everything is current.
  • Docker Deployment — builds and runs the full containerized stack (PostgreSQL+pgvector, MinIO, Redis, ONLYOFFICE, Ollama, Caddy) for hosting online, e.g. on a VPS. Uses docker-compose.deploy.yml and .env.deploy. See the Docker Deployment troubleshooting section if it fails to start.
  • Clean — removes .venv (and a leftover pre-1.8 venv), stops Docker containers, and kills Ollama processes.

Either mode is safe to re-run — every step skips anything already done. You still need to have edited .env (Part 2, Step 5) once before using either script; Full Install doesn't do that part for you.

Where should documents be stored? On a fresh install (no .env yet) both scripts also ask this once: MinIO (the default) or Google Drive. Choosing Drive skips the MinIO container and prompts for the service-account key file and the folder URL. Either can be skipped and filled in later; the script asks again for whatever is still blank. See Choose where documents are stored for which to pick and the Google Drive setup steps.

Upgrading from 1.7 or earlier? The old venv/ folder is no longer used — uv builds its own .venv per platform. Run the launcher's Full Install once (or uv sync), then delete venv/ whenever you like.

On Windows, Ollama opens in its own cmd window that must stay open. On macOS, start.sh opens a new Terminal tab the same way; on Linux it tries gnome-terminal, then konsole, then xterm, and falls back to running Ollama in the background with output logged to ollama.log if none of those are available. Either script checks first whether Ollama is already running, so re-running won't open duplicate windows.

Generated secrets: on every launch, start.bat / start.sh replace the public CHANGE_ME placeholders for SECRET_KEY and ONLYOFFICE_JWT_SECRET in .env with random values; keys you've already set are left alone. docker-compose.yml reads ONLYOFFICE_JWT_SECRET from .env, so the document editor and the API always share the same secret.

Part 1 — Installing Prerequisites

Install these in order. Do not skip any.

1. Python 3.11 or higher

Download: python.org/downloads

Critical During installation, check the box that says "Add Python to PATH" before clicking Install. If you miss this:
  • You can still fix it afterward by re-running the installer and selecting "Modify" → check "Add Python to environment variables" → Install.
  • Or manually add C:\Users\YourName\AppData\Local\Programs\Python\Python311\ and ...\Python311\Scripts\ to your system PATH via Environment Variables in Windows Settings.
If you skip this step, nothing will work — the terminal won't recognize the python command.

Verify:

python --version

Expected: Python 3.11.x or higher.

2. PostgreSQL 16 + pgvector

PostgreSQL stores everything: users, documents, chat history, search logs, analytics. SmartKMS also requires pgvector — a PostgreSQL extension that enables semantic (vector) search by storing and querying document embeddings.

What is pgvector?

pgvector is an open-source PostgreSQL extension that adds vector similarity search capabilities. It's what powers SmartKMS's semantic search — every document gets converted to a mathematical vector (embedding) using Ollama's nomic-embed-text model, and pgvector finds the most similar documents to your search query using cosine similarity.

Key features used by SmartKMS:

  • Cosine distance (<=>) — measures similarity between document embeddings and search queries
  • Exact and approximate nearest neighbor search — HNSW and IVFFlat indexes for fast queries at scale
  • ACID compliance — vector operations work with transactions, point-in-time recovery, and JOINs
  • Any language — SmartKMS uses asyncpg with SQLAlchemy's pgvector extension

If pgvector isn't installed and enabled, the app will show type "vector" does not exist errors when you try to upload documents or search.

PostgreSQL 16

Download: postgresql.org/download/windows — pick version 16. During installation: set a password for the postgres user (write it down, you need it later), leave the port as 5432, leave everything else default. After installation, PostgreSQL runs automatically as a Windows service. Verify by opening pgAdmin 4 from the Start menu — you should see a server in the left panel.

pgvector for Windows

Important: The PostgreSQL installer does NOT include pgvector. You must install it separately.

Method 1: Stack Builder (recommended)

  1. Open Stack Builder from the Start menu (comes with PostgreSQL)
  2. Select your PostgreSQL installation (e.g., PostgreSQL 16 on port 5432)
  3. Expand "Spatial Extensions" and check "pgvector"
  4. Follow the prompts to install

Method 2: Build from source

Ensure C++ support in Visual Studio is installed and run x64 Native Tools Command Prompt for VS [version] as administrator:

set "PGROOT=C:\Program Files\PostgreSQL\16"
cd %TEMP%
git clone --branch v0.8.6 https://github.com/pgvector/pgvector.git
cd pgvector
nmake /F Makefile.win
nmake /F Makefile.win install

Method 3: conda-forge (if using Conda Postgres):

conda install -c conda-forge pgvector
Alternative: Use Docker for PostgreSQL with pgvector pre-installed

If you're already using Docker, you can skip the manual PostgreSQL/pgvector installation and use the official Docker image:

docker run -d --name postgres-pgvector \
  -e POSTGRES_PASSWORD=yourpassword \
  -e POSTGRES_DB=dbskms \
  -p 5432:5432 \
  pgvector/pgvector:pg16-bookworm

See Part 3 — Docker Setup below, which uses this approach automatically.

3. Docker Desktop

Docker runs MinIO (file storage), Redis, and ONLYOFFICE with a single command.

Download Docker Desktop: docker.com/products/docker-desktop. After installation restart your computer, then open Docker Desktop and wait for the green "Engine running" indicator before continuing. If it asks, let it enable the WSL 2 backend.

Verify either way:

docker --version
docker compose version

4. Ollama

Ollama runs AI models locally — no OpenAI account or API key needed. Download: ollama.com (installers for Windows, macOS, and Linux).

Pull the three models SmartKMS uses, one at a time, waiting for each to finish:

ollama pull qwen2.5:3b

~2 GB — generates answers and document summaries.

ollama pull nomic-embed-text

~270 MB — powers semantic search (creates document embeddings stored in pgvector).

ollama pull llava

~4.5 GB — OCR and image-based content screening (scanned documents, photo uploads).

Verify:

ollama list

You should see all three models listed.

Skip this if you plan to use the Full Install option in start.bat/start.sh below — it pulls all three models for you.

5. Git (optional)

Only needed to clone from a repository.

Part 2 — Project Setup (First Time Only)

Using the launcher script? It does Steps 3–9 below for you; you only need Step 5 (editing .env). The manual steps are here for reference or if the script fails.

Step 1 — Extract the project

Extract the zip to a folder. The result should contain run.py, scripts/setup_db.py, start.bat, start.sh, pyproject.toml, uv.lock, .env, docker-compose.yml, an app/ folder, and a static/ folder.

Step 2 — Open a terminal in the project folder

cd C:\Users\YourName\Downloads\SKMS

Tip: right-click the SKMS folder in File Explorer (or Finder/your file manager) and choose "Open in Terminal". All commands below run from inside this folder.

Step 3 — Install uv

SmartKMS uses uv to manage its Python environment — it replaces venv and pip, and will download a compatible Python 3.11+ on its own if your system doesn't have one. Skip this step if uv --version already works.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or winget install astral-sh.uv. Open a new terminal afterwards so uv is on PATH.

Step 4 — Install Python packages

uv sync

Creates a .venv folder in the project and installs exactly the versions pinned in uv.lock — usually well under a minute. There is nothing to activate: every command below is run through uv run …, which uses the project's .venv automatically from any terminal.

Note: The start.bat / start.sh scripts (Full Install mode) install uv if it's missing and run uv sync for you.

Step 5 — Edit the .env file

Open .env and change two lines — your PostgreSQL password:

DATABASE_URL=postgresql+asyncpg://postgres:YOUR_PASSWORD@localhost:5432/dbskms

and, if you like, your secret key (any long random text; the launcher generates one if you leave the placeholder):

SECRET_KEY=smartkms-your-university-name-2026-random-secure-string
Note: leave ONLYOFFICE_JWT_SECRET as it is. The launcher replaces the placeholder with a random value, and docker-compose.yml passes it to the ONLYOFFICE container. Not using the launcher? Run uv run python scripts/ensure_secrets.py once instead.

Choose where documents are stored — MinIO or Google Drive

Uploaded files are kept in one of two places. This is a one-time choice for the administrator; users see no difference either way, and search, AI answers and sharing work the same.

MinIO (default)Google Drive
Choose it ifYou want everything on your own server, with nothing to sign up forYour institution already uses Google Workspace and wants the files in its Drive
Where files liveOn the server's disk, in a local Docker containerIn a Drive folder, ideally a Workspace Shared Drive
Storage limitThe server's free disk spaceThe Google account's quota (15 GB on a personal account; a Shared Drive uses the Workspace's)
SetupNone — works out of the boxAbout 10 minutes in Google Cloud Console (steps below)
Internet neededNoYes, for every upload and download
Not sure? Choose MinIO. It needs no account and keeps documents on-premise. You can switch to Google Drive later: documents already uploaded stay where they are and keep working, and only new uploads go to the new place.

How to set it: on a fresh install, start.bat / start.sh ask which one you want and write it to .env for you. To set it by hand, put one of these in .env:

STORAGE_BACKEND=minio          # default
STORAGE_BACKEND=google_drive

If you choose Google Drive

You need a Google account that can use Google Cloud Console, and a Drive where the documents will live — preferably a Workspace Shared Drive, because the app's service account has no storage of its own and a folder in a personal My Drive stops accepting uploads when that person's quota is full.

  1. Enable the Drive API. Go to console.cloud.google.com, create or select a project, then open APIs & Services → Library, search for Google Drive API and click Enable.
  2. Create a service account. Open APIs & Services → Credentials → Create credentials → Service account, give it a name (for example smartkms-storage) and finish. No roles are needed.
  3. Download its key. Open the new service account → Keys → Add key → Create new key → JSON. A .json file downloads. Keep it private: anyone with this file can reach the shared folder.
  4. Create the folder. In Google Drive, create the folder SmartKMS should use (inside a Shared Drive if you have one).
  5. Share the folder with the service account. Share it with the service account's e-mail (name@project.iam.gserviceaccount.com, shown on the Credentials page and in the client_email field of the key file) as Editor or Content manager.
  6. Give SmartKMS the key and the folder. Run start.bat / start.sh, choose Google Drive, then drag the key file into the window and paste the folder's URL when asked. The script copies the key into the git-ignored secrets/ folder, prints the service account e-mail from step 5 so you can double-check the share, and writes both settings to .env. To do it by hand instead, save the key as secrets/google-drive-key.json and add:
    STORAGE_BACKEND=google_drive
    GOOGLE_DRIVE_CREDENTIALS_FILE=secrets/google-drive-key.json
    GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz0123456   # the part of the folder URL after /folders/
  7. Check that it works. Start SmartKMS, sign in as an administrator and upload a small document. A sub-folder named after the college's short code (for example CIT) should appear inside your Drive folder with the file in it.
Upload fails? The most common causes are that the folder was not shared with the service account e-mail from step 5, or that the folder sits in a personal My Drive whose quota is full. Share the folder again with Editor access, or move it into a Shared Drive. The full list of storage settings is on the Configuration page.

With Google Drive selected, the MinIO container is not needed: the launcher skips it, and in Step 7 you can leave minio out of the docker compose command.

Step 6 — Set up the database

One script handles everything: creates dbskms if missing, enables pgvector (CREATE EXTENSION vector;), creates every table, and seeds the 5 college organizations plus 8 demo accounts. Safe to re-run anytime — anything that already exists is left alone.

uv run python scripts/setup_db.py
If you see type "vector" does not exist:

pgvector isn't installed or enabled. This is the most common installation issue. Fix it by:

  1. Verify pgvector is installed (see Part 1, Step 2)
  2. Connect to PostgreSQL and enable the extension manually:
    psql -U postgres -d dbskms -c "CREATE EXTENSION IF NOT EXISTS vector;"
  3. Or re-run uv run python scripts/setup_db.py — it runs CREATE EXTENSION IF NOT EXISTS vector; automatically

Visit the pgvector GitHub repository for detailed installation instructions for your platform.

If you see "could not connect to server", open pgAdmin 4 (usually starts PostgreSQL automatically) and try again.

The start.bat / start.sh scripts run this step for you: Full Install runs it in full, and Quick Start runs setup_db.py --update, which only brings an existing database up to date (it never creates the database or re-adds demo accounts an administrator deleted).

Step 7 — Start Docker services (MinIO + Redis + ONLYOFFICE + NudeNet)

docker compose up -d minio redis onlyoffice nudenet

First run downloads the images — MinIO (~300 MB), Redis (~50 MB), ONLYOFFICE (~1–1.5 GB) — and builds the small NudeNet image-screening service from nudenet_service/. Verify with docker compose ps — all four should show running.

MinIO console: http://localhost:9001 (minioadmin / minioadmin) — no action needed there, the app creates its bucket automatically.

ONLYOFFICE: http://localhost:8080 — may take 30–60 seconds to become healthy on first run.

The start.bat script automatically starts these services (with docker compose up -d minio redis onlyoffice nudenet) and waits for them to be ready before proceeding.

Step 8 — Start Ollama

In a second terminal (or let start.bat handle it):

ollama serve

Leave this running — Ollama must stay up for AI features to work.

The start.bat script automatically launches Ollama in a new window if it's not already running. The Full Install mode also pulls all three models (qwen2.5:3b, nomic-embed-text, llava) if they're missing.

Step 9 — Start the app

Back in your first terminal, in the project folder:

uv run python run.py

Healthy startup ends with Application startup complete. Open http://localhost:8000.

Part 3 — Docker Setup (Alternative: Run Everything in Docker)

Runs PostgreSQL (with pgvector pre-installed), MinIO, Redis, and the API entirely inside Docker, with no manual Python install.

This is an alternative to Part 2 — do one or the other, not both.

You still need Docker Desktop installed and running.

docker compose up -d

Starts skms_postgres (5432), skms_minio (9000/9001), skms_redis (6379), skms_onlyoffice (8080), skms_nudenet (8001), and skms_api (8000). Check with docker compose ps — all six should show running.

The API image is built with uv: uv sync --frozen installs exactly the versions in uv.lock, so a container always matches a local install.

The PostgreSQL container uses the official pgvector/pgvector:pg16-bookworm image, so pgvector is pre-installed and ready to use — no manual installation needed.

Set up the database:

docker compose exec api python scripts/setup_db.py

Then open http://localhost:8000.

Useful Docker commands

# View live logs from the API
docker compose logs -f api

# Restart just the API after code changes
docker compose restart api

# Stop all services
docker compose down

# Stop and delete all data (full reset)
docker compose down -v

# Open a terminal inside the API container
docker compose exec api bash

Running Ollama in Docker too (optional)

Ollama normally runs natively even when everything else is in Docker — just run ollama serve separately. To containerize it too, add to docker-compose.yml:

  ollama:
    image: ollama/ollama:latest
    container_name: skms_ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

Add ollama_data: under the volumes: section, then update .env:

OLLAMA_BASE_URL=http://ollama:11434

Part 4 — Running the App Every Day

Fastest path: run start.bat (Windows) or ./start.sh (macOS/Linux) with the Quick Start option — see above. It does everything below in one command. The manual steps here are for when you'd rather run things by hand or in separate terminals.

After first-time setup, open three terminals:

Terminal 1 — AI models

ollama serve

Keep open. The first AI response after startup takes 15–30 seconds while the model loads; after that, much faster.

Terminal 2 — Docker services

docker compose up -d minio redis onlyoffice

Terminal 3 — The app

uv run python run.py

Open http://localhost:8000.

Quick Reference
App:         http://localhost:8000
API docs:    http://localhost:8000/api/docs
Health:      http://localhost:8000/health
MinIO:       http://localhost:9001  (minioadmin / minioadmin)
ONLYOFFICE:  http://localhost:8080

Login:       admin@cit.edu / Admin@CIT2024
On this page