view release on metacpan or  search on metacpan

script/lupa-pona  view on Meta::CPAN

#!/usr/bin/env perl
# Copyright (C) 2017–2021  Alex Schroeder <alex@gnu.org>

# This program is free software: you can redistribute it and/or modify it under
# the terms of the GNU Affero General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option) any
# later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
# details.
#
# You should have received a copy of the GNU Affero General Public License along
# with this program. If not, see <https://www.gnu.org/licenses/>.

=encoding utf8

=head1 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
L<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 C<SimpleHTTPServer>.

=head2 Limitations

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

=head2 Dependencies

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

=over

=item L<Mojo::Log> and L<Mojo::IOLoop>, or C<libmojolicious-perl>

=item L<IO::Socket::SSL>, or C<libio-socket-ssl-perl>

=item L<File::Slurper>, or C<libfile-slurper-perl>

=item L<Modern::Perl>, or C<libmodern-perl-perl>

=item L<URI::Escape>, or C<liburi-escape-xs-perl>

=back

=head2 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 C<$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 C<gemini://localhost:1965>. If it
aborts, see the L</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!! 😀 🚀🚀

=head2 Troubleshooting

No trouble, yet!

=head2 Options

These are the options Lupa Pona knows about:

=over

=item C<--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. C<alexschroeder.ch> and C<emacswiki.org> and you just want want to
serve one of them)

=item C<--port> is the port to use; the default is 1965

=item C<--text_encoding> is the text encoding to use if you're not going to use
UTF-8 (consider adding support for L<Encode::Guess>)