←blog

How to host a Gemini capsule with Node and Nginx

Project Gemini is a text-based web protocol, like a mash-up of TLS + Gopher. It's hyped as a "Small Internet" with outer space imagery, where instead of web sites, we have Gemini capsules. Some people love it, some people hate it, but it's there and I think it's kind of cool. Anyway, recently I was playing with it and I realized there aren't good docs on how to get it running with nginx. So here's a quick howto:

1. Enable the nginx stream module

Depending on your environment, you may need to install the nginx stream module (eg. sudo apt install libnginx-mod-stream), or it might just need to be enabled. Assuming it's installed, simply add this to the very top of your nginx.conf to enable it (the path may be different in your environment): load_module /usr/lib/nginx/modules/ngx_stream_module.so;

2. Set up a stream directive in nginx.conf

This should be in your nginx.conf as a sibling to the http directive (i.e. not within the http directive or sites_available). Basically in your actual nginx.conf, put it underneath the http directive, like this:

http {

    ##
    # Basic Settings
    ##

    # ...
    # ... skipping ahead ...
    # ...

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

stream {

    ##
    # Configure ngx_stream_module for Gemini
    ##

    limit_conn_zone               $binary_remote_addr zone=addr:10m;
    limit_conn_log_level          warn;
    limit_conn                    addr 1;

    log_format                    basic '$remote_addr $upstream_addr [$time_local] '
                                  '$protocol $status $bytes_sent $bytes_received '
                                  '$session_time';
    access_log /var/log/nginx/gemini-access.log;
    error_log  /var/log/nginx/gemini-error.log;

    server {
        listen                    1965;
        proxy_buffer_size         16k;
        proxy_pass                'localhost:9003';  # set your actual port here
    }
}

3. Have a Gemini server listening on the local port specified in nginx.conf

This is really easy to setup using the gemini-server npm package, which is modeled after Express (but really you can use any Gemini server). Here's a simple Node.js server written in TypeScript:

import { readFileSync } from 'fs';
import gemini, { Request, Response, status } from 'gemini-server';

const PORT = 9003;

const app = gemini({
  cert: readFileSync('./cert.pem'),
  key: readFileSync('./privkey.pem'),
  titanEnabled: false
});

app.on('/', (_req: Request, res: Response) => {
  res.file('pages/index.gmi');
});

// Get the facts.
app.on('/facts/:file', (_req: Request, res: Response) => {
  try {
    res.file('pages/facts/' + _req.params.file);
  } catch(error) {
    res.error(40 as status, 'File not found.')
  }
})

app.listen(PORT, () => console.log('Gemini listening on ' + PORT + '...'));

Note that Gemini requires TLS, so you'll have to use a real cert.pem and privkey.pem, but if you already have these for your HTTPS domain you can reuse them. Otherwise check out this wiki to set up a cert.

That's it. Have fun!

• node
• gemini
• nginx