mataroa

Naked blogging platform.

Table of Contents

• Community
  • Tools
• Local Development
  • Subdomains
  • Docker
  • Dependencies
  • Environment variables
  • Database
  • Serve
  • Testing
  • Code linting and formatting
• Contributing
  • Directory structure
  • Coding Conventions
  • Git Commit Message Guidelines
  • Feature Release Checklist
  • Dependency Policy
• Operations
  • Deployment
  • Billing
  • Recurring Tasks
  • Post by email
  • Database Backup
  • Server Migration Checklist
  • On Server Outage
• License

Community

Main repository on GitHub: github.com/mataroablog/mataroa

Mirror on sr.ht: git.sr.ht/~sirodoht/mataroa

Bug tracking on GitHub: github.com/mataroablog/mataroa/issues

Community mailing list on sr.ht: lists.sr.ht/~sirodoht/mataroa-community

Tools

• mataroa-cli
• Mataroa Telegram Bot

Local Development

This is a Django codebase. Check out the Django docs for general technical documentation.

The Django project is mataroa. There is one Django app, main, with all business logic. Application CLI commands are generally divided into two categories, those under python manage.py and those under make.

Subdomains

Mataroa works primarily with subdomain, thus one cannot access the basic web app using the standard http://127.0.0.1:8000 or http://localhost:8000 URLs. What we do for local development is add a few custom entries on our /etc/hosts system file.

Important note: there needs to be an entry of each user account created in the local development environment, so that the web server can respond to it.

The first line is the main needed: mataroalocal.blog. The rest are included as examples of other users one can create in their local environment. The easiest way to create them is to go through the sign up page (http://mataroalocal.blog:8000/accounts/create/ using default values).

# /etc/hosts

127.0.0.1 mataroalocal.blog

127.0.0.1 paul.mataroalocal.blog
127.0.0.1 random.mataroalocal.blog
127.0.0.1 anyusername.mataroalocal.blog

This will enable us to access mataroa locally (once we start the web server) at http://mataroalocal.blog:8000/ and if we make a user account with username paul, then we will be able to access it at http://paul.mataroalocal.blog:8000/

Docker

[!NOTE] This is the last step for initial Docker setup. See the "Environment variables" section below, for further configuration details.

To set up a development environment with Docker and Docker Compose, run the following to start the web server and database:

docker compose up

If you have also configured hosts as described above in the "Subdomains" section, mataroa should now be locally accessible at http://mataroalocal.blog:8000/

Note: The database data are saved in the git-ignored docker-postgres-data docker volume, located in the root of the project.

Dependencies

We use uv for dependency management and virtual environments.

uv sync --all-groups

See Dependency Policy for more details on adding/upgrading dependencies.

Environment variables

A file named .envrc is used to define the environment variables required for this project to function. One can either export it directly or use direnv. There is an example environment file one can copy as base:

cp .envrc.example .envrc

When on Docker, to change or populate environment variables, edit the environment key of the web service either directly on docker-compose.yml or by overriding it using the standard named git-ignored docker-compose.override.yml.

# docker-compose.override.yml

services:
  web:
    environment:
      EMAIL_HOST_USER: smtp-user
      EMAIL_HOST_PASSWORD: smtp-password

Finally, stop and start docker compose up again. It should pick up the override file as it has the default name docker-compose.override.yml.

Database

This project is using one PostreSQL database for persistence.

One can use the provided script to set up a local Postgres database (user mataroa, passwordless):

./setup-database-localdev.sh

And also easily reset it (drop database and user):

./reset-database-localdev.sh

After setting the DATABASE_URL (see above), create the database schema with:

uv python manage.py migrate

Initialising the database with some sample development data is possible with:

uv python manage.py loaddata dev-data

• dev-data is defined in main/fixtures/dev-data.json
• Credentials of the fixtured user are admin / admin.

Serve

To run the Django development server:

uv python manage.py runserver

If you have also configured hosts as described above in the "Subdomains" section, mataroa should now be locally accessible at http://mataroalocal.blog:8000/

Testing

Using the Django test runner:

uv run python manage.py test

For coverage, run:

uv run coverage run --source='.' --omit '.venv/*' manage.py test
uv run coverage report -m

Code linting and formatting

We use ruff for Python linting and code formatting.

To lint:

uv run ruff check

To apply automatic fixes if they exist:

uv run ruff check --fix

To format:

uv run ruff format --check

Contributing

Main repository on GitHub: github.com/mataroablog/mataroa

Mirror repository on sr.ht: git.sr.ht/~sirodoht/mataroa

Report bugs on GitHub: github.com/mataroablog/mataroa/issues

Contribute on GitHub with Pull Requests: github.com/mataroablog/mataroa/pulls

Contribute with email patches on sr.ht: ~sirodoht/public-inbox@lists.sr.ht. See how to contribute using email patches on git-send-email.io.

Directory structure

Here, an overview of the project's code sources is presented. The purpose is for the reader to understand what kind of functionality is located where in the source code.

All business logic of the application is in one Django app: main.

Condensed and commented sources file tree:

.
├── .build.yml # SourceHut CI build config
├── .envrc.example # example direnv file
├── .github/ # GitHub Actions config files
├── Caddyfile # configuration for Caddy webserver
├── Dockerfile
├── docker-compose.yml
├── export_base_epub/ # base sources for epub export functionality
├── export_base_hugo/ # base sources for hugo export functionality
├── export_base_zola/ # base sources for zola export functionality
├── main/
│   ├── admin.py
│   ├── apps.py
│   ├── denylist.py # list of various keywords allowed and denied
│   ├── feeds.py # django rss functionality
│   ├── fixtures/
│   │   └── dev-data.json # sample development data
│   ├── forms.py
│   ├── management/ # commands under `python manage.py`
│   │   └── commands/
│   │       ├── checkstripe.py
│   │       ├── mailexports.py
│   │       ├── mailsummary.py
│   │       ├── processnotifications.py
│   │       └── testbulkmail.py
│   ├── middleware.py # mostly subdomain routing
│   ├── migrations/
│   ├── models.py
│   ├── sitemaps.py
│   ├── static/
│   ├── templates
│   │   ├── main/ # HTML templates for most pages
│   │   ├── assets/
│   │   │   ├── drag-and-drop-upload.js
│   │   │   └── style.css
│   │   ├── partials/
│   │   │   ├── footer.html
│   │   │   ├── footer_blog.html
│   │   │   └── webring.html
│   │   └── registration/
│   ├── tests/
│   │   ├── test_api.py
│   │   ├── test_billing.py
│   │   ├── test_blog.py
│   │   └── testdata/
│   ├── text_processing.py # markdown and text utilities
│   ├── urls.py
│   ├── validators.py # custom form and field validators
│   └── views/
│       ├── api.py
│       ├── billing.py
│       ├── general.py
├── manage.py
└── mataroa
    ├── asgi.py
    ├── settings.py # django configuration file
    ├── urls.py
    └── wsgi.py

main/urls.py

All urls are in this module. They are visually divided into several sections:

• general, includes index, dashboard, static pages
• user system, includes signup, settings, logout
• blog posts, the CRUD operations of
• blog extras, includes rss and newsletter features
• comments, related to the blog post comments
• billing, subscription and card related
• blog import, export, webring
• images CRUD
• analytics list and details
• pages CRUD

main/views/

The majority of business logic is organized in the views/ directory, split across several modules for better organization.

Generally, Django class-based generic views are used most of