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

Building

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

Dependencies

GNU Emacs >= 29.3
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)

Website

You will need the binary assets for this website, which can be obtained with this one-liner: curl -LO https://jakob.space/annex.tar.gz | tar zxf -. When all of the dependencies have been installed, the website can be built by running haunt build from the directory this README file resides in. When haunt build completes, the output will be at 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. It may also take a few minutes to compile all of the posts using Emacs, but unless explicitly disabled, the results are cached. Hence, subsequent builds will not take as long.

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 site/ [DESTINATION] to update the static components on a remote.

The following OpenRC service will manage the API server:

#!/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:

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 jakob/dynamic/schema-rsvp.sql
jakob_gallery
Initialized with jakob/dynamic/schema-gallery.sql
jakob_comments
Initialized with 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 is currently vendored at 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 (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

{
    "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

{
    "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

{
    "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