view release on metacpan or  search on metacpan

script/phoebe  view on Meta::CPAN

A line starting with "#", "##", or "###", followed by a space and some text is a
heading.

    ## License
    The GNU Affero General Public License.

A line starting with "*", followed by a space and some text is a list item.

    * one item
    * another item

A line starting with ">", followed by a space and some text is a quote.

    The monologue at the end is fantastic, with the city lights and the rain.
    > I have seen things you people would not believe.

=head1 SECURITY

It might be best if you had a separate user for Phoebe:

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

Now you're in the new home directory, F</home/phoebe>. If you start C<phoebe>
here, your wiki directory will be F</home/phoebe/wiki>. If you haven't installed
L<App::Phoebe> for all your users, you will have to install it again.

    cpan App::Phoebe

The Perl files are stored in F</home/phoebe/perl5>.

=head1 QUICKSTART

Start Phoebe.

    phoebe

When you run it for the first time, Phoebe is 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.

    Do you want to create them right now?
    The certificate uses eliptic curves and is valid for five years.
    If so, please provide your hostname (e.g. localhost).
    If not, just press Enter.
    localhost
    openssl req -new -x509 -newkey ec -subj "/CN=localhost" -pkeyopt ec_paramgen_curve:prime256v1 -days 1825 -nodes -out cert.pem -keyout key.pem
    Generating an EC private key
    writing new private key to 'key.pem'
    -----

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

    gemini gemini://localhost/

You should see a Gemini page starting with the following:

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

Success!! 😀 🚀🚀

Let's create a new page using the Titan protocol, from the command line:

    echo "Welcome to the wiki!" > test.txt
    echo "Please be kind." >> test.txt
    titan --url=titan://localhost/raw/Welcome --token=hello test.txt

You should get a nice redirect message.

    30 gemini://localhost:1965/page/Welcome

You can check the page:

    gemini gemini://localhost:1965/page/Welcome

You should get back a page that starts as follows:

    20 text/gemini; charset=UTF-8
    Welcome to the wiki!
    Please be kind.

Yay! 😁🎉 🚀🚀

If you have a bunch of Gemtext files in a directory, you can upload them all in
one go:

    titan --url=titan://localhost/ --token=hello *.gmi

=head1 CERTIFICATES

If you want to generate your own certificates, here's how you would generate a
certificate for two domains (you can add as many as you need), and a common name
of "Phoebe" (use whatever you want).

    openssl req -new -x509 -newkey ec \
    -pkeyopt ec_paramgen_curve:prime256v1 \
    -subj "/CN=Phoebe" \
    -addext "subjectAltName=DNS:localhost,DNS:phoebe.local" \
    -days 1825 -nodes -out cert.pem -keyout key.pem

=head1 IMAGE UPLOADS

OK, how do image uploads work? First, we need to specify which MIME types Phoebe
accepts. The files are going to be served back with that MIME type, so even if
somebody uploads an executable and claim it's an image, other people's clients
will treat it as an image instead of executing it (one hopes!) – so let's start
with a list of common MIME types.

=over

=item * C<image/jpeg> is for photos (usually with the C<jpg> extension)

=item * C<image/png> is for graphics (usually with the C<png> extension)

=item * C<audio/mpeg> is for sound (usually with the C<mp3> extension)

=back

Let's continue using the setup we used for the L</QUICKSTART> section. Restart
the server and allow photos:

    phoebe --wiki_mime_type=image/jpeg

Upload the image using the C<titan> script:

    titan --url=titan://localhost:1965/jupiter.jpg \
      --token=hello Pictures/Planets/Juno.jpg

You should get back a redirect to the uploaded image:

    30 gemini://localhost:1965/file/jupiter.jpg

How did the C<titan> script know the MIME-type to use for the upload? If you
don't specify a MIME-type using C<--mime>, the C<file> utility is called to
guess the MIME type of the file.

Test it: