Audience: Contributor
Prepare a Linux workstation for LokAkrt development. This page expands on the checklist in the repository at tools/dev-setup.md and ties it to the monorepo quick start.
See also: Home · Element schema architecture · Observability · repository
README.md·CONTRIBUTING.md
| Step | What |
|---|---|
| 1 | Install NVM and pin a Node.js version |
| 2 | Install system packages for image and media processing |
| 3 | Install global CLI tools (Angular, Ionic, Cordova, etc.) |
| 4 | Clone the repo, install workspace dependencies, build shared libs |
| 5 | Start Docker services and run LokAkrt UI + API locally |
Install NVM (Node Version Manager), then install and use the project Node version.
# After installing NVM (see upstream README)
nvm install --lts
nvm use --lts
npm install -g npm
LokAkrt targets Node 22 (same major as the production Docker image). Pin a current 22.x for local work:
nvm install 22
nvm alias default 22
nvm use 22
Verify:
node -v
npm -v
Install native dependencies used by media processing and sharp/libvips:
sudo apt install libvips-dev
sudo apt install exiftool
sudo apt install imagemagick
sudo apt install tesseract-ocr
On other distributions, install equivalent packages for libvips, ExifTool, ImageMagick, and Tesseract.
Install command-line tools used across the UI, preview, and mobile export workflows:
npm install -g @angular/cli
npm install -g @ionic/cli
npm install -g cordova
npm install -g cordova-res
npm install -g capacitor-resources
npm install -g svgo
npm install -g npm-check-updates
| Package | Purpose |
|---|---|
@angular/cli |
Angular workspace builds (ui, common, preview) |
@ionic/cli |
Ionic tooling and preview client |
cordova / cordova-res |
Legacy mobile asset generation |
capacitor-resources |
Capacitor splash/icon resources |
svgo |
SVG optimization (common/icons) |
npm-check-updates |
Dependency upgrade scripts (npm run ncu:*) |
From the monorepo root:
git clone <your-fork-or-origin-url> lokakrt
cd lokakrt
cp .env.example .env
# Edit .env — MariaDB passwords (app settings live in DB after setup)
npm install
cd common && npm install && npm run build
cd ../server/main && npm install
cd ../../server/ai && npm install
cd ../../ui/main && npm install
Build shared libraries before starting the UI or API whenever common/ changes:
cd common && npm run build
cd server/main
docker-compose up -d
Grafana is not started here. Optional ops stack: Observability (server/observability/, host port 8005, status-first Overview).
cd server/main
npm run dev
cd ui/main
npm start
cd server/ai
npm start
| Service | URL |
|---|---|
| LokAkrt UI | http://localhost:4200 |
| LokAkrt API | http://localhost:8080 |
| AI server | http://localhost:9090 |
| AI UI | http://localhost:5200 |
| Grafana (optional ops) | http://localhost:8005 — Observability |
Optional Grafana stack (status-first Overview — issue / what / which app). Not started with main / store / AI.
After the API is running:
./tools/dev/smoke-release.sh
Cypress e2e (npm run test:cypress) uses a separate throwaway MariaDB. Restore is once per spec file, not per it(). See Cypress e2e.
Override URL or credentials if needed:
LOKAKRT_API=http://localhost:8080 \
LOKAKRT_EMAIL=admin@example.com \
LOKAKRT_PASSWORD=admin \
./tools/dev/smoke-release.sh
Delete local branches already merged into your main line (adjust branch names to match your workflow):
git branch --merged | grep -v '\*\|master\|main\|develop' | xargs -n 1 git branch -d
docker ps
docker logs lokakrt_mariadb
Reset MariaDB volume if you need a clean slate:
cd server/main
docker-compose down
docker volume rm lokakrt_mariadb_volume
docker-compose up -d
Change port mappings in server/main/docker-compose.yml or stop the conflicting process.
common/Rebuild shared packages:
cd common && npm run build
Canonical short checklist in the repo: tools/dev-setup.md
Keep that file as the minimal copy-paste list; this wiki page adds context, tables, and run instructions for onboarding.