Skylab Setup

Note: these steps should still work, although the adduser script will ask you for a couple of new things. Until an updated setup guide becomes available, just know that my inbox is open if you need any support.

If you'd like to run skylab on a subpath, define `skylabPath` in `site_config.yaml` as the subpath without any slash at the beginning or end.

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: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 misfin server hostname: satch.xyz
Are you using a GMAP-style gembox? (true/false): true
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. Use GMAP if it's supported by your misfin server so that your read messages and tagged messages are synced across clients and checking for new messages is faster.

GmCapsule Configuration

Now everything is ready except my gemini server, GmCapsule. I start by dumping the whole example configuration 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.