An Otter Wiki: Git-backed Markdown wiki with Flask

Git and Markdown as the Otter Wiki content model

An Otter Wiki targets people who need a collaborative content space but prefer plain Markdown files and Git history to a document model hidden inside an application database. The README states that content is stored in a Git repository, with Markdown used as the markup language. That choice has a direct practical effect: pages remain text files, while Git records changes to those files. The repository layout contains a dedicated `otterwiki/` Python package, a `Dockerfile`, a `docker-compose.yml`, documentation, frontend assets, and tests, so the project is organized as a deployable web application rather than a command-line Markdown converter.

The intended users are teams or individuals who need wiki features such as page editing, page history, user accounts, attachments, and structured Markdown. The feature list includes a Markdown editor with syntax highlighting and table support, a customizable sidebar, full page history, authentication, attachments, footnotes, alerts, and Mermaid diagrams. These are additions around Markdown rather than a separate diagramming or workflow platform. The Git-backed model also gives administrators a familiar repository to inspect, but the README does not specify a retention policy, conflict-resolution policy, or large-repository limits.

Flask application flow and editing features

The application is written in Python using Flask. The `pyproject.toml` file identifies Flask, Jinja2, Flask-Login, Flask-WTF, SQLAlchemy, Flask-SQLAlchemy, GitPython, Mistune, Pygments, Beautiful Soup, and several other packages as runtime dependencies. Based on those dependencies and the repository layout, the web layer handles requests through Flask, Jinja2 renders the interface, authentication is integrated through Flask-Login and Flask-WTF, and GitPython provides Git repository interaction. SQLAlchemy and Flask-SQLAlchemy are present for application data, while Git is the stated storage system for wiki content.

The frontend uses halfmoon for CSS and CodeMirror for editing. The README describes support for extended Markdown features including tables, footnotes, fancy blocks, alerts, and Mermaid diagrams. Mistune and Pygments are listed as Python dependencies, which is consistent with parsing and syntax highlighting, although the README does not specify the exact extension-loading sequence. The page history and changelog features should be understood as application features backed by Git change records, not as a claim that Otter Wiki exposes every Git object or command through its interface.

The project also includes an experimental Git HTTP server for clone, pull, and push operations. That feature may appeal to users who already work with Git clients, but its experimental status is important. The README does not document authentication details, repository permissions, merge behavior, or recovery procedures for concurrent edits, so those points require verification before exposing the feature to an untrusted network.

Docker Compose installation and first local wiki

The README recommends Docker Compose and provides a concrete deployment example. Copy the Compose file, run it in the project directory, and then open the local address shown in the documentation. The published example uses the `redimp/otterwiki:2` image, maps host port `8080` to container port `80`, and persists the `./app-data` directory under `/app-data`.

Use this Compose configuration as documented in the README:

services:
  otterwiki:
    image: redimp/otterwiki:2
    restart: unless-stopped
    ports:
      - 8080:80
    volumes:
      - ./app-data:/app-data

Start the service with the command printed in the README:

docker-compose up -d

After startup, access `http://127.0.0.1:8080` if the service is running on the local machine. The first account becomes the admin account and grants access to the settings tab. The next step is to adjust the settings, including the sidebar configuration described by the feature list. The README points to the installation guide for reverse-proxy examples and to the configuration guide for further details. Those guides are the appropriate source for settings beyond the Compose example.

The Compose file in the repository differs from the README example. The repository version defines a service named `web`, builds from the local `.` directory, and uses the same `8080:80` mapping and `./app-data:/app-data` volume. That distinction matters when reproducing the deployment: the README example pulls `redimp/otterwiki:2`, while the checked-in file builds the current development version.

Persistent data, reverse proxy, and operational boundaries

The `./app-data:/app-data` mount is the clearest documented operational boundary. The repository Compose file says this mount makes settings, the database, and the repository accessible outside the container. The README instructs administrators to configure a web server when the wiki must be reachable through the internet or a domain name, and links to reverse-proxy examples for nginx, Apache, and Caddy.

That arrangement keeps the container and its host-facing configuration separate. It does not, by itself, document backup procedures for the Git repository, the database, attachments, or application settings. The README also does not state which database backend is configured by default, how attachments are stored internally, or how migrations behave between releases. A deployment plan based only on the Compose file would therefore lack important backup and recovery details.

The Dockerfile builds a Python 3.11 environment, installs dependencies from `pyproject.toml`, copies the `otterwiki` package, and includes a test stage with Git and the development dependencies. This supports a container-based development and release workflow, but the Dockerfile excerpt does not provide a separate production entrypoint or a documented backup job. The `restart: unless-stopped` setting applies to container restart policy, not data durability.

The project metadata requires Python `>=3.11` for direct package installation. Its pinned dependency versions make the environment relatively explicit, but exact upgrade and compatibility procedures are not documented in the README. Release notes and `CHANGELOG.md` are available repository files, so an administrator should inspect them before changing the image tag.

When Otter Wiki is the wrong content tool

Otter Wiki is a poor fit for a workflow whose primary requirement is a database-backed application model with transactions, structured permissions, or real-time concurrent editing. Its documented strength is a simple wiki interface over Markdown and Git. That design is attractive for documentation, internal notes, and small collaborative sites, but the README does not claim transactional editing, a hosted service, or advanced approval workflows. Those missing features should not be inferred from the word wiki.

The experimental Git HTTP server also changes the risk profile for teams that expect ordinary Git semantics. The README names clone, pull, and push, but does not explain merge conflict behavior, branch policies, authentication, or protection against concurrent writes. A team that depends on predictable pull-request review through Otter Wiki's interface should not assume that the experimental server provides the same controls as a separately managed Git hosting service.

For a highly structured product documentation system, a documentation generator may be a better fit when source files can be built into a static site. Such a generator changes the operating model from editing a live wiki to maintaining files and rebuilding output. Otter Wiki instead offers authenticated browser editing and an application-managed repository, which is more suitable when contributors should make changes through the site itself. Neither comparison removes the need to decide who owns backups, conflict resolution, and deployment.

Release activity, license, and upgrade considerations

The repository is not archived, and its last push was on 2026-10-11. The recent release list includes `v2.25.2` on 2026-10-11, `v2.25.1` on 2026-10-09, and `v2.25.0` on 2026-10-03. These dates indicate recent release activity in the project history, but the README does not describe a support policy, compatibility matrix, or migration guide for every version. The security-oriented title of `v2.25.2` is not enough to infer the scope of its security fixes.

The project is distributed under the MIT License. That identifier permits use, modification, distribution, and sublicensing under the license's conditions, but deployment operators still need to review the repository's `LICENSE` file and any bundled third-party notices. The README also credits the otter logo under CC BY 3.0. This is relevant to packaging and redistribution because the application license and the logo license are separate items in the documentation.

Upgrade planning should focus first on the persisted `/app-data` directory, which includes settings, the database, and the repository according to the repository Compose file. The README does not explain whether upgrading the image performs a database migration, how to roll back a release, or how to reconcile repository changes made during a deployment. Those are concrete pre-upgrade checks, not reasons to assume the upgrade is unsafe.

Editorial conclusion

Adopt An Otter Wiki when Markdown files in Git are the preferred source of truth and a small Flask application can serve the editing interface. Do not choose it when your requirements depend on undocumented database, deployment, backup, or conflict-resolution behavior. Before adoption, verify the intended reverse proxy, persistent `/app-data` directory, authentication setup, release upgrade process, and recovery plan.

Frequently asked questions

Official sources

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