Pyrom

pyrom is a playful home-grown forum software for the indie web borne out of frustration with social media and modern forums imitating it.

the aim is not to recreate the feeling of forums from any time period. rather, it aims to serve as a lightweight alternative to other forum software packages. pyrom is lean and "fire-and-forget"; there is little necessary configuration, making it a great fit for smaller communities (though nothing prevents it from being used in larger ones.)

a live example can be seen in action over at Porom.

stack & structure

on the server side, pyrom is built in Python using the Flask framework. content is rendered mostly server-side with Jinja templates. the database used is SQLite.

on the client side, JS with only one library (Bitty) is used. for CSS, pyrom uses Sass.

below is an explanation of the folder structure:

/
- app/
  - lib/ - utility libraries
  - routes/ - each .py file represents a "sub-app", usually the first part of the URL
  - templates/ - Jinja templates used by the routes. each subfolder corresponds to the "sub-app" that uses that template.
  - __init__.py - creates the app
  - auth.py - authentication helper
  - constants.py - constant values used throughout the forum
  - db.py - database abstraction layer and ORM library
  - migrations.py - database migrations
  - models.py - ORM model definitions
  - run.py - runner script for development
  - schema.py - database schema definition
- config/ - configuration for the forum
- data/
  - _cached/ - cached versions of certain endpoints are stored here
  - db/ - the SQLite database is stored here
  - static/ - static files
    - avatars/ - user avatar uploads
    - badges/ - user badge uploads
    - css/ - CSS files generated from Sass sources
    - emoji/ - emoji images used on the forum
    - fonts/
    - js/
- sass/
  - _default.scss - the default theme. Sass variables that other themes modify are defined here, along with the default styles. other files define the available themes.
- build-themes.sh - script for building Sass files into CSS
- nginx.conf - nginx config (production only)
- uwsgi.ini - uwsgi config (production only)

license

released under CNPLv7+. please read the full terms for proper wording.

acknowledgments

pyrom uses many open-source and otherwise free-culture components. see the THIRDPARTY file for full credit.

installing & first time setup

docker (production)

clone the repo
create config/secrets.prod.env according to config/secrets.prod.env.example
create config/pyrom_config.toml according to config/pyrom_config.toml.example and modify as needed
make sure the data/ folder is writable by the app:

$ chmod -R 777 data/

bring up the container:

$ docker compose up --build

opens port 8080
exposes data/db and data/static for data backup and persistence

make sure to run it in an interactive session the first time, because it will spit out the password to the auto-created admin account.

point your favorite proxy at localhost:8080

manual (development)

install python >= 3.13, sqlite3, libargon2, and imagemagick & clone repo
create a venv:

$ python -m venv .venv
$ source .venv/bin/activate

install requirements:

$ pip install -r requirements.txt

run dev server:

$ python -m app.run

the server will run on localhost:8080. when run for the first time, it will create an admin account and print its credentials to the terminal, so make sure to run this in an interactive session.

press Ctrl+C to stop the server.

to deactivate the venv:

$ deactivate

when you want to run the server again, make sure to activate the venv first:

$ source .venv/bin/activate
$ python -m app.run

4.0 KiB Raw Blame History