1# clover sitegen framework and typescript library
2
3this repository contains clover's "sitegen" framework, which is a set of tools
4that assist building websites. additionally, this is the home of her typescript
5library [`lib`](./lib/readme.md), containing many high quality standalone
6sub-projects. all these tools power <https://paperclover.net>.
7
8none of these tools are complex or revolutionary. rather, this project is the
9sum of many years of experience on managing content heavy websites, and an
10example on how other over-complicate other frameworks.
11
12Included is `src`, which contains `paperclover.net`'s source code. Highlights:
13
14- TODO: flashy homepage.
15- [Question/Answer board, custom markdown parser and components][q+a].
16- [File viewer with fast ui/ux + optimized media streaming][file].
17- [Personal, friends-only blog with password protection][friends].
18- [Blog with pretty automatic table of contents][blog].
19
20[q+a]: https://paperclover.net/q+a
21[file]: https://paperclover.net/file
22[friends]: https://paperclover.net/friends
23[blog]: https://paperclover.net/blog/webdev/one-year-next-app-router
24
25## Development
26
27minimum system requirements:
28
29- a cpu with at least 1 core.
30- some random access memory.
31- any operating system with node.js v26
32- the internet.
33
34my primary development machine is a Dell Inspiron 7348 (Core i7) with Windows 7
35
36 # copy the site's databases. without `CLOVER_SOT_KEY` in `.env`, the
37 # copies hold what the site shows anyone.
38 node run download-db
39
40 # setup and run the site locally, watching for changes.
41 node run
42
43for unix systems, the provided `flake.nix` can be used with `nix develop` to
44open a shell with all needed system dependencies.
45
46## Deployment
47
48there are two primary server components to be deployed: the web server and the
49sourth of truth server. The latter is a singleton that runs on Clover's NAS,
50which holds the full contents of the file storage. The web server pulls data
51from the source of truth and renders web pages, and can be duplicated to
52multiple cloud hosts without issue.
53
54deployment of the source of truth can be done with Docker Compose:
55
56 services:
57 backend:
58 container_name: backend
59 build:
60 # this uses loopback to hit the self-hosted git server,
61 # docker will cache the image to not re-fetch on reboot.
62 context: http://127.0.0.1:3000/clo/sitegen.git
63 dockerfile: src/source-of-truth.dockerfile
64 environment:
65 # configuration
66 - PORT=43200
67 - CLOVER_DB=/data
68 - CLOVER_FILE_RAW=/published
69 - CLOVER_FILE_DERIVED=/data/derived
70 - CLOVER_SOT_KEY=... # guards private/unreleased content
71 ports:
72 - '43200:43200'
73 restart: unless-stopped
74 volumes:
75 - /mnt/storage1/clover/Documents/Config/paperclover:/data
76 - /mnt/storage1/clover/Published:/published
77
78due to caching, images may need to be purged via `docker image rm {image} -f`
79when an update is desired. some docker GUIs support force pulls, some are buggy.
80
81## Contributions
82
83No contributions to `src` accepted, only `lib` and `framework`.