README.md (5020B)
1 # Cerca 2 _a forum software_ 3 4 Meaning: 5 * to search, quest, run _(it)_ 6 * near, close, around, nearby, nigh _(es)_ 7 * approximately, roughly _(en; from **circa**)_ 8 9 This piece of software was created after a long time of pining for a new wave of forums hangs. 10 The reason it exists are many. To harbor longer form discussions, and for crawling through 11 threads and topics. For habitually visiting the site to see if anything new happened, as 12 opposed to being obtrusively notified when in the middle of something else. For that sweet 13 tinge of nostalgia that comes with the terrain, from having grown up in pace with the sprawling 14 phpBB forum communities of the mid noughties. 15 16 It was written for the purpose of powering the nascent [Merveilles community forums](https://forum.merveilles.town). 17 18 ## Features 19 20 * **Customizable**: Many of Cerca's facets are customizable and the structure is intentionally simple to enable DIY modification 21 * **Private**: Threads are public viewable by default but new threads may be set as private, restricting views to logged-in users only 22 * **Easy admin**: A simple admin panel lets you add users, reset passwords, and remove old accounts. Impactful actions require two admins to perform, or a week of time to pass without a veto from any admin 23 * **Transparency**: Actions taken by admins are viewable by any logged-in user in the form of a moderation log 24 * **Low maintenance**: Cerca is architected to minimize maintenance and hosting costs by carefully choosing which features it supports, how they work, and which features are intentionally omitted 25 * **RSS**: Receive updates when threads are created or new posts are made by subscribing to the forum RSS feed 26 27 ## Config 28 Cerca supports community customization. 29 30 * Write a custom [about text](/defaults/sample-about.md) describing the community inhabiting the forum 31 * Define your own [registration rules](/defaults/sample-rules.md), [how to verify one's account](/defaults/sample-verification-instructions.md), and link to an existing code of conduct 32 * Set your own [custom logo](/defaults/sample-logo.html) (whether svg, png or emoji) 33 * Create your own theme by writing plain, frameworkless [css](/html/assets/theme.css) 34 35 To enable these customizations, there's a config file. To choose a config file, run cerca with 36 the `--config` option; the default config file is set to `./cerca.toml`. 37 38 ``` 39 cerca --config ./configs/cerca.toml 40 ``` 41 42 The configuration format is [TOML](https://toml.io/en/) and the config is populated with the following 43 defaults: 44 45 ```TOML 46 [general] 47 name = "" # whatever you want to name your forum; primarily used as display in tab titles 48 conduct_url = "" # optional + recommended: if omitted, the CoC checkboxes in /register will be hidden 49 language = "English" # Swedish, English and a few others. contributions for more translations welcome! 50 51 [rss] 52 feed_name = "" # defaults to [general]'s name if unset 53 feed_description = "" 54 forum_url = "" # should be forum index route https://example.com. used to generate post routes for feed, must be set to generate a feed 55 56 [documents] 57 logo = "content/logo.html" # can contain emoji, <img>, <svg> etc. see defaults/sample-logo.html in repo for instructions 58 about = "content/about.md" 59 rules = "content/rules.md" 60 verification_instructions = "content/verification-instructions.md" 61 ``` 62 63 Content documents that are not found will be prepopulated using Cerca's [sample content 64 files](/defaults). The easiest thing to do is to run Cerca once and let it populate content 65 files using the samples, and then edit the files in `content/*` after the fact, before running 66 Cerca again to see your changes. 67 68 Either write your own configuration following the above format, or run cerca once to populate it and 69 then edit the created config. 70 71 ## Contributing 72 If you want to join the fun, first have a gander at the [CONTRIBUTING.md](/CONTRIBUTING.md) 73 document. It lays out the overall idea of the project, and outlines what kind of contributions 74 will help improve the project. 75 76 ### Translations 77 78 Cerca supports use with different natural languages. To translate Cerca into your language, please 79 have a look at the existing [translations (i18n.go)](/i18n/i18n.go) and submit yours as a 80 [pull request](https://github.com/cblgh/cerca/compare). 81 82 ## Local development 83 84 Install [golang](https://go.dev/). 85 86 To launch a local instance of the forum, run those commands (linux): 87 88 - `go run run.go --dev` 89 90 It should respond `Serving forum on :8277`. Just go on [http://localhost:8277](http://localhost:8277). 91 92 ### Building binaries with reduced size 93 This is optional, but if you want to minimize the size of any binary (whether it be the `cerca` executable 94 or any of the binaries in [`cmd/`](/cmd/) follow the instructions below. Less useful for active development, more 95 useful for sending binaries to other computers. 96 97 Pass `-ldflags="-s -w"` when building your binary: 98 99 ``` 100 go build -ldflags="-s -w" . 101 ``` 102 103 Additionally, run [upx](https://upx.github.io) on any generated binary: 104 105 ``` 106 upx --lzma cerca 107 ```