view release on metacpan or  search on metacpan

script/phoebe  view on Meta::CPAN

Titan is a companion protocol to Gemini: it allows clients to upload files to
Gemini sites, if servers allow this. On Phoebe, you can edit "raw" pages. That
is, at the bottom of a page you'll see a link to the "raw" page. If you follow
it, you'll see the page content as plain text. You can submit a changed version
of this text to the same URL using Titan. There is more information for
developers available on Community Wiki. L<https://communitywiki.org/wiki/Titan>

Known clients:

This repository comes with a Perl script called F<titan> to upload files.
L<https://alexschroeder.ch/cgit/phoebe/plain/titan>

I<Gemini Write> is an extension for the Emacs Gopher and Gemini client
I<Elpher>. L<https://alexschroeder.ch/cgit/gemini-write/>
L<https://thelambdalab.xyz/elpher/>

Gemini & Titan for Bash are two shell functions that allow you to download and
upload files. L<https://alexschroeder.ch/cgit/gemini-titan/about/>

=head2 Editing via the web

The Configuration section of the Phoebe space on I<The Transjovian Council> has
an example config on how to enable editing via the web.

=over

=item * L<https://transjovian.org:1965/phoebe/page/Configuration>

=item * L<gemini://transjovian.org/phoebe/page/Configuration>

=back

=head1 INSTALLATION

Using C<cpan>:

    cpan App::phoebe

Manual install:

    perl Makefile.PL
    make
    make install

=head2 Dependencies

If you are not using C<cpan> or C<cpanm> to install Phoebe, you'll need to
install the following dependencies:

=over

=item * L<Algorithm::Diff>, or C<libalgorithm-diff-xs-perl>

=item * L<File::ReadBackwards>, or C<libfile-readbackwards-perl>

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

=item * L<Mojolicious>, or C<libmojolicious-perl>

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

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

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

=item * L<Net::IDN::Encode>, or C<libnet-idn-encode-perl>

=item * L<Encode::Locale>, or C<libencode-locale-perl>

=back

I'm going to be using F<curl> and F<openssl> in the L</Quickstart> instructions,
so you'll need those tools as well. And finally, when people download their
data, the code calls C<tar> (available from packages with the same name on
Debian derived systems).

The F<update-readme.pl> script I use to generate F<README.md> also requires some
libraries:

=over

=item * L<Pod::Markdown>, or C<libpod-markdown-perl>

=item * L<Text::Slugify>, which has no Debian package, apparently 😭

=back

=head2 Quickstart

I'm going to assume that you're going to create a new user just to be safe.

    sudo adduser --disabled-login --disabled-password phoebe
    sudo su phoebe --shell=/bin/bash
    cd

Now you're in your home directory, F</home/phoebe>. We're going to install
things right here.

    cpan App::phoebe

Start Phoebe. It's going to prompt you for a hostname and create certificates
for you. If in doubt, answer C<localhost>. The certificate and a private key are
stored in the F<cert.pem> and F<key.pem> files, using elliptic curves, valid for
five years, without password protection.

    perl5/bin/phoebe

This starts the server in the foreground. If it aborts, see the
L</Troubleshooting> section below. If it runs, open a second terminal and test
it:

    perl5/bin/gemini gemini://localhost/

You should see a Gemini page starting with the following:

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

Success!! 😀 🚀🚀

script/phoebe  view on Meta::CPAN

following command tells Phoebe to serve both C<127.0.0.1> and C<localhost>
(the default is to just serve C<localhost>).

    phoebe --host=127.0.0.1 --host=localhost

Visit both at L<gemini://localhost/> and L<gemini://127.0.0.1/>, and create a
new page in each one, then examine the data directory F<wiki>. You'll see both
F<wiki/localhost> and F<wiki/127.0.0.1>.

If you're using more wiki spaces, you need to prefix them with the respective
hostname if you use more than one:

    phoebe --host=127.0.0.1 --host=localhost \
        --wiki_space=127.0.0.1/alex --wiki_space=localhost/berta

In this situation, you can visit L<gemini://127.0.0.1/>,
L<gemini://127.0.0.1/alex/>, L<gemini://localhost/>, and
L<gemini://localhost/berta/>, and they will all be different.

If this is confusing, remember that not using virtual hosting and not using
spaces is fine, too. 😀

=head2 Multiple Certificates

If you're using virtual hosting as discussed above, you have two options: you
can use one certificate for all your hostnames, or you can use different
certificates for the hosts. If you want to use just one certificate for all your
hosts, you don't need to do anything else. If you want to use different
certificates for different hosts, you have to specify them all on the command
line. Generally speaking, use C<--host> to specifiy one or more hosts, followed
by both C<--cert_file> and C<--key_file> to specifiy the certificate and key to
use for the hosts.

For example:

    phoebe --host=transjovian.org \
        --cert_file=/var/lib/dehydrated/certs/transjovian.org/cert.pem \
        --key_file=/var/lib/dehydrated/certs/transjovian.org/privkey.pem \
        --host=alexschroeder.ch \
        --cert_file=/var/lib/dehydrated/certs/alexschroeder.ch/cert.pem \
        --key_file=/var/lib/dehydrated/certs/alexschroeder.ch/privkey.pem

=head1 SEE ALSO

As you might have guessed, the system is easy to tinker with, if you know some
Perl. The Transjovian Council has a wiki space dedicated to Phoebe, and it
includes a section with more configuration examples.
See L<gemini://transjovian.org/> or L<https://transjovian.org:1965/>.

=head1 LICENSE

GNU Affero General Public License

=cut

use App::Phoebe qw($log $server host_regex handle_request get_ip_numbers);
use Modern::Perl '2018';
use File::Slurper qw(read_dir);
use Encode qw(decode);
use Encode::Locale;
use IO::Socket::SSL;
use Mojo::IOLoop;
use Getopt::Long;
use Pod::Text;
use utf8;
use B;

# Some of these need to be decoded (hostnames, pagenames).
GetOptions(
  $server,
  'help' => \&help,
  'log_level=s' => sub { $log->level($_[1]), },
  'log_file=s' => sub { $log->path($_[1]) },
  'cert_file=s' => \&host_setup,
  'key_file=s' => \&host_setup,
  'host=s' => \&host_setup,
  'port=i@', # same ports for all hosts!
  'wiki_dir=s',
  'wiki_space=s@' => \&utf8_list_item,
  'wiki_token=s@' => \&utf8_list_item,
  'wiki_page=s@' => \&utf8_list_item,
  'wiki_main_page=s' => \&utf8_item,
  'wiki_mime_type=s@',
  'wiki_page_size_limit=i')
    or die("Error in command line arguments\n");

sub utf8_list_item { my ($key, $value) = @_; push(@{$server->{$key}}, decode(locale => $value)) };
sub utf8_item { my ($key, $value) = @_; $server->{$key} = decode(locale => $value) };

{
  # use a block so that these variables stay local
  my ($cert_file, $key_file, @host);

  sub host_setup {
    my ($opt, $val) = @_;
    if ($opt eq 'host') {
      push @host, decode(locale => $val);
      return;
    };
    die "$val does not exist\n" unless -f $val;
    if ($opt eq 'cert_file') { $cert_file = $val }
    elsif ($opt eq 'key_file') { $key_file = $val }
    if ($cert_file and $key_file) {
      if (not @host) {
	$server->{host}->{'localhost'} = 1;
	$server->{cert_file}->{'localhost'} = $cert_file;
	$server->{key_file}->{'localhost'} = $key_file;
      }
      for (@host) {
	$server->{host}->{$_} = 1;
	$server->{cert_file}->{$_} = $cert_file;
	$server->{key_file}->{$_} = $key_file;
      }
      $cert_file = $key_file = undef;
      @host = ();
    }
  }

  # if, at the end, there is a left-over
  if ($cert_file or $key_file) {
    die "I must have both --key_file and --cert_file\n";