The Problem
Many teams need a self‑hosted knowledge base that supports extended Markdown, fine‑grained permissions, SSO/OIDC, and offline/PWA use‑cases, but existing options either lack essential features or require heavy infrastructure to operate.
What This Does
Alexandrie is a Go‑backed (Gin + sqlx) service that stores documents in MySQL 8 and assets in an S3‑compatible store (MinIO, AWS S3, etc.). The frontend is a Nuxt 4/Vue 3 app that uses CodeMirror 6 with custom Markdown extensions (colored containers, KaTeX math, footnotes) and provides a PWA manifest for offline work. Authentication is handled via JWT and OIDC/SSO providers; the OIDC configuration lives in backend/oidc/config.go. Permission logic is enforced through a 5‑level access control model defined in backend/models/permission.model.go and exposed through the router at backend/router/routes/users.go and backend/router/routes/nodes.go. Database schema is managed via SQL migrations under backend/app/migrations/ and the entry point is backend/main.go.
How To Use It
Setup Get the code git clone https://github.com/Smaug6739/Alexandrie.git cd Alexandrie Configure environment – copy the provided examples cp .env.example .env # root .env (defaults for Docker Compose) cp backend/.env.example backend/.env # backend‑specific values
Launch
docker compose up -d # starts the four‑service stack (backend, DB, MinIO, frontend)
Open http://localhost:8200 and create the first admin account.
Development (hot‑module replacement)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
This builds the frontend with Vite HMR and watches for changes.
Configuration
Key environment variables are defined in .env.example and backend/.env.example. Typical values include DBDSN, MINIOENDPOINT, OIDCCLIENTID, and OIDCCLIENTSECRET. Adjust these for production; never commit actual secrets.
Real‑World Use
A distributed research group can deploy Alexandrie behind a reverse proxy, configure Google OIDC so members sign in with their corporate accounts, and rely on the built‑in full‑text search to surface legacy notes. Because the app ships as a PWA, engineers can install it on laptops or tablets and continue editing notes while offline; changes sync when connectivity returns. The Kanban board (Vue component AppKanbanBoard.vue not listed in the file count but referenced in the README) lets teams visualize sprint backlogs directly within a workspace.
Code Health & Issues
Tests: 5 test files exist under backend/tests/; they cover user lifecycle and authentication flows, providing basic regression coverage. CI/CD: GitHub Actions workflows are present (.github/workflows/codeql.yml, docker-image-release.yml, deploytoprod.yml). CodeQL analysis is configured, and Docker image publishing is automated on tags. Secrets: The heuristic flag frontend/.env indicates possible credentials committed to the repo. The file should be added to .gitignore and replaced with environment injection at runtime. Configuration hygiene: Root .env and backend/.env.example contain default values; ensure production overrides are supplied via a separate .env that is not version‑controlled. Makefile: Present but targets are not documented in the repository; verify required make commands (e.g., make build, make migrate) before relying on them. Input validation: The backend uses sqlx for query construction; review backend/services/user.service.go and backend/controllers/authentication.controller.go for any unchecked user input that could lead to SQL injection, though the use of parameterized queries mitigates most risk.
The Bottom Line
Alexandrie delivers a feature‑rich, self‑hosted knowledge base with Markdown extensions, OIDC/SSO, PWA/offline support, and granular permissions out of the box. Docker Compose enables a one‑command deployment, and the codebase includes CI, migration scripts, and basic test coverage. Teams should treat the committed .env files as placeholders and inject real secrets at runtime; otherwise the platform is well‑suited for small‑to‑medium organizations that need a customizable, offline‑capable wiki without the overhead of larger SaaS solutions.