Naked blogging platform
black changed its mind about new lines
fix typos and reword on export index
fix hugo and zola double quote escape


browse  log 



You can also use your local clone with git send-email.


Naked blogging platform.


We have a mailing list at ~sirodoht/mataroa-community@lists.sr.ht for the mataroa community to introduce themselves, their blogs, and discuss anything that’s on their mind!

Archives at lists.sr.ht/~sirodoht/mataroa-community


Victor Freire has created mata, a CLI tool for Mataroa.


Feel free to open a PR on GitHub or send an email patch to ~sirodoht/public-inbox@lists.sr.ht.

On how to contribute using email patches see git-send-email.io.

Also checkout our docs on:


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.


python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
pip install -r requirements.txt

#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

.envrc should contain the following variables:

export DEBUG=1
export SECRET_KEY=some-secret-key
export DATABASE_URL=postgres://mataroa:db-password@db:5432/mataroa
export EMAIL_HOST_USER=smtp-user
export EMAIL_HOST_PASSWORD=smtp-password

When on production, also include/update the following variables (see Deployment and Backup):

export DEBUG=0
export PGPASSWORD=db-password


This project is using one PostreSQL database for persistence.

One can use the make pginit command to initialise a database in the postgres-data/ directory.

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

python manage.py migrate

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

python manage.py loaddata dev-data


To develop locally with subdomains, one needs something like this in their /etc/hosts: mataroalocal.blog random.mataroalocal.blog test.mataroalocal.blog mylocalusername.mataroalocal.blog

/etc/hosts does not support wildcard entries, thus there needs to be one entry per mataroa user/blog.


To run the Django development server:

python manage.py runserver


If Docker and docker-compose are preferred, then:

  1. Set DATABASE_URL in .envrc to postgres://postgres:postgres@db:5432/postgres
  2. Run docker-compose up -d.

The database data will be saved in the git-ignored directory / Docker volume docker-postgres-data, located in the root of the project.


Using the Django test runner:

python manage.py test

For coverage, run:

make cov

#Code linting & formatting

The following tools are used for code linting and formatting:

To use:

make format
make lint


Deployment is configured using uWSGI and Caddy.

A server playbook document is also available, based on Ubuntu 20.04 LTS.

Environment variables for production are defined both in uwsgi.ini (for uWSGI) and in .envrc (for manage.py commands such as migrations and cron management commands).

cp uwsgi.example.ini uwsgi.ini  # edit environment variables in uwsgi.ini
uwsgi uwsgi.ini  # start djago app
caddy start --config /home/roa/mataroa/Caddyfile  # start caddy server

To reload or stop the uWSGI process:

uwsgi --reload mataroa.pid
uwsgi --stop mataroa.pid

# or find the PID and kill that directly
ps aux|grep uwsgi
kill -9 <PID>

To reload or store the Caddy webserver:

caddy reload --config /home/roa/mataroa/Caddyfile
caddy stop

Also, two cronjobs (used by the email newsletter feature) need to be installed. The schedule is subject to the administrator’s preference. Indicatively:

*/5 * * * * bash -c 'cd /home/roa/mataroa && source ./venv/bin/activate && source .envrc && python manage.py enqueue_notifications'
*/10 * * * * bash -c 'cd /home/roa/mataroa && source ./venv/bin/activate && source .envrc && python manage.py process_notifications'
0 0 1 * * bash -c 'cd /home/roa/mataroa && source ./venv/bin/activate && source .envrc && python manage.py mail_exports'

Documentation about these commands can be found in section Management.

Finally, certain setting variables may need to be redefined:



To automate backup, one can run backup-database.sh which dumps the database and uploads it into any S3-compatible object storage cloud using the MinIO client. This script needs the database password as an environment variable. The key must be PGPASSWORD. The variable can live in .envrc as such:

export PGPASSWORD=db-password

To restore a database dump:

pg_restore -v -h localhost -cO --if-exists -d mataroa -U mataroa -W mataroa.dump

To add on cron:

0 */6 * * * /home/roa/mataroa/backup-database.sh


In addition to the standard Django management commands, there are also:

  • enqueue_notifications: create records for notification emails to be sent.
  • process_notifications: sends notification emails for new blog posts of existing records.
  • mail_exports: emails users of their blog exports.

They are triggered using the standard manage.py Django way; eg:

python manage.py enqueue_notifications


One can deploy mataroa without setting up billing functionalities. This is the default case. To handle payments and subscriptions this project uses Stripe. To enable Stripe and payments, one needs to have a Stripe account with a single Product (eg. "Mataroa Premium Plan").

To configure, add the following variables from your Stripe account to your .envrc:

export STRIPE_API_KEY="sk_test_XXX"
export STRIPE_PUBLIC_KEY="pk_test_XXX"
export STRIPE_PRICE_ID="price_XXX"


This software is licensed under the MIT license. For more information, read the LICENSE file.