view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# Lupa Pona

Lupa Pona serves the local directory as a Gemini site.

It's a super simple server: it just serves the current directory. I use
[Phoebe](https://alexschroeder.ch/cgit/phoebe/about/) myself, for Gemini
hosting. It's a wiki, not just a file server.

Let me know if you want to use Lupa Pona in a multi-user or virtual-hosting
setup. All the necessary bits can be lifted from elsewhere. Right now, I'm just
using Lupa Pona to temporarily serve a local directory, as one might
occasionally use a few lines of Python to serve the local directory over the web
using `SimpleHTTPServer`.

**Table of Contents**

- [Limitations](#limitations)
- [Dependencies](#dependencies)
- [Quickstart](#quickstart)
- [Troubleshooting](#troubleshooting)
- [Options](#options)
- [Using systemd](#using-systemd)
- [Privacy](#privacy)

## Limitations

Currently, all files are served as `text/gemini; charset=UTF-8`.

## Dependencies

Perl libraries you need to install if you want to run Lupa Pona:

- [Mojo::Log](https://metacpan.org/pod/Mojo%3A%3ALog) and [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop), or `libmojolicious-perl`
- [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL), or `libio-socket-ssl-perl`
- [File::Slurper](https://metacpan.org/pod/File%3A%3ASlurper), or `libfile-slurper-perl`
- [Modern::Perl](https://metacpan.org/pod/Modern%3A%3APerl), or `libmodern-perl-perl`
- [URI::Escape](https://metacpan.org/pod/URI%3A%3AEscape), or `liburi-escape-xs-perl`

## Quickstart

Since Lupa Pona traffic is encrypted, we need to generate a certificate and a
key. When you start it for the first time, it will ask you for a hostname. Use
'localhost' if you don't know. You can also generate your own certificate, like
this, replacing `$hostname` with whatever you need:

    openssl req -new -x509 -newkey ec -subj "/CN=$hostname" \
    -pkeyopt ec_paramgen_curve:prime256v1 \
    -days 1825 -nodes -out cert.pem -keyout key.pem

This creates a certificate and a private key, both of them unencrypted, using
eliptic curves of a particular kind, valid for five years.

Start the server:

    lupa-pona

This starts the server in the foreground, for `gemini://localhost:1965`. If it
aborts, see the ["Troubleshooting"](#troubleshooting) section below. If it runs, open your
favourite Gemini client and test it, or open another terminal and test it:

    echo gemini://localhost \
      | openssl s_client --quiet --connect localhost:1965 2>/dev/null

You should see a Gemini page starting with the following:

    20 text/gemini; charset=UTF-8
    Welcome to Lupa Pona!

Success!! 😀 🚀🚀

## Troubleshooting

No trouble, yet!

## Options

These are the options Lupa Pona knows about:

- `--host` is the address to use; the default is 0.0.0.0, i.e. accepting
all connections (use this option if your machine is reachable via multiple
names, e.g. `alexschroeder.ch` and `emacswiki.org` and you just want want to
serve one of them)
- `--port` is the port to use; the default is 1965
- `--text_encoding` is the text encoding to use if you're not going to use
UTF-8 (consider adding support for [Encode::Guess](https://metacpan.org/pod/Encode%3A%3AGuess))
- `--log_level` is the log level to use (error, warn, info, debug, trace);
the default is `warn`
- `--cert_file` is the certificate file to use; the default is `cert.pem`
- `--key_file` is the key file to use; the default is `key.pem`

## Using systemd

Systemd is going to handle daemonisation for us. There's more documentation
[available