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- random access memory.
31- windows 7 or later, macos, or other operating system.
32
33required software:
34
35- node.js v24
36
37my development machine, for example, is Dell Inspiron 7348 with Core i7
38
39 # install, build, serve, and watch for incremental rebuilds
40 node run watch
41
42 # create a production site
43 node run generate
44 node --enable-source-maps .clover/o/backend
45
46for unix systems, the provided `flake.nix` can be used with `nix develop` to
47open a shell with all needed system dependencies.
48
49## Deployment
50
51there are two primary server components to be deployed: the web server and the
52sourth of truth server. The latter is a singleton that runs on Clover's NAS,
53which holds the full contents of the file storage. The web server pulls data
54from the source of truth and renders web pages, and can be duplicated to
55multiple cloud hosts without issue.
56
57Deployment of the source of truth can be done with Docker Compose:
58
59 services:
60 backend:
61 container_name: backend
62 build:
63 # this uses loopback to hit the self-hosted git server,
64 # docker will cache the image to not re-fetch on reboot.
65 context: http://127.0.0.1:3000/clo/sitegen.git
66 dockerfile: src/source-of-truth.dockerfile
67 environment:
68 # configuration
69 - PORT=43200
70 - CLOVER_DB=/data
71 - CLOVER_FILE_RAW=/published
72 - CLOVER_FILE_DERIVED=/data/derived
73 - CLOVER_SOT_KEY=... # guards private/unreleased content
74 ports:
75 - '43200:43200'
76 restart: unless-stopped
77 volumes:
78 - /mnt/storage1/clover/Documents/Config/paperclover:/data
79 - /mnt/storage1/clover/Published:/published
80
81Due to caching, images may need to be purged via `docker image rm {image} -f`
82when an update is desired. Some docker GUIs support force pulls, some are buggy.
83
84The web server performs rendering. A `Dockerfile` for it is present in
85`src/web.dockerfile` but it is currently unused. Deployments are done by
86building the project locally, and then using `rsync` to copy files.
87
88 node run generate
89 rsync .clover/o "$REMOTE_USER:~/paperclover" --exclude=.clover --exclude=.env \
90 --delete-after --progress --human-readable
91 ssh "$REMOTE_USER" /bin/bash << EOF
92 set -e
93 cd ~/paperclover
94 npm ci
95 pm2 restart site
96 echo "-> https://paperclover.net"
97 EOF
98
99## Contributions
100
101No contributions to `src` accepted, only `lib` and `framework`.