view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

affected, since these comments use Gemini instead of Titan. Thus, people can
still leave comments.

If you allow editing via the web using [App::Phoebe::WebEdit](https://metacpan.org/pod/App%3A%3APhoebe%3A%3AWebEdit), then those are
not affected, since these edits use HTTP instead of Titan. Thus, people can
still edit pages. **This is probably not what you want!**

# App::Phoebe::Spartan

This extension serves your Gemini pages via the Spartan protocol and generates a
few automatic pages for you, such as the main page.

**Warning!** If you install this code, anybody can write to your site using the
Spartan protocol. There is no token being checked.

To configure, you need to specify the Spartan port(s) in your Phoebe config
file. The default port is 300. This is a priviledge port. Thus, you either need
to grant Perl the permission to listen on a priviledged port, or you need to run
Phoebe as a super user. Both are potential security risk, but the first option
is much less of a problem, I think.

If you want to try this, run the following as root:

    setcap 'cap_net_bind_service=+ep' $(which perl)

Verify it:

    getcap $(which perl)

If you want to undo this:

    setcap -r $(which perl)

Once you do that, no further configuration is necessary. Just add the following
to your `config` file:

    use App::Phoebe::Spartan;

The alternative is to use a port number above 1024. Here's a way to do that:

    package App::Phoebe::Spartan;
    our $spartan_port = 7000; # listen on port 7000
    use App::Phoebe::Spartan;

If you don't do any of the above, you'll get a permission error on startup:
"Mojo::Reactor::Poll: Timer failed: Can't create listen socket: Permission
denied…"

# App::Phoebe::SpeedBump

We want to block crawlers that are too fast or that don’t follow the
instructions in robots.txt. We do this by keeping a list of recent visitors: for
every IP number, we remember the timestamps of their last visits. If they make
more than 30 requests in 60s, we block them for an ever increasing amount of
seconds, starting with 60s and doubling every time this happens.

For every IP number, Phoebe also records whether the last 30 requests were
“suspicious” or not. A suspicious request is a request that is “disallowed” for
bots according to “robots.txt” (more or less). If 10 requests or more of the
last 30 requests in the last 60 seconds are suspicious, the IP number is
blocked.

When an IP number is blocked, it is blocked for 60s, and there’s a 120s
probation time. When you’re blocked, Phoebe responds with a “44” response. This
means: slow down!

If the IP number is unblocked but gives cause for another block in the probation
time, it is blocked again and the blocking time is doubled: the IP is blocked
for 120s and there’s 240s probation time. And if it happens again, it is doubled
again.

There is no configuration required, but adding a known fingerprint is suggested.
The `/do/speed-bump` URL shows you more information, if you have a client
certificate with a known fingerprint.

The exact number of requests and the length of the time window (in seconds) can
be changed in the `config` file, too.

    Here’s one way to do all that:

       package App::Phoebe;
       our @known_fingerprints = qw(
         sha256$0ba6ba61da1385890f611439590f2f0758760708d1375859b2184dcd8f855a00);
       package App::Phoebe::SpeedBump;
       our $speed_bump_requests = 20;
       our $speed_bump_window = 20;
       use App::Phoebe::SpeedBump;

Here’s how to get the fingerprint from a certificate named `client-cert.pem`:

    openssl x509 -in client-cert.pem -noout -sha256 -fingerprint \
    | sed -e 's/://g' -e 's/SHA256 Fingerprint=/sha256$/' \
    | tr [:upper:] [:lower:]

This should give you the fingerprint in the correct format to add to the list
above.

# App::Phoebe::StaticFiles

Serving static files... Sometimes it's just easier. All the static files are
served from `/do/static`, without regard to wiki spaces. You need to define
routes that map a path to your filesystem.

    package App::Phoebe::StaticFiles;
    our %routes = (
      "zürich" => "/home/alex/Pictures/2020/Zürich",
      "amaryllis" => "/home/alex/Pictures/2021/Amaryllis", );
    use App::Phoebe::StaticFiles;

The setup does not allow recursive traversal of the file system.

You still need to add a link to `/do/static` somewhere in your wiki.

# App::Phoebe::TokiPona

This extension adds rendering of Toki Pona glyphs to the web output of your
site. For this to work, you need to download the WOFF file from the Linja Pona
4.2 repository and put it into your wiki directory.

[https://github.com/janSame/linja-pona/](https://github.com/janSame/linja-pona/)

No further configuration is necessary. Simply add it to your `config` file:

    use App::Phoebe::TokiPona;

# App::Phoebe::Web

Phoebe doesn’t have to live behind another web server like Apache or nginx. It