Oddmuse

Oddmuse is a lightweight, self‑hosted wiki engine written in Perl that runs as an Apache CGI script. Its core purpose is to provide a minimal yet extensible platform for collaborative editing while keeping the deployment footprint small. The application serves HTML pages directly from a file‑based data store (defaulting to /tmp/oddmuse) but can be reconfigured to use any directory writable by the web server. Each page is stored as a plain‑text file with optional metadata, and revision history is maintained by the script itself rather than relying on a separate database.

Key Features

• File‑based persistence – No external database is required; all page content, history logs, and configuration are stored as files in a single directory.
• Perl CGI architecture – The entire runtime is a single wiki.pl script that Apache executes per request, making it easy to drop into any existing CGI‑enabled environment.
• Extensible module system – Built‑in modules cover user authentication, translation, and content filtering; additional modules can be dropped into the modules/ directory without recompilation.
• REST‑like API – While primarily a web UI, Oddmuse exposes simple HTTP endpoints for creating, editing, and retrieving pages (e.g., ?action=edit, ?action=view). These can be consumed by external tools or integrated into CI pipelines.

Technical Stack

The choice of Perl allows rapid iteration and a large ecosystem of CPAN modules for extensions. The CGI model keeps the runtime stateless, which simplifies scaling via load balancers or reverse proxies.

Core Capabilities

• Page creation & editing – Classic wiki markup with double‑square brackets for links.
• Revision control – Automatic diffs and rollback via ?action=history.
• Authentication hooks – Supports Apache’s mod_auth or custom Perl modules for token‑based auth.
• Search – Built‑in full‑text search over the file system, optionally powered by external tools like grep.
• RSS feeds – Generates channel feeds for recent changes.
• Hooks & callbacks – Developers can inject code before/after page rendering or editing, enabling custom workflows.

Deployment & Infrastructure

Oddmuse is designed for simplicity: copy wiki.pl to Apache’s cgi-bin, set the data directory with an environment variable, and ensure ownership for the web user (www-data). No daemon or background process is required. For production, it can be placed behind a reverse proxy (NGINX or HAProxy) to handle SSL termination and load balancing. Containerization is straightforward; the official Docker image mounts a persistent volume for data storage, making it suitable for Kubernetes or Docker‑Compose setups.

Integration & Extensibility

• Plugin system – Drop Perl modules into modules/; they automatically register actions and UI hooks.
• Webhooks – Custom modules can emit HTTP callbacks on page updates, enabling integrations with CI/CD pipelines or external notification services.
• API access – Although not a full REST API, the query parameters provide programmatic control; developers can wrap these in higher‑level SDKs.
• Template customization – The HTML output is generated via simple Perl templates; developers can override layout files to match branding or integrate with front‑end frameworks.

Developer Experience

The documentation is concise and focused on the minimal steps required to get a wiki running. Configuration is exposed via environment variables (WikiDataDir) and Apache’s SetEnv, keeping the codebase untouched. The Perl community offers extensive resources for debugging and extending the application. Community support is active on mailing lists and GitHub, with frequent module contributions that demonstrate a healthy ecosystem.

Use Cases

• Internal knowledge bases for small teams where database overhead is undesirable.
• Documentation portals that need to be version‑controlled and searchable without a full CMS stack.
• DevOps playbooks that can be updated through the web UI and then exported to Git or other SCM tools.
• Educational labs where students can learn wiki markup and collaboration in a controlled environment.

Advantages

For developers seeking a lightweight, self‑hosted wiki that can be embedded into existing Perl or Apache environments, Oddmuse offers a clean balance between minimalism and extensibility. Its file‑based design eliminates operational complexity, while the Perl module system keeps the door open for custom features and integrations.