Alexandrie: a self-hosted Markdown knowledge base with offline PWA support

What Alexandrie solves, and for whom

Teams that want a Notion-shaped workspace usually face the same trade: hosted products give you structure and permissions but keep the files, while a folder of Markdown gives you the files and nothing else. Alexandrie sits between those two. The README describes it as "a self-hosted, open-source knowledge base with an extended Markdown editor", and it is aimed at teams and individuals who want to organize, search, share and export notes from any device, including offline.

The audience is narrower than the tagline suggests. You need to run Docker, you need somewhere to keep a MySQL volume and an object store, and you need someone who can edit a .env file. In return you get the parts that hosted tools usually charge for: multi-tenant teams, a five-level access model, OIDC providers, and media stored in an S3-compatible bucket you own. If nobody on the team wants to operate that stack, the project is the wrong shape for you, however good the editor is.

How the Alexandrie stack is put together

The repository splits into a backend/ directory written in Go and a frontend/ directory built with Nuxt and Vue, with docs/ holding a separate Nuxt site. The bundled docker-compose.yml wires three services onto one network. mysql:8.0 holds relational data. rustfs/rustfs:latest provides S3-compatible object storage for media and backups. The backend image is ghcr.io/smaug6739/alexandrie-backend:latest, which the compose file runs with BACKEND_PORT: 8201 and GIN_MODE: release.

Configuration flows through environment variables, and the interesting part is that the public URLs are the browser's URLs, not the container's. .env.example sets FRONTEND_URL, API_URL and CDN_URL to localhost addresses with ports 8200, 8201 and 9005, and the comment above them says that behind Nginx or Traefik you should put your public domain names there instead. CDN_ENDPOINT defaults to /alexandrie/, described as the base path in the CDN where files are served from, which the comment ties to the bucket name. That is a deployment detail worth reading twice: a mismatch between the bucket name and this path is the kind of thing that produces broken images rather than a clear error.

Feature flags sit in the same file. CONFIG_DISABLE_LANDING, CONFIG_DISABLE_SIGNUP and CONFIG_DISABLE_NATIVE_LO (truncated in the example) let you turn parts of the frontend off, which is how a private instance hides its signup page. The frontend also carries a service worker role: the README calls it an "Offline-First PWA" that installs on desktop and mobile with synchronization. The README does not document the conflict-resolution rules behind that synchronization, so treat offline editing as a feature to verify against your own workflow rather than one to assume.

Installing Alexandrie with Docker Compose

The Quick Start section of the README gives three steps, and they are the whole install. First, pull the two files that define the stack:

curl -O https://raw.githubusercontent.com/Smaug6739/Alexandrie/main/.env.example
curl -O https://raw.githubusercontent.com/Smaug6739/Alexandrie/main/docker-compose.yml

Second, create your environment file from the template:

cp .env.example .env

Third, start everything:

docker compose up -d

When the containers are healthy, the README says to open http://localhost:8200 to create your primary owner account. That page is the first-run path: the first account becomes the owner, which is why the signup flag matters later. The compose file publishes MySQL on ${MYSQL_EXTERNAL_PORT:-3307} and RustFS on ${RUSTFS_EXTERNAL_PORT:-9000}, and it supplies defaults such as MYSQL_ROOT_PASSWORD: rootpassword, MYSQL_PASSWORD: password, RUSTFS_ACCESS_KEY: alexandrie-key and RUSTFS_SECRET_KEY: alexandrie-secret. Those defaults exist so the stack starts without editing anything. Before the instance is reachable from anywhere but your laptop, replace them in .env, along with JWT_SECRET, whose default value in the compose file literally tells you to change it.

For local development the Makefile offers a different route: make backend runs go run main.go from backend/, make frontend runs bunx --bun nuxt dev from frontend/, and there is a docker-compose.dev.yml alongside the production one. The Makefile also shows a MinIO alternative for object storage, started with MINIO_ROOT_USER=alexandrie-access and MINIO_ROOT_PASSWORD=alexandrie-secret against ./minio, which is useful if you would rather not run RustFS locally.

Where Alexandrie gets in your way

The compose file is a demo-grade starting point, not a hardened deployment. MySQL and the object store are both published to the host by default, and the credentials are published in the repository. Running docker compose up -d on a machine with a public IP, without editing .env first, exposes a database on 3307 with a known password. The README's quick start does not warn about this, and that omission is the single most important thing to fix before anyone else touches the instance.

Upgrades are the second gap. There are three releases in the repository (v8.14.0, v8.14.1, v8.14.2), and the compose file pulls :latest for the backend image, which means a restart can move you to a new version without a deliberate decision. The README does not document a migration step, a version pinning strategy or a rollback procedure. The Makefile has a migrate target that shells out to migrate create -ext sql -dir backend/migrations/ -seq $(name), which tells you migrations are SQL files in backend/migrations/, but nothing in the repository explains how they are applied on upgrade or whether a downgrade is possible. Back up the MySQL volume and the object store before you pull a new image.

The third limitation is scope. Alexandrie is a knowledge base, not a project tracker. Kanban boards exist per workspace, but the README presents them as a way to organize objectives alongside documentation, not as a replacement for an issue tracker with sprints, dependencies and reporting. If your team's real need is ticket flow, this is the wrong tool and no amount of Markdown editing changes that.

Alexandrie against Obsidian and Confluence

The README names Notion, Confluence and Obsidian as the alternatives it has in mind, and the three differ in ways that matter more than feature lists.

Obsidian is local-first in the strict sense: your notes are files on your disk, and sync is an add-on you choose. Alexandrie is offline-first in the PWA sense. The frontend can be installed on a device and used offline, but the source of truth is the MySQL database and the object store on your server, reached through the API. If your requirement is that a plain folder of .md files is the canonical artifact, Obsidian fits and Alexandrie does not, because exporting from Alexandrie is an action you take rather than a property of the system. The README does describe ZIP import and export tools that can back up or restore selective nodes, metadata configurations or entire platform states, so portability exists, but it is a pipeline, not the storage model.

Confluence is the comparison for the team features. Alexandrie's five-level access model (None, Read, Write, Admin, Owner) applied per node or workspace, plus invitation codes and group rules, covers the permission ground a wiki needs. The difference is operational: Confluence is a service someone else runs and bills for, while Alexandrie is a compose file you own and patch. That trade is the entire decision. OIDC support means you can keep your existing identity provider, which removes one of the usual reasons teams stay on a hosted wiki.

Licence, maintenance and upgrade cost

Alexandrie is MIT licensed, which is permissive: you can run it commercially, modify it and redistribute it, provided the copyright notice and licence text are preserved. The repository also carries a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, so contribution expectations are written down. Nothing in the repository suggests a separate enterprise edition or a licence key, so there is no commercial gate to plan around. This is a description of the licence, not legal advice; if you redistribute a modified build, read the LICENSE file in the repository yourself.

The maintenance picture is active. The last push was on 2026-09-21, and the most recent release, v8.14.2, is dated 2026-09-07. That cadence is a cost as well as a benefit: frequent releases mean you should pin the backend image rather than track :latest, and you should read the release notes before each bump. The repository does not include those notes, so the upgrade procedure has to come from the repository itself. Budget for someone to own the .env, the volumes and the backup restore, because none of those are automated by the compose file as published.

Editorial conclusion

Adopt Alexandrie if you already run Docker and want Markdown documents, team permissions and SSO on hardware you control, and if you accept that the bundled compose file publishes MySQL on port 3307 and RustFS on 9000 with default credentials that must be changed before the stack is reachable. Skip it if you need a hosted service with a support contract, or if you expect the README to explain upgrades, migrations and rollback, because it does not. Before you invite anyone, verify that .env holds real values for JWT_SECRET, the MYSQL_* passwords and the RUSTFS_* keys, and that a backup restore of a single document has actually been rehearsed.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Smaug6739/Alexandrie on GitHub