path: root/README.md

# The Personal Website of Jakob L. Kreuze

This repository contains the source code for my personal website. In particular:

- The Haunt configuration
- The Guile API server implementing all of the website's dynamic functionality
- Org source files for all of the articles published on the website

The first two are under `haunt/`, and the last is under `org/`.

## Building

My website is, in theory, reproducible.
If you find that to not be the case, please let me know.

### Dependencies

- GNU Guile `>= 2.2.7`
- `haunt == 0.2.4`
- `guile-commonmark >= 0.1.2`
- `guile-gcrypt >= 0.3.0`
- `guile-gnutls >= 3.7.8`
  - In Gentoo, this is `net-libs/gnutls` with `USE=guile`
- `guile-json >= 4.7.2`
- `git`
- `pagefind = 0.12.0` (optional)

### Articles

Posts must be compiled before the website can be built (otherwise `haunt/posts` is unpopulated).

1. Install [ox-haunt](https://git.sr.ht/~jakob/ox-haunt).
2. `(setq ox-haunt-images-dir "./haunt/static/image/")`
2. For every `$article` in `ls org/*/*.org`,
  1. `M-x find-file RET $article`
  2. `M-x org-export-dispatch RET s h`

### Website

When all of the articles have been compiled, the website can be built by running `haunt build` in the `haunt/` directory.
When `haunt build` completes, the output will be at `haunt/site/`.
It may take a minute to fetch comments and webmentions.
The build process can be sped up by setting the `HAUNT_SKIP_COMMENTS` environment variable.

If using `pagefind`, the index will need to be build after running `haunt build`.
This can be done with `pagefind -s site/ -b _pagefind/`.

## Deploying

Recommend using `rsync -azv --delete --progress haunt/site/ [DESTINATION]` to update the static components on a remote.

The following OpenRC service will manage the API server:

```sh
#!/sbin/openrc-run

command="/usr/bin/guile"
command_args="-L ${JAKOB_API_DIR} ${JAKOB_API_DIR}/api.scm"
command_background=true
command_user="${JAKOB_API_USER}:${JAKOB_API_GROUP}"

pidfile="/run/${RC_SVCNAME}.pid"

depend() {
        need net
}
```

A sample `/etc/conf.d/jakob-api`:

```sh
JAKOB_API_DIR=/opt/jakob-api/
JAKOB_API_USER=jakob-api
JAKOB_API_GROUP=jakob-api
```

Ideas for a better name are appreciated 🙂

Before running the API server, the following databases will need to be created:

- `jakob_rsvp`
  - Initialized with `haunt/jakob/dynamic/schema-rsvp.sql`
- `jakob_gallery`
  - Initialized with `haunt/jakob/dynamic/schema-gallery.sql`
- `jakob_comments`
  - Initialized with `haunt/jakob/dynamic/schema-comments.sql`

### Dependencies

- GNU Guile `>= 2.2.7`
- `guile-gcrypt >= 0.3.0`
- `guile-json >= 4.7.2`
- `latex` and `dvipng`
- PostgreSQL `>= 14.0`

[squee](https://notabug.org/cwebber/guile-squee/) is currently vendored at `haunt/squee.scm`.

**TODO**: Should we package `squee` for Gentoo? Or use something more standard? I don't like vendoring code.

## API

Dynamic capabilities such as comments are implemented by the Guile API server (`haunt/api.scm`).
It is assumed that the web server proxies all requests matching a `/api` prefix to this server.
By default, the API server runs on port `8081`.

**TODO**: "By default" implies that it's configurable without modifying the source code. It should be configurable. That shouldn't be a hard lift.

### Comments

#### Proof of Work

Used to generate a transient proof-of-work challenge.

**URL** : `/api/challenge/proof-of-work`

**Method** : `GET`

**Auth required** : NO

**Data constraints** : NONE

##### Success Response

**Code** : `200 OK`

**Content example**

```json
{
    "hardness": 4,
    "challenge-id": 621,
    "nonce": "pXdoMbxdsmz7zK86MbyLF3qnDVBiPgIy9TY7Optnnow="
}
```

#### Normal Captcha

Used to generate a visual (math problem) captcha challenge.

**URL** : `/api/challenge/captcha`

**Method** : `GET`

**Auth required** : NO

**Data constraints** : NONE

##### Success Response

**Code** : `200 OK`

**Content example**

```json
{
    "challenge-id": 263,
    "image": "data:image/jpeg;charset=utf-8;base64,[...]"
}
```

#### Post Comment

Used to generate a visual (math problem) captcha challenge.

**URL** : `/api/comment`

**Method** : `POST`

**Auth required** : NO

**Data constraints**

Data should be `application/x-www-form-urlencoded`.

- `slug`: identifier for the post being commented on.
- `name`: author name for comment.
- `comment`: markdown string containing comment content.
- `captcha-id`: `challenge-id` for captcha challenge.
- `captcha`: solution for captcha with identifier `challenge-id`.
- `subject` (optional): subject string of comment.
- `email` (optional): email address of author.
- `url` (optional): homepage of author.

`captcha-id` and the captcha challenge can be generated with the "Proof of Work" or "Normal Captcha" endpoints.
If the captcha was created by the former endpoint, then the field names are `captcha-alt` and `captcha-alt-id`.

##### Success Response

**Code** : `307 Temporary Redirect`

**Content example**

```json
{
    "success": true,
}
```

### Other Endpoints

# License Information

## Haunt Sources and Guile API Server

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

## squee

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

## oneko.js

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## Static Assets

| Tor Logo   | haunt/static/tor.svg | The Tor Project, Inc. | [CC BY 3.0 US](https://creativecommons.org/licenses/by/3.0/us/deed.en) |
| I2P Logo   | haunt/static/i2p.svg | I2P Project           | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)              |