diff options
Diffstat (limited to 'content/theses/self-sufficiency/gemini.md')
| -rw-r--r-- | content/theses/self-sufficiency/gemini.md | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/content/theses/self-sufficiency/gemini.md b/content/theses/self-sufficiency/gemini.md new file mode 100644 index 0000000..f43045d --- /dev/null +++ b/content/theses/self-sufficiency/gemini.md @@ -0,0 +1,138 @@ +--- +title: gemini:// +weight: 6 +--- + +Here I explain how to set up a `gemini://` server, which is known as a `capsule`. + +If you don't know what `gemini://` is, essentially it is a text-only `https://` alternative. + +It allows you to browse text only feeds, and is a welcome escape from ads and javascript and bloat. + +{{% hint info %}} +Gemini in general does not support anything except for pure text. There is no CSS, no JavaScript, nothing, except for text and sometimes images (but not in-line, you have to click them). +It is considered an alternative to the web, seen as "better/superior" because it forces minimalism, however it is a bad comparison. +The issue with modern web is the invasiveness, not the CSS or JS (although JS sucks); in this regard, I prefer my site being static and served over the web where I can use CSS, than gemini, where in the name of "minimalism" I have to give up expressive liberty. +Be that as it may, it's nice to have options, plus the minimalism might appeal to some, or might enable a "rehab" sentiment. +{{% /hint %}} + +## setup +The nixos configuration is a bit more difficult because of how simple `gemini` servers are. This simplicity means that we need to set up our own user, open the port (since `nginx` is a ***web*** server, it can't work with `gemini://`), and set up autosync so we don't need to sync files manually with git. + +### specs +There are many servers to host; the `gemini://` protocol is extremely simple, and so servers can take ~200-500 lines of code, and are *extremely* lightweight. + +This guide sets up `agate` since it's a service in `nixos`. + +We start by making a folder `gemini` and `gemini/default.nix` +```sh +$ mkdir gemini && touch gemini/default.nix +``` +(or use the file explorer of your choice) + +### nix declaration +Open `gemini/default.nix` in any text editor, and copy the following + +```nix +{ config, pkgs, lib, ... }: +{ + services.agate = { + enable = true; + + hostnames = [ "<YOUR-DOMAIN>" ]; + addresses = [ "0.0.0.0:1965" ]; + language = "en"; + contentDir = "/srv/gemini"; + }; + + networking.firewall.allowedTCPPorts = [ 1965 ]; + + users = { + groups.agate = { }; + users = { + agate = { + isSystemUser = true; + description = "gemini user"; + group = "agate"; + home = "/srv/gemini"; + createHome = true; + shell = "${pkgs.git}/bin/git-shell"; + }; + }; + }; + + systemd = { + # set service + services."gemini" = { + description = "Update Gemini site from repo"; + + script = '' + if [ -d /srv/gemini/.git ]; then + ${pkgs.git}/bin/git -C /srv/gemini pull + else + ${pkgs.git}/bin/git clone https://<YOUR-GEMINI-REPOSITORY> /srv/gemini + fi + ''; + + serviceConfig = { + Type = "oneshot"; + User = "agate"; + }; + }; + + timers."gemini" = { + description = "Hourly Gemini-site update"; + wantedBy = [ "timers.target" ]; + + timerConfig = { + OnCalendar = "hourly"; + Persistent = true; + }; + }; + }; +} +``` +Then to enable it, just include it in the server config file: +```nix + imports = [ + # ... other services + ./gemini + # ... other services + ]; +``` +and you're done. +{{% hint warning %}} +Make sure to replace `<YOUR-GEMINI-REPO>` with your actual gemini repo above +{{% /hint %}} + +Let's break the config file down. + +### explanation +1) We declare the `agate` service as enabled. +2) We define the hostname for the `gemini://` network, set the address(es) to serve from, and declare the language we will be writing in. Finally we declare the content directory +3) We open port 1965 to the internet +4) We declare a group `agate` +5) We declare a user `agate`, in group `agate`, with the home folder being at `srv/gemini`, having access only to the git shell, for security. +6) We declare a `systemd` service, `gemini`, that checks if `/srv/gemini` is a git repo; if it isn't it `git clone` at a specified repository, if it is, it runs `git pull`. This service is set to run once (not continuously), and to be run by user `agate` +7) We declare a timer that runs the `gemini` service we just declared, once per hour. This automates the setup + + +### adding content +In order to add content to your new capsule, simply go to the `content/` folder and start writing. + +By default `gemini://` serves the `index.gmi` at `<YOUR-DOMAIN>/`, so make that file first. + +{{% hint info %}} +`.gmi` is the markup flavour that gemini reads/serves. +It is a stripped down version of markdown (`.md` files). +[You can find out more about it here](https://geminiprotocol.net/docs/gemtext.gmi) +{{% /hint %}} + +Since servers simply serve `.gmi` files, you don't need to do any update/reload or anything. It happens automatically. + +Personally, I use `git` to keep files synced (as in, the content folder is a git repo). + +## client +In order to browse `gemini://` you need a dedicated client. + +Use [`Lagrange`](https://gmi.skyjake.fi/lagrange/). |