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.
.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.batchmod +x start.sh # once
./start.shchmod +x start.sh # once
./start.shBoth 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 fromuv.lockif 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, runssetup_db.py --update, then starts the app.--updateapplies 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 syncso the environment matchesuv.lockexactly, runsdocker compose pullbefore 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.ymland.env.deploy. See the Docker Deployment troubleshooting section if it fails to start. - Clean — removes
.venv(and a leftover pre-1.8venv), 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.
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
- 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.
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.
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
asyncpgwith SQLAlchemy'spgvectorextension
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
Method 1: Stack Builder (recommended)
- Open Stack Builder from the Start menu (comes with PostgreSQL)
- Select your PostgreSQL installation (e.g., PostgreSQL 16 on port 5432)
- Expand "Spatial Extensions" and check "pgvector"
- 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
PostgreSQL 16 via Homebrew:
brew install postgresql@16
brew services start postgresql@16
pgvector — also via Homebrew:
brew install pgvector
If you have more than one Postgres installed, point pgvector at the right one first:
export PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
Set a password for the postgres user — psql postgres then \password postgres — and leave the port as the default 5432. Write the password down, you need it later.
The extension itself is enabled in the database by setup_db.py (Step 6) — nothing to do by hand.
PostgreSQL 16 (Debian / Ubuntu shown; use your distribution's equivalent):
sudo apt update
sudo apt install postgresql-16 postgresql-server-dev-16
sudo systemctl enable --now postgresql
pgvector — from the APT repository if your distribution has it:
sudo apt install postgresql-16-pgvector
Otherwise build it from source (needs build-essential and the postgresql-server-dev-16 package above):
cd /tmp
git clone --branch v0.8.6 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install
Set a password for the postgres user — sudo -u postgres psql then \password — and leave the port as the default 5432. Write the password down, you need it later.
The extension itself is enabled in the database by setup_db.py (Step 6) — nothing to do by hand.
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.
Download Docker Desktop for Mac: docker.com/products/docker-desktop (pick the Apple silicon or Intel build to match your Mac), or brew install --cask docker. Open Docker Desktop once and wait for the green "Engine running" indicator before continuing.
Install Docker Engine directly (no Desktop app needed) — follow the official steps for your distribution at docs.docker.com/engine/install, or on Debian/Ubuntu:
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Log out and back in after the last command, so your user's new docker group membership takes effect.
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.
start.bat/start.sh below — it pulls all three models for you.5. Git (optional)
Only needed to clone from a repository.
Download: git-scm.com/download/win
xcode-select --install
Or brew install git.
sudo apt install git
(Debian / Ubuntu; use your distribution's package manager otherwise.)
Part 2 — Project Setup (First Time Only)
.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\SKMScd ~/Downloads/SKMScd ~/Downloads/SKMSTip: 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.
curl -LsSf https://astral.sh/uv/install.sh | sh
Or brew install uv. Open a new terminal afterwards so uv is on PATH.
curl -LsSf https://astral.sh/uv/install.sh | sh
Installs to ~/.local/bin. Open a new terminal afterwards (or source ~/.bashrc) 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
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 if | You want everything on your own server, with nothing to sign up for | Your institution already uses Google Workspace and wants the files in its Drive |
| Where files live | On the server's disk, in a local Docker container | In a Drive folder, ideally a Workspace Shared Drive |
| Storage limit | The server's free disk space | The Google account's quota (15 GB on a personal account; a Shared Drive uses the Workspace's) |
| Setup | None — works out of the box | About 10 minutes in Google Cloud Console (steps below) |
| Internet needed | No | Yes, for every upload and download |
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.
- 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.
- 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. - Download its key. Open the new service account → Keys → Add key → Create new key → JSON. A
.jsonfile downloads. Keep it private: anyone with this file can reach the shared folder. - Create the folder. In Google Drive, create the folder SmartKMS should use (inside a Shared Drive if you have one).
- 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 theclient_emailfield of the key file) as Editor or Content manager. - 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-ignoredsecrets/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 assecrets/google-drive-key.jsonand 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/ - 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.
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
type "vector" does not exist:
pgvector isn't installed or enabled. This is the most common installation issue. Fix it by:
- Verify pgvector is installed (see Part 1, Step 2)
- Connect to PostgreSQL and enable the extension manually:
psql -U postgres -d dbskms -c "CREATE EXTENSION IF NOT EXISTS vector;" - Or re-run
uv run python scripts/setup_db.py— it runsCREATE 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.
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.
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.
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.
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
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.
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