Mataroa

Mataroa is a naked blogging platform built on Django, designed for developers who want full control over the hosting environment and a minimalistic, privacy‑first experience. At its core, it serves as a stateless web application that maps each user to a subdomain (e.g., alice.mataroa.blog), enabling isolated blogs without the need for multi‑tenant routing logic. The platform exposes a RESTful API, webhook endpoints, and a command‑line interface (mataroa-cli) for programmatic management of posts, users, and exports.

Technical Stack & Architecture

• Framework: Django 4.x with a single app, main, encapsulating all business logic. The project follows Django’s standard MVT pattern but eschews the admin UI in favor of a custom, lightweight interface.
• Language: Python 3.11+, leveraging type hints and uv for dependency management.
• Database: PostgreSQL, bundled with Docker Compose in a named volume (docker-postgres-data). The schema is intentionally simple—users, posts, media, and export jobs—to keep the migration surface small.
• Containerization: Docker Compose orchestrates a web container (gunicorn + Nginx) and a db container. The Dockerfile is minimal, using the official Python slim image and installing only production dependencies.
• Subdomain Handling: During development, developers map user accounts to /etc/hosts entries. In production, a reverse proxy (NGINX or Traefik) routes subdomains to the Django container, with Host header checks performed in middleware.

Core Capabilities & APIs

• Markdown‑first Publishing: Posts are stored as Markdown with optional front matter. The rendering pipeline uses markdown and a custom template to convert to HTML on the fly.
• Export & Import: CLI commands allow exporting a blog as an EPUB, JSON, or plain Markdown bundle. Import utilities parse markdown files and create posts with metadata.
• RSS & Email Newsletters: Built‑in RSS feeds expose the latest posts; an optional email newsletter system can push updates to subscribers.
• Analytics: Server‑side analytics are collected without third‑party cookies. Metrics (views, referrers) are stored in the same PostgreSQL database and exposed via a lightweight API.
• Webhooks: External services can hook into post creation, update, or deletion events. The webhook payload includes user ID, post slug, and timestamps.

Deployment & Infrastructure

• Self‑Hosting: Requires a Linux host with Docker or a virtual environment for local development. The platform is stateless aside from the database, making horizontal scaling straightforward—add more web replicas behind a load balancer.
• Scalability: Django’s ORM and PostgreSQL handle moderate traffic out of the box. For high‑volume scenarios, caching (Redis) can be introduced for rendered HTML fragments and RSS feeds.
• Customization: The template system is intentionally minimal, but developers can override templates or extend the main app with custom views. Static assets are served via Nginx, allowing CDN integration.

Integration & Extensibility

• Plugin System: While no formal plugin API exists, the codebase is modular. Developers can fork main or create separate Django apps that hook into signals (e.g., post_save) to add functionality such as image processing or social media posting.
• Webhooks & APIs: The REST endpoints follow Django Rest Framework conventions, enabling integration with CI/CD pipelines or external content management tools.
• CLI & Automation: mataroa-cli exposes commands for user and post management, making it suitable for scripting deployments or generating static backups.

Developer Experience

• Documentation: The official docs (docs.mataroa.blog) cover architecture, deployment, and API usage. Community support is active via a mailing list (~sirodoht/mataroa-community@lists.sr.ht) and GitHub discussions.
• Configuration: Environment variables are managed through a .envrc file and direnv, simplifying local setup. The Docker Compose stack abstracts most configuration, but developers can override settings via environment variables.
• Licensing: Released under Affero GPLv3, ensuring that any modifications remain open source while allowing commercial hosting.

Use Cases

1. Personal Blogging: A developer can spin up a private blog in minutes, host it on their own domain, and export content as EPUB for offline reading.
2. Educational Content: Instructors can host course blogs, auto‑export lesson plans via email, and use the API to integrate with learning management systems.
3. Micro‑Publishing: Teams can deploy multiple subdomains for product updates, using the lightweight API to push new posts from CI pipelines.

Advantages Over Alternatives

• Zero Tracking & Privacy: No third‑party analytics or cookies, appealing to privacy‑conscious developers.
• Simplicity & Performance: A single Django app with a lean database schema keeps resource usage low and startup times fast.
• Open Source Freedom: Affero GPL guarantees that any improvements remain in the community, and the absence of platform lock‑in means full control over hosting and data.
• Developer‑Friendly Extensibility: The codebase is small enough to be forked and extended without a steep learning curve, yet mature enough to support production workloads.

Mataroa offers a robust, privacy‑centric blogging foundation that empowers developers to host their own content with minimal friction while retaining the flexibility to extend and integrate as