Skip to content

Installation

Not the recommended install path

This page covers the bare-metal install (no Docker). It is not recommended unless you're actively developing on ALMa or are comfortable managing a heavy native Python AI stack (torch, transformers, hdbscan, umap-learn) by hand. For everyday use, follow Docker instead — one command, every dependency pinned and tested, no host-side Python or Node.

Docker users do not need to install Python packages, Node packages, or a virtual environment on the host — every dependency below is already inside the image.

1. Clone

git clone https://github.com/costantinoai/alma-library-manager.git
cd alma-library-manager

2. Python environment

ALMa is one Python package (alma) installable in editable mode. Pick [import] (BibTeX/Zotero support) for everyday installs; add [ai] if you want the local SPECTER2 encoder for embeddings.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[import]"          # lite-equivalent
# or
pip install -e ".[ai,import]"       # normal-equivalent

conda create -n alma python=3.11 -y
conda activate alma
pip install -e ".[import]"

uv venv
source .venv/bin/activate
uv pip install -e ".[import]"

What [ai] adds

[ai] pulls transformers, adapters, torch, scikit-learn, umap-learn, and hdbscan (~1.5 GB on disk). On Apple Silicon and Linux x86_64 the wheels install cleanly; on Windows expect to wait longer for torch. Without [ai], embeddings still work — ALMa fetches Semantic Scholar's pre-computed SPECTER2 vectors, and you can configure OpenAI as an embedding provider from the Settings page. What you lose is the local encoder for papers Semantic Scholar doesn't have a vector for.

You can install AI extras later — ALMa will detect them and light up the matching settings.

For source installs, Settings → Intelligence → AI provider defaults the selected Python environment to this repo-local .venv. Docker builds use the container-internal /opt/venv instead.

3. Frontend build

The React SPA is committed as source; it has to be built once before the backend can serve it.

cd frontend
npm install
npm run build      # writes to frontend/dist
cd ..

For active development, the one-command dev runner starts both servers from the repo .venv (so the local SPECTER2 / GPU stack is available in-process) against an isolated dev profile that never touches your prod data — backend on :8001, Vite on :5173:

scripts/start-dev.sh

It auto-selects .venv/bin/python as the backend interpreter. Override with BACKEND_PORT / FRONTEND_PORT / BACKEND_PYTHON if needed. To run the two servers manually instead, use the .venv Python so AI is available:

# Terminal 1 — backend with auto-reload
.venv/bin/python -m uvicorn alma.api.app:app --reload

# Terminal 2 — Vite dev server (proxies /api/* to the backend)
cd frontend && npm run dev

Vite serves on http://localhost:5173; the backend serves API on http://localhost:8000.

4. Configuration

ALMa reads configuration from two places:

  • settings.json at the repo root — runtime preferences (auto-created on first run with sensible defaults).
  • .env at the repo root — secrets (API keys). Copy from .env.example:
cp .env.example .env
chmod 600 .env
$EDITOR .env

The most useful keys to set:

Variable Purpose
OPENALEX_API_KEY Required — keyless OpenAlex returns 100 credits/day then HTTP 409. Free at openalex.org/settings/api.
OPENALEX_EMAIL Optional contact email (polite pool retired; just sets a courteous User-Agent).
SEMANTIC_SCHOLAR_API_KEY Strongly recommended — avoids shared-pool 429s. Free at semanticscholar.org/product/api.
OPENAI_API_KEY Optional OpenAI embedding provider.
SLACK_TOKEN / SLACK_CHANNEL Slack digest alerts.
API_KEY Optional shared key — if set, requires X-API-Key on every request.

See the configuration reference for the complete list.

5. Run

python -m uvicorn alma.api.app:app --reload --port 8000

Open http://localhost:8000. The frontend SPA is served from the same port as the API.

For production, drop --reload and consider running behind a reverse proxy. See Deployment.

6. CLI

A small CLI is also installed:

alma --help

It exposes the same operations the API does — useful for cron scripts, backups, and one-off debugging.

Next steps