Repository files navigation

Naked blogging platform.

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

Archives atlists.sr.ht/~sirodoht/mataroa-community

• mataroa-cli
• Mataroa Telegram Bot

Open a PR onGitHub.

Send an email patch to~sirodoht/public-inbox@lists.sr.ht.See how to contribute using email patches here:git-send-email.io.

Read our docs atdocs.mataroa.blog

This is aDjango codebase. Check out theDjango docs for general technicaldocumentation.

The Django project ismataroa. There is one Django app,main, with all business logic. Application CLI commands are generallydivided into two categories, those underpython manage.py and those undermake.

Because mataroa works primarily with subdomain, one cannot access the basic web appusing the standardhttp://127.0.0.1:8000 orhttp://localhost:8000 URLs. What we dofor local development is adding 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 localdevelopment environment, so that the web server can respond to it.

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

# /etc/hosts127.0.0.1 mataroalocal.blog127.0.0.1 paul.mataroalocal.blog127.0.0.1 random.mataroalocal.blog127.0.0.1 anyusername.mataroalocal.blog

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

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

docker compose up

If you have also configured hosts as described above in the "Set up subdomains"section, mataroa should now be locally accessible athttp://mataroalocal.blog:8000/

Note: The database data are saved in the git-ignoreddocker-postgres-data dockervolume, located in the root of the project.

We useuv for dependency management and virtual environments.

uv sync --all-groups

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

cp .envrc.example .envrc

.envrc should contain the following variables:

# .envrcexport DEBUG=1export SECRET_KEY=some-secret-keyexport DATABASE_URL=postgres://mataroa:db-password@db:5432/mataroaexport EMAIL_HOST_USER=smtp-userexport EMAIL_HOST_PASSWORD=smtp-password

When on production, also include/update the following variables (seeDeployment andBackup):

# .envrcexport DEBUG=0export PGPASSWORD=db-password

When on Docker, to change or populate environment variables, edit theenvironmentkey of theweb service either directly ondocker-compose.yml or by overriding itusing the standard named git-ignoreddocker-compose.override.yml.

# docker-compose.override.ymlversion:"3.8"services:  web:    environment:      EMAIL_HOST_USER=smtp-user      EMAIL_HOST_PASSWORD=smtp-password

Finally, stop and startdocker compose up again. It should pick up the override fileas it has the default namedocker-compose.override.yml.

This project is using one PostreSQL database for persistence.

One can use themake pginit command to initialise a database in thepostgres-data/ directory.

After setting theDATABASE_URL (see above), createthe 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 inmain/fixtures/dev-data.json
• Credentials of the fixtured user areadmin /admin.

To run the Django development server:

uv python manage.py runserver

If you have also configured hosts as described above in the "Set up subdomains"section, mataroa should now be locally accessible athttp://mataroalocal.blog:8000/

Using the Django test runner:

uv run python manage.pytest

For coverage, run:

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

We useruff for Python code formatting and linting.

To format:

uv run ruff format

To lint:

uv run ruff checkuv run ruff check --fix

We useuv to manage dependencies declared inpyproject.toml (see[project] and[dependency-groups]).

Common commands:

# Add or remove dependenciesuv add<package>uv remove<package># Update locked versions and installuv lock -Uuv sync --all-groups

See theDeployment document for an overview on stepsrequired to deploy a mataroa instance.

To reload the gunicorn process:

sudo systemctl reload mataroa

To reload Caddy:

systemctl restart caddy# root only

gunicorn logs:

journalctl -fb -u mataroa

Caddy logs:

journalctl -fb -u caddy

Get an overview with systemd status:

systemctl status caddysystemctl status mataroa

SeeDatabase Backup for details. In summary:

To create a database dump:

pg_dump -Fc --no-acl mataroa -h localhost -U mataroa -f /home/deploy/mataroa.dump -w

To restore a database dump:

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

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

• processnotifications: sends notification emails for new blog posts of existing records.
• mailexports: emails users of their blog exports.

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

python manage.py processnotifications

One can deploy mataroa without setting up billing functionalities. This isthe default case. To handle payments and subscriptions this project usesStripe. To enable Stripe and payments, one needs to havea Stripe account with a singleProduct (eg. "Mataroa PremiumPlan").

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"

Copyright Mataroa Contributors

This program is free software: you can redistribute it and/or modify it underthe terms of the GNU Affero General Public License as published by the FreeSoftware Foundation, version 3.