114 lines
4.0 KiB
Markdown
114 lines
4.0 KiB
Markdown
# 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](https://forum.poto.cafe/).
|
|
|
|
## 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](https://bitty-js.com)) 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+](https://thufie.lain.haus/NPL.html).
|
|
please read the [full terms](./LICENSE.md) for proper wording.
|
|
|
|
# acknowledgments
|
|
|
|
pyrom uses many open-source and otherwise free-culture components. see the [THIRDPARTY](./THIRDPARTY.md) file for full credit.
|
|
|
|
# installing & first time setup
|
|
## docker (production)
|
|
1. clone the repo
|
|
2. create `config/secrets.prod.env` according to `config/secrets.prod.env.example`
|
|
3. create `config/pyrom_config.toml` according to `config/pyrom_config.toml.example` and modify as needed
|
|
4. make sure the `data/` folder is writable by the app:
|
|
|
|
```bash
|
|
$ chmod -R 777 data/
|
|
```
|
|
|
|
5. bring up the container:
|
|
|
|
```bash
|
|
$ 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.
|
|
|
|
6. point your favorite proxy at `localhost:8080`
|
|
|
|
## manual (development)
|
|
1. install python >= 3.13, sqlite3, libargon2, and imagemagick & clone repo
|
|
2. create a venv:
|
|
|
|
```bash
|
|
$ python -m venv .venv
|
|
$ source .venv/bin/activate
|
|
```
|
|
|
|
3. install requirements:
|
|
|
|
```bash
|
|
$ pip install -r requirements.txt
|
|
```
|
|
|
|
4. run dev server:
|
|
|
|
```bash
|
|
$ 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 <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop the server.
|
|
|
|
to deactivate the venv:
|
|
|
|
```bash
|
|
$ deactivate
|
|
```
|
|
|
|
when you want to run the server again, make sure to activate the venv first:
|
|
```bash
|
|
$ source .venv/bin/activate
|
|
$ python -m app.run
|
|
```
|
|
|