You are viewing the official README for the Hackersphere Capsule Engine, or HCE for short. This file contains documentation you'll need if you're a sysadmin wishing to create a new Gemini capsule with the HCE. If that's *not* you and you're a user wishing to learn how to create content on your subcapsule of hackersphere.space, read our user manual page instead:
The HCE was written on GNU/Linux for a virtual machine that has 1 x86-64 CPU core, 2GB RAM, and 25GB SSD. Honestly, you could probably get away with less than that. The same installation procedures can probably be followed for any Unix-like OS that uses systemd.
There aren't many. Basically, you just need to be able to run npm and NodeJS. The package.json file doesn't have many dependencies in it and can be read on the Web here:
https://git.sr.ht/~willowf/hackersphere/tree/main/item/package.json
You'll also need systemd to run the server as a daemon using the hackersphere.service file I wrote.
The user under which the server daemon runs will need permission to access any ports you want to use, i.e. port 443 for HTTPS and 1965 for Gemini. You'll also need an SSL certkey pair for TLS.
Clone this repository:
https://git.sr.ht/~willowf/hackersphere
Navigate to the repository's root directory and do `npm install`.
The file cfg/server.json contains server configuration info. You'll likely want to change these values:
There are also some optional parameters, which have default values if not specified:
The file gemini-static/index.gmi is the capsule's index page (unless staticFilesDirectory in cfg/server.json doesn't point to gemini-static/). Edit it to be about your capsule instead of ours.
Navigate to the git repository and do `npm run compile`. Note: if you want to change the configuration in cfg/server.json, it is NOT necessary to recompile the program, but it IS necessary to restart it. If it's running as a daemon under systemd you can do this with `sudo systemctl restart hackersphere`.
Copy the file hackersphere.service into /etc/systemd/system or wherever your service unit files are kept. Edit the `User` parameter to the user under which you want the server to run (ideally not root) and edit the `WorkingDirectory` parameter to the path to the git repository. Save and exit, then do `sudo systemctl enable hackersphere` and `sudo systemctl start hackersphere` to start running the server.
The HCE is designed with the expectation that users will login to the host via SSH, and add content to their subcapsules by creating and editing gemtext files in their personal subdirectories of gemini-static. However, the HCE does not have any built-in functionality relating to user accounts as such. The idea is that the system of users and groups built-in to Unix should be perfectly adequate for the engine's envisioned use case. I would suggest that you only create users for people you trust, and that you use user and group permissions to prevent users from accidentally or intentionally messing with other users' files.
That said, the HCE is agnostic to any concept of a "user account", so you are free to use any system you want for that. If you're the only user, you can just put anything you want in the static files directory. You could also extend the system to implement your own user management scheme; it's not mandatory that your users should have their own Unix user account, nor that content be updated by logging in with SSH. The HCE doesn't care, it just serves whatever files are in the static files directory.
A substitution rule is a JSON file named `subrule.json`, containing information used by the HCE's template processor. A substitution rule is applied to the directory in which it resides, but not to any subdirectories thereof. If no substitution rule is present in a given directory, then no template processing will be done to the files in that directory. A substitution rule does not modify any files; it only affects the content served to the client.
A substitution rule's syntax is as follows:
{
"@@EXAMPLE@@": "text to replace the template variable EXAMPLE with",
"@@ANOTHER-EXAMPLE@@": "text to replace the template variable ANOTHER-EXAMPLE with"
}
A template variable must have the following syntax:
When a substitution rule is applied to some content, the template processor will replace all instances of template variables in the text with the expansions defined in the rule, and serve the result to the client. For example, if an HCE capsule at the domain "foo.example" has a subdirectory of its static files directory called "example", which contains the following in subrule.json:
{
"@@FAVORITE-COLOR@@": "red"
}
and the following in page.gmi:
My favorite color is @@FAVORITE-COLOR@@, but I like other colors too :)
then the URI gemini://foo.example/example/page.gmi will return the following content:
My favorite color is red, but I like other colors too :)
The HCE is a Node application written in Typescript. It serves static files from a directory specified in cfg/server.json. When a client sends a Gemini request, it will do these things:
When a client makes an HTTPS request, the HCE will do the same thing, except that the content will be converted to HTML after template processing.
The HCE is programmed to shut down gracefully when it receives SIGTERM, SIGINT, or SIGQUIT. One nice consequence of this is that it's safe to stop the server with Ctrl+C when running it in an interactive shell.