ref: 85fede93239589626fb538eeeb65cea3856a49b6 mataroa/README.md -rw-r--r-- 3.7 KiB
85fede93Theodore Keloglou fix validator message to be inclusive all fields 3 months ago


Minimal blogging platform with export as first-class feature.


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

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


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.


Using venv:

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

This project also uses pip-tools for dependencies management.

#Environment variables

You need to create a new file named .env in the root of this project once you cloned it.

.env should contain the following env variables:



This project uses PostgreSQL. See above on how to configure access to it using the .env file.

There is no need to create manually one if you're using Docker and Docker Compose. Run this to spin up the database in the background:

docker-compose up -d db

The database data will be saved in a gitignored directory, db_data, in the root of the project.

To create the database schema:

python manage.py migrate


To develop locally with subdomains, you need to add something like that in your /etc/hosts: mataroalocal.blog yourlocaluser.mataroalocal.blog random.mataroalocal.blog test.mataroalocal.blog 


To run the Django development server:

python manage.py runserver

Or, if you prefer to run the web server under Docker:

docker-compose up web

In which case, DATABASE_URL in .env should be like this:


You can also run just the database using Docker and the webserver without, in which case .env would be like this:


and you would start the database like so:

docker-compose up db


python manage.py test

#Code linting & formatting

black . && isort --profile black . && flake8


Deployment is configured using the production-grade uwsgi server.

uwsgi --ini=uwsgi.ini -H venv/

You also need to populate your shell environment:

export SECRET_KEY="thisisthesecretkey"
export DATABASE_URL="postgres://username:password@localhost:5432/db_name"
export EMAIL_HOST_USER="smtp_user"
export EMAIL_HOST_PASSWORD="smtp_password"


This project is also configured to deploy to dokku.


Except for the standard Django management commands, there is also:

  • process_notifications: sends notification emails for new blog posts.

To trigger:

python manage.py process_notifications


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