| 1 | # clover sitegen framework and typescript library |
| 2 | |
| 3 | this repository contains clover's "sitegen" framework, which is a set of tools |
| 4 | that assist building websites. additionally, this is the home of her typescript |
| 5 | library [`lib`](./lib/readme.md), containing many high quality standalone |
| 6 | sub-projects. all these tools power <https://paperclover.net>. |
| 7 | |
| 8 | none of these tools are complex or revolutionary. rather, this project is the |
| 9 | sum of many years of experience on managing content heavy websites, and an |
| 10 | example on how other over-complicate other frameworks. |
| 11 | |
| 12 | Included 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 | |
| 27 | minimum 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 | |
| 34 | my primary development machine is a Dell Inspiron 7348 (Core i7) with Windows 7 |
| 35 | |
| 36 | # setup and run the site locally, watching for changes. |
| 37 | node run |
| 38 | |
| 39 | for unix systems, the provided `flake.nix` can be used with `nix develop` to |
| 40 | open a shell with all needed system dependencies. |
| 41 | |
| 42 | ## Deployment |
| 43 | |
| 44 | there are two primary server components to be deployed: the web server and the |
| 45 | sourth of truth server. The latter is a singleton that runs on Clover's NAS, |
| 46 | which holds the full contents of the file storage. The web server pulls data |
| 47 | from the source of truth and renders web pages, and can be duplicated to |
| 48 | multiple cloud hosts without issue. |
| 49 | |
| 50 | deployment of the source of truth can be done with Docker Compose: |
| 51 | |
| 52 | services: |
| 53 | backend: |
| 54 | container_name: backend |
| 55 | build: |
| 56 | # this uses loopback to hit the self-hosted git server, |
| 57 | # docker will cache the image to not re-fetch on reboot. |
| 58 | context: http://127.0.0.1:3000/clo/sitegen.git |
| 59 | dockerfile: src/source-of-truth.dockerfile |
| 60 | environment: |
| 61 | # configuration |
| 62 | - PORT=43200 |
| 63 | - CLOVER_DB=/data |
| 64 | - CLOVER_FILE_RAW=/published |
| 65 | - CLOVER_FILE_DERIVED=/data/derived |
| 66 | - CLOVER_SOT_KEY=... # guards private/unreleased content |
| 67 | ports: |
| 68 | - '43200:43200' |
| 69 | restart: unless-stopped |
| 70 | volumes: |
| 71 | - /mnt/storage1/clover/Documents/Config/paperclover:/data |
| 72 | - /mnt/storage1/clover/Published:/published |
| 73 | |
| 74 | due to caching, images may need to be purged via `docker image rm {image} -f` |
| 75 | when an update is desired. some docker GUIs support force pulls, some are buggy. |
| 76 | |
| 77 | ## Contributions |
| 78 | |
| 79 | No contributions to `src` accepted, only `lib` and `framework`. |