Minimal blogging platform with export as first-class feature.
On how to contribute using email patches see git-send-email.io.
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
and those under
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 dependency management.
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 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
export NODEBUG=1 export PGPASSWORD=db-password
This project uses PostgreSQL. Assuming one has set the
DATABASE_URL (see above), to create the
python manage.py migrate
Also, initialising the database with some sample development data is possible with:
python manage.py populate_dev_data
To develop locally with subdomains, one needs something like that in
127.0.0.1 mataroalocal.blog 127.0.0.1 random.mataroalocal.blog 127.0.0.1 test.mataroalocal.blog 127.0.0.1 mylocalusername.mataroalocal.blog
/etc/hosts does not support wildcard entries, there needs to be one entry for each
To run the Django development server:
python manage.py runserver
If Docker and docker-compose are preferred, then:
docker-compose up -d.
The database data will be saved in the git-ignored directory / Docker volume
located in the root of the project.
Using the Django test runner:
python manage.py test
For coverage, run:
The following tools are used for code linting and formatting:
make format make lint
Remember to set the environment variables before starting
uwsgi. Depending on the deployment
environment, this could mean directly exporting the variables or just sourcing
.envrc (with all
production variables — including
source .envrc uwsgi uwsgi.ini # start djago app caddy start --config /home/roa/mataroa/Caddyfile # start caddy server
Note that the value of the
NODEBUG variable is ignored. What matters is merely its existence
in the environment.
Also, two cronjobs (used by the email newsletter feature) are needed 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'
Documentation about the commands can be found in section Management.
Finally, certain setting variables may need to be redefined:
To automate backup, there is a script which dumps the database and uploads
it into AWS S3. The script also needs the database password as an environment variable. The
key needs to be
PGPASSWORD. The backup script assumes the variable lives in
.envrc like so:
To restore a 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.
populate_dev_data: populate database with sample development data.
They are triggered using the standard
manage.py Django way:
python manage.py enqueue_notifications
This software is licensed under the MIT license. For more information, read the LICENSE file.