💾 Archived View for satch.xyz › skylab › setup.gmi captured on 2024-08-18 at 17:19:50. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Skylab Setup

TLDR

Use git clone and go build to make the executable
Configure your gemini server
Make the correct directory structure and write your config files using the skylab-tool.sh script

Example Skylab directory structure

Here's how I set up my Skylab instance for the first time:

Get GmCapsule ready with a new cert:

$ openssl req -x509 -new -sha256 -days 9999 -nodes -key key.pem     -out host.cert -subj "/CN=satch.xyz" -addext     "subjectAltName=DNS:satch.xyz,DNS:bensonplace.blue,DNS:blube.club,DNS:stavaser.o0o0o0o0o0o0o.ooo,DNS:$(printf '%s' 'ooo.o0o0o0o0o0o0o.o0o0o0o0o0o0o.ooo' | openssl enc -base64), DNS:benson.place, DNS:mail.satch.xyz"

$ mv host.cert cert.pem

Then I restarted GmCapsule and checked to make sure that everything was working. I went to gemini://mail.satch.xyz and got "50 Permanent failure" but a valid certificate, so that's great.

Clone git repository and run setup scripts

$ git clone https://git.sr.ht/~satchlj/skylab

That was 3.04 MiB in total.

$ cd skylab
$ chmod +x skylab-tool.sh
$ ./skylab-tool.sh
Usage: ./skylab-tool.sh [--init]
Options:
  --init    Perform initialization setup (create directories, etc.)
  --adduser Add a new user
$ ./skylab-tool.sh --init
Enter directory path for Skylab. (default: current directory): ~/gmcapsule/skylab

Here I break and go make that directory before continuing:

cd ~/gmcapsule/ && mkdir skylab

Back to the script:

$ ./skylab-tool.sh --init
Enter directory path for Skylab. (default: current directory): ~/gmcapsule/skylab
Enter hostname: mail.satch.xyz
Initialization complete.

I can now check that everything worked:

$ ls ~/gmcapsule/skylab/
mail.satch.xyz  users  users.yaml

Great. I will now build the cgi executable file using `go build` to the output directory I just created.

$ go build -o ~/gmcapsule/skylab/mail.satch.xyz/
go: downloading gopkg.in/yaml.v2 v2.4.0
go: downloading gitlab.com/clseibold/misfin-server v0.0.0-20240111212826-2812aea0d21e

$ ls ~/gmcapsule/skylab/mail.satch.xyz/
skylab

It's also totally fine to just run `go build` and then `mv` the file to the place it needs to be.

Next, I will create a user (myself):

$ ./skylab-tool.sh --adduser
Enter username: satya
Enter directory path for Skylab. This directory should already exist and should contain 'users' and 'users.yaml': ~/gmcapsule/skylab
Enter path to misfin keypair PEM file (this script will copy it): ^C

I've forgotten where my keypair is kept, so I stop the script and go check. I'm putting it in my home directory for now to make this easy.

$ ./skylab-tool.sh --adduser
Enter username: satya
Enter directory path for Skylab. This directory should already exist and should contain 'users' and 'users.yaml': ~/gmcapsule/skylab
Enter path to misfin keypair PEM file (this script will copy it): ~/cert.pem
Enter GeminiFetchAddress: gemini://satch.xyz:1958/fetch
Enter AutoFetch (true/false): false
Enter Timezone: America/New_York
User satya setup complete.

AutoFetch to false just means I don't download and parse my gembox file every time I reload the page while using Skylab.

GmCapsule Configuration

Now everything is ready except my gemini server, GmCapsule. I start by dumping the whole example file into the .gmcapsulerc which I already have.

cat configurations/gmcapsulerc.example.ini >> ~/.gmcapsulerc

Then I go in there and edit out the redudant bits like [server], [static], [cgi], [titan] and things like that. Basically I have my old configuration and then the [DEFAULT] block onwards from the example file. I'm making sure to add "mail.satch.xyz" to my hosts list. I change the default values to the appropriate ones, and I can leave everything else:

[DEFAULT]
skylab_host = mail.satch.xyz
skylab_cwd = ./gmcapsule/skylab/mail.satch.xyz

Now I restart GmCapsule!

gemini@satch:~$ gmcapsuled
GmCapsule v0.6.1
Configuration: /home/gemini/.gmcapsulerc
Init: Rewriter
Init: Git Repository Viewer
Init: CGI programs
  gemini://mail.satch.xyz/ -> ['./skylab']
  gemini://mail.satch.xyz/* -> ['./skylab']
Init: Static files
  Content directory: /home/gemini/gmcapsule/static/{hostname}
Opening port 1965...
Server started on port 1965
5 parser(s) and 2 handler(s) started

It's working!

I go to gemini://mail.satch.xyz and I see a login link, which I click. It prompts me to activate a client certificate, and so I do (the same PEM file which I provided during the setup, signed by my server admin cert). My inbox loads but it's empty since I have AutoFetch set to `false`, so I click on 🔃 Check for New Mail and my mail is there at the top of the screen!

To update

Whenever I want to update Skylab, I run `git pull` and then `go build -o ~/gmcapsule/skylab/mail.satch.xyz/` and that's it! Always check the skylab mailinglist before updating to see if there's anything important to know. You should probably just subscribe!

Skylab Mailinglist Archive

Optional configuration in site_config

To run Skylab on a subdirectory, edit site_config.yaml:

SkylabPath: ~skylab

A tilde path is recommended as navigation to the homepage will be easier on gemini clients like Lagrange which treat these paths specially. In order to simplify the UI, links to "Home" have been omitted in favor of built in client tools for navigation to the root directory. If you use a tilde path, some clients will recognize it as the Skylab root.

To show sensitive configuration options on the frontend, edit site_config.yaml:

ExposeSettings: true

This is not recommended for multi-user Skylab instances where users are not highly trusted.