view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

If you allow uploads of binary files, these are stored separately from the
regular pages; the wiki doesn't keep old revisions of files around. If somebody
overwrites a file, the old revision is gone.

You definitely don't want random people uploading all sorts of images, videos
and binaries to your server. Make sure you set up those [tokens](#security)
using `--wiki_token`!

# Notes

## Security

The server uses "access tokens" to check whether people are allowed to edit
files. You could also call them "passwords", if you want. They aren't associated
with a username. You set them using the `--wiki_token` option. By default, the
only password is "hello". That's why the Titan command above contained
"token=hello". 😊

If you're going to check up on your wiki often (daily!), you could just tell
people about the token on a page of your wiki. Spammers would at least have to
read the instructions and in my experience the hardly ever do.

You could also create a separate password for every contributor and when they
leave the project, you just remove the token from the options and restart
Phoebe. They will no longer be able to edit the site.

## Privacy

The server only actively logs changes to pages. It calculates a "code" for every
contribution: it is a four digit octal code. The idea is that you could colour
every digit using one of the eight standard terminal colours and thus get little
four-coloured flags.

This allows you to make a pretty good guess about edits made by the same person,
without telling you their IP numbers.

The code is computed as follows: the IP numbers is turned into a 32bit number
using a hash function, converted to octal, and the first four digits are the
code. Thus all possible IP numbers are mapped into 8⁴=4096 codes.

If you increase the log level, the server will produce more output, including
information about the connections happening, like `2020/06/29-15:35:59 CONNECT
SSL Peer: "[::1]:52730" Local: "[::1]:1965"` and the like (in this case `::1`
is my local address so that isn't too useful but it could also be your visitor's
IP numbers, in which case you will need to tell them about it using in order to
comply with the
[GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation).

# Example

Here's an example for how to start Phoebe. It listens on `localhost` port 1965,
adds the "Welcome" and the "About" page to the main menu, and allows editing
using one of two tokens.

    phoebe \
      --wiki_token=Elrond \
      --wiki_token=Thranduil \
      --wiki_page=Welcome \
      --wiki_page=About

Here's what my `phoebe.service` file actually looks like:

    [Unit]
    Description=Phoebe
    After=network.target
    [Install]
    WantedBy=multi-user.target
    [Service]
    Type=simple
    WorkingDirectory=/home/alex/farm
    Restart=always
    User=alex
    Group=ssl-cert
    MemoryMax=100M
    MemoryHigh=90M
    ExecStart=/home/alex/src/phoebe/script/phoebe \
     --port=1965 \
     --log_level=debug \
     --wiki_dir=/home/alex/phoebe \
     --host=transjovian.org \
     --cert_file=/var/lib/dehydrated/certs/transjovian.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/transjovian.org/privkey.pem \
     --host=toki.transjovian.org \
     --cert_file=/var/lib/dehydrated/certs/transjovian.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/transjovian.org/privkey.pem \
     --host=vault.transjovian.org \
     --cert_file=/var/lib/dehydrated/certs/transjovian.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/transjovian.org/privkey.pem \
     --host=communitywiki.org \
     --cert_file=/var/lib/dehydrated/certs/communitywiki.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/communitywiki.org/privkey.pem \
     --host=alexschroeder.ch \
     --cert_file=/var/lib/dehydrated/certs/alexschroeder.ch/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/alexschroeder.ch/privkey.pem \
     --host=next.oddmuse.org \
     --cert_file=/var/lib/dehydrated/certs/oddmuse.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/oddmuse.org/privkey.pem \
     --host=emacswiki.org \
     --cert_file=/var/lib/dehydrated/certs/emacswiki.org/fullchain.pem \
     --key_file=/var/lib/dehydrated/certs/emacswiki.org/privkey.pem \
     --wiki_main_page=Welcome \
     --wiki_page=About \
     --wiki_mime_type=image/png \
     --wiki_mime_type=image/jpeg \
     --wiki_mime_type=audio/mpeg \
     --wiki_space=transjovian.org/test \
     --wiki_space=transjovian.org/phoebe \
     --wiki_space=transjovian.org/anthe \
     --wiki_space=transjovian.org/gemini \
     --wiki_space=transjovian.org/titan

## Certificates and File Permission

In the example above, I'm using certificates I get from Let's Encrypt. Thus, the
regular website served on port 443 and the Phoebe website on port 1965 use the
same certificates. My problem is that for the regular website, Apache can read
the certificates, but in the setup above Phoebe runs as the user `alex` and
cannot access the certificates. My solution is to use the group `ssl-cert`.
This is the group that already has read access to `/etc/ssl/private` on my
system. I granted the following permissions:

README.md  view on Meta::CPAN

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

# Ijirait

This is a command-line client for Ijirait, a Gemini-based MUSH that can be run
by Phoebe. See [App::Phoebe::Ijirait](https://metacpan.org/pod/App%3A%3APhoebe%3A%3AIjirait).

First, generate your client certificate for as many or as few days as you like:

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

Then start this program to play:

    ijirait --cert=cert.pem --key=key.pem \
      --url=gemini://campaignwiki.org/play/ijirait

You can also use it to stream, i.e. get notified of events in real time:

    ijirait --cert=cert.pem --key=key.pem --stream \
      --url=gemini://campaignwiki.org/play/ijirait/stream

Here are the Debian package names to satisfy the dependencies. Use `cpan` or
`cpanm` to install them.

- [Modern::Perl](https://metacpan.org/pod/Modern%3A%3APerl) from `libmodern-perl-perl`
- [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop) from `libmojolicious-perl`
- [Term::ReadLine::Gnu](https://metacpan.org/pod/Term%3A%3AReadLine%3A%3AGnu) from `libterm-readline-gnu-perl`
- [URI::Escape::XS](https://metacpan.org/pod/URI%3A%3AEscape%3A%3AXS) from `liburi-escape-xs-perl`
- [Encode::Locale](https://metacpan.org/pod/Encode%3A%3ALocale) from `libencode-locale-perl`
- [Text::Wrapper](https://metacpan.org/pod/Text%3A%3AWrapper) from `libtext-wrapper-perl`

# phoebe-ctl

This script helps you maintain your Phoebe installation.

- **--wiki\_dir=**_DIR_

    This the wiki data directory to use; the default is either the value of the
    `GEMINI_WIKI_DATA_DIR` environment variable, or the `./wiki` subdirectory. Use
    it to specify a space, too.

- **--log=**_NUMBER_

    This is the log level to use. 1 only prints errors; 2 also prints warnings (this
    is the default); 3 prints any kind of information; 4 prints all sorts of info
    the developer wanted to see as they were fixing bugs.

## Commands

**phoebe-ctl help**

This is what you're reading right now.

**phoebe-ctl update-changes**

This command looks at all the pages in the `page` directory and generates new
entries for your changes log into `changes.log`.

**phoebe-ctl erase-page**

This command removes pages from the `page` directory, removes all the kept
revisions in the `keep` directory, and all the mentions in the `change.log`.
Use this if spammers and vandals created page names you want to eliminate.

**phoebe-ctl html-export** \[**--source=**`subdirectory` ...\]
\[**--target=**`directory`\] \[**--no-extension**\]

This command converts all the pages in the subdirectories provided to HTML and
writes the HTML files into the target directory. The subdirectories must exist
inside your wiki data directory. The default wiki data directory is `wiki` and
the default source subdirectory is undefined, so the actual files to be
processed are `wiki/page/*.gmi`; if you're using virtual hosting, the
subdirectory might be your host name; if you're using spaces, those need to be
appended as well.

Example:

    phoebe-ctl html-export --wiki_dir=/home/alex/phoebe \
      --source=transjovian.org \
      --source=transjovian.org/phoebe \
      --source=transjovian.org/gemini \
      --source=transjovian.org/titan \
      --target=/home/alex/transjovian.org

This will create HTML files in `/home/alex/transjovian.org`,
`/home/alex/transjovian.org/phoebe`, `/home/alex/transjovian.org/gemini`, and
`/home/alex/transjovian.org/titan`.

Note that the _links_ in these HTML files do not include the `.html` extension
(e.g. `/test`), so this relies on your web server doing the right thing: if a
visitor requests `/test` the web server must serve `/test.html`. If that
doesn't work, perhaps using `--no-extension` is your best bet: the HTML files
will be written without the `.html` extension. This should also work for local
browsing, although it does look strange, all those pages with the `.html`
extension.

# Spartan

**titan** \[**--help**\] \[**--verbose**\] _URL_

This is a very simple test client. All it does is print the response. The header
is printed to standard error so the rest can be redirected to get just the
content.

    spartan URL

Usage:

    spartan spartan://mozz.us/

Send some text:

    echo "Hello $USER!" | script/spartan spartan://mozz.us/echo

# Titan