Cerca
a forum software
screenshot of cerca, as deployed for the merveilles community forum
Meaning:
- to search, quest, run (it)
- near, close, around, nearby, nigh (es)
- approximately, roughly (en; from circa)
This piece of software was created after a long time of pining for a new wave of forums hangs. The reason it exists are many. To harbor longer form discussions, and for crawling through threads and topics. For habitually visiting the site to see if anything new happened, as opposed to being obtrusively notified when in the middle of something else. For that sweet tinge of nostalgia that comes with the terrain, from having grown up in pace with the sprawling phpBB forum communities of the mid noughties.
It was initially written for the purpose of powering the nascent Merveilles community forums.
Design points
- No likes or popularity symbols
- Markdown input
- Make threads independent of category => enable trivial moving of posts
- As little design as possible
- As little bespoke HTML as possible, minimize use of custom classes
- No mandatory client-side javascript, and no javascript at all—as far as possible
- Move slow
- Minimize maintenance requirements through minimizing external infra and dependencies; eschew email
The contributing guidelines further crystallizes other development decisions:
At the end of the day, a maintainer must live with decisions made for the project—both good and bad! That weight of responsibility is taken into account when looking at new contributions.
cerca logo by rostiger
More information
Cerca supports community customization:
- Write a custom about text describing the community inhabiting the forum
- Define your own registration rules, how to verify one’s account, and link to an existing code of conduct
- Set your own custom logo (whether svg, png or emoji)
- Create your own theme by writing plain, frameworkless css
Manual install
For a simple manual install, run the following commands:
// build the cerca binary
go build ./cmd/cerca
// cerca can write a default config and save at a specified path;
// the command also writes the database and content files cerca needs
cerca write-defaults -config <path-to-cerca.toml> -data-dir <dir-to-store-files-and-database>
// cerca can now host your forum - pass the config path you gave previously
cerca -config <path-to-cerca.toml>
// for more options and commands, run -help:
cerca -help
In general, after running the cerca
process once, you will find that all the customizable
files are located relative to the data_dir
specified in the config file:
├── assets
│ ├── logo.html
│ └── theme.css
├── docs
│ ├── about.md
│ ├── registration.md
│ └── rules.md
└── forum.db
Change any of these files and then restart the cerca
process to serve the changes (force-refresh your
browser to see theme.css
changes).
The configuration format is TOML and the config is populated with the following defaults:
[general]
name = "" # whatever you want to name your forum; primarily used as display in tab titles
conduct_url = "" # optional + recommended: if omitted, the CoC checkboxes in /register will be hidden
language = "English" # Swedish, English. contributions for more translations welcome!
auth_key = "" # generate with `cerca genauthkey` if empty (i.e. "")
data_dir = "/var/lib/cerca" # where the database should be stored — feel free to keep default value
[rss]
feed_name = "" # defaults to [general]'s name if unset
feed_description = ""
forum_url = "" # should be forum index route https://example.com. used to generate post routes for feed, must be set to generate a feed
Translations
Cerca supports use with different natural languages. To translate Cerca into your language, please have a look at the existing translations (i18n.go) and submit yours as a pull request.
Local development
Install golang.
To launch a local instance of the forum on Linux:
First output and configure the default config and the required content files by running the
cerca write-defaults
command:
go run ./cmd/cerca write-defaults -config ./cerca.toml -data-dir ./cerca-data
Then run the forum:
go run ./cmd/cerca -dev -config ./cerca.toml
It should respond Serving forum on :8277
. You can now go to http://localhost:8277.
Lending Inspiration
For some reason, Cerca struck a chord. This little section lists some projects that have been inspired by it.
azlen elza’s forum-shaped notebook runs a personal fork of cerca
- Cerca was used by a post-doc friend as an example in constructing a minimal project (melting my heart on hearing)
- Azlen Elza’s “forum-shaped notebook”
- winduptoy.sensorstation.co/oasis.html (wayback archive link)
- aw
is running a fork of cerca over at https://fishbb.nyc/is running a cousin to cerca at https://fishbb.org/- Later giving birth to a new codebase: https://git.sr.ht/~aw/fishbb
- And even later, to another forum implementation in ruby also by aw
- the merveilles community map was inspired by cerca for being “a wonderful example of small, community-focused tooling”
- tendigits created a guide for how to style their own view of the merveilles forum
- izzzi “an experiment which might be called ‘slow social media’ where posts are collected into a digest once a day / posts from yesterday are deleted, forever, every day / posts are only visible between mutuals”
- the permacomputing community runs cerca: bbs.permacomputing.net
- a LATAM community is running cerca: foro.archipielago.uno
- an experimental cerca forum was launched by the low carbon computing collective