Illuminant
==========

An ActivityPub server with an NNTP interface.

Usage
-----

To use Illuminant (after installation, see below), you connect a
newsreader to your instance - remember to configure it to login with
user and password.

Note that there is no web interface for Illuminant - only a basic
frontpage displaying the users most recently encountered.

The newsgroups are organised like this:

 - fediverse.timeline  -- everything on the instance
 - fediverse.home      -- your own posts
 - fediverse.like      -- your likes (favourites, stars)
 - fediverse.repeat    -- your repeats (boosts, re-posts)
 - fediverse.profile   -- your profile
 - fediverse.following -- one article for each user you follow
 - fediverse.followers -- one article for each user following you
 - fediverse.@someuser@somedomain   -- articles from @someuser@somedomain
 - fediverse.@otheruser@otherdomain -- articles from @otheruser@otherdomain
 -   ...

### Following/unfollowing

To follow a user with nickname @otheruser@otherdomain, enter the group
called fediverse.@otheruser@otherdomain. This will register you as a
follower of that nickname. In the background the latest posts by that
user will be downloaded and put into Illuminant, if the user isn't
already known to the server.

When you have followed a user, an article representing that user will
appear in fediverse.following. To unfollow a user, enter
fediverse.following and post a follow up to the article representing
that user.

### Reading

The person sending the post is shown in the From: header with name and
nickname.

Hashtags will be displayed in the Keywords: header (without the #'s).

The convention for Content Warning in the fediverse is that the
"subject" field is set. In the nntp articles this is translated to
prefixing the Subject: header with a warning triangle.

When there is no "subject", Illuminant will put the beginning of the
post in the Subject:, to make a nicer overview.

Likes are displayed by putting a star at the beginning of the Subject:
header, and repeats (boosts/re-posts) are signaled with a two-arrow
icon.

In the case of likes or repeats, the From: header contains the name
and nickname of the original author, while the name and nickname of
the person who created the like/repeat is shown in the Sender: header.

Often you'll see replies from people you follow to posts by people you
don't follow. If you ask your newsreader to display the parent
article, Illuminant will try to fetch that article from the relevant
server, regardless of whether you are following the author of the
parent article or not.

### Sending new/replies

To write a new post, enter fediverse.home and post a new article. The
body is interpreted as Markdown (and converted to HTML). MIME
attachments will be gathered and sent as attached images, keywords
will be sent as hashtags. Note that you must put the hashtags in the
body of the article yourself.

To answer a post, make a followup in fediverse.timeline,
fediverse.home, or fediverse.@otheruser@otherdomain.

When you send a post, if you have included an X-Face: or Face: header,
this will be picked up by Illuminant and stored as the icon for your
user.

### Liking posts

To like a post, make a followup but send it to the newsgroup
fediverse.like.

### Repeating posts

To repeat (boost, re-post) a post, make a followup but send it to the
newsgroup fediverse.repeat.

### Voting in polls

Create a followup with an option you want to vote for per line in the
article.

### Editing your profile

You can edit your profile by posting an article in fediverse.profile -
you avatar will be the X-Face/Face from the article, your background
image is the first attached image in the article.

Your description will be the body of the article, up until two empty
lines, after which the attachments are listed, one per line, with the
label up until ":" and the value after.

Example:

    From: Adam Sjøgren <asjo@illuminant.asjo.org>
    Face: [png]
    Subject: Profile
    Newsgroups: fediverse.profile

    Just call me [Mr. NNTP](https://https://koldfront.dk/just_call_me_mr_nntp_1871).


    Blog (English): https://koldfront.dk/
    Blog (Danish): https://kammeratadam.dk/
    Feedbase: https://feedbase.org/

    [Attachment: robert_rauschenberg_dsc9187.jpg]

Prerequisites
-------------

 * PostgreSQL
 * nntp client
 * compface netpbm
 * openssl
 * To build: GHC, cabal
 * Webserver (eg Apache)

Installation
------------

This is tested on Debian 12 (bookworm, stable).

 * Install GHC and Haskell libraries

```
sudo apt install cabal-install ghc libghc-warp-dev libghc-postgresql-simple-dev libghc-aeson-dev libghc-yaml-dev libghc-http-types-dev libghc-wai-extra-dev libghc-wai-dev libghc-hsopenssl-dev libghc-http-conduit-dev libghc-unliftio-dev libghc-vector-dev libghc-wai-middleware-static-dev libghc-network-dev libghc-sockaddr-dev libghc-tls-dev libghc-mime-dev libghc-random-dev libghc-temporary-dev libghc-juicypixels-dev libghc-cmark-gfm-dev libghc-lens-dev libghc-attoparsec-dev libghc-case-insensitive-dev libghc-safe-exceptions-dev
cabal new-update
```

 * Clone Illuminant repository: `git clone https://koldfront.dk/git/illuminant/ && cd illuminant`
 * Build the Illuminant servers: `cabal new-build`
 * Install PostgreSQL: `sudo apt install postgresql-15`
 * Create a user for yourself: `sudo -u postgres createuser --createdb --createrole "$USER"`
 * `createdb illuminant`
 * `psql illuminant -f db/init.sql`
 * Build bin/gensaltedhash: `cd bin && cabal new-install --lib pbkdf random && ghc --make gensaltedhash.hs && cd ..`
 * Generated saltedhash password, fill in YOURPASSWORD: ` SALTEDPW=$(./bin/gensaltedhash YOURPASSWORD)`
 * Generate RSA key pair for your own user:
     * `openssl genrsa -out private.pem 2048`
     * `openssl rsa -in private.pem -outform PEM -pubout -out public.pem`
 * Fill in YOURDOMAIN, YOUR NAME: `export PUBLIC_KEY=$(sed 's/$/\\n/' public.pem | tr -d '\n') export PRIVATE_KEY=$(sed 's/$/\\n/' private.pem | tr -d '\n'); psql illuminant -c "INSERT INTO \"user\" (nickname, login, password, \"name\", private_key, public_key, \"type\") values ('@$USER@YOURDOMAIN', '$USER', '$SALTEDPW', 'YOUR NAME', E'$PRIVATE_KEY', E'$PUBLIC_KEY', 'Person')"`
 * Generate RSA key pair for background user:
     * `openssl genrsa -out background_private.pem 2048`
     * `openssl rsa -in background_private.pem -outform PEM -pubout -out background_public.pem`
 * Fill in YOURDOMAIN: `export PUBLIC_KEY=$(sed 's/$/\\n/' background_public.pem | tr -d '\n') export PRIVATE_KEY=$(sed 's/$/\\n/' background_private.pem | tr -d '\n'); psql illuminant -c "INSERT INTO \"user\" (nickname, login, password, \"name\", private_key, public_key, \"type\") values ('@background@YOURDOMAIN', 'background', 'NOLOGIN', 'Background Daemon', E'$PRIVATE_KEY', E'$PUBLIC_KEY', 'Service')"`
 * Add user to run nntp server: `sudo adduser --system --no-create-home --disabled-password --disabled-login illuminant-nntp`
 * Add user to run http server: `sudo adduser --system --no-create-home --disabled-password --disabled-login illuminant-http`
 * Add user to run background server: `sudo adduser --system --no-create-home --disabled-password --disabled-login illuminant-background`
 * Get certs from Let's Encrypt for nntp, put in certs/
 * Change owner of static/attachments: `mkdir -p static/attachments; sudo chown illuminant-nntp:illuminant static/attachments`

### To install the servers

(I have made `/usr/local/bin` writable to my user.)

```
cabal install exe:illuminant-http --install-method=copy --overwrite-policy=always --installdir=/usr/local/bin/
cabal install exe:illuminant-nntp --install-method=copy --overwrite-policy=always --installdir=/usr/local/bin/
cabal install exe:illuminant-background --install-method=copy --overwrite-policy=always --installdir=/usr/local/bin/
strip /usr/local/bin/illuminant-{http,nntp,background}
```

 * Configure your machine to start `illuminant-background`, `illuminant-http`, and `illuminant-nntp` - eg using systemd .service files:

`/etc/systemd/system/illuminant-background.service` - adjust WorkingDirectory to where you checked out the repository, and create /var/log/illuminant with appropriate permissions - if you like to use [timestamp](https://koldfront.dk/git/timestamp/about/), install it:

```
[Unit]
Description=Illuminant background daemon
After=postgresql.service

[Service]
# To build: see illuminant-http.service
Type=simple
# Add user: adduser --system --no-create-home --disabled-password --disabled-login --ingroup illuminant illuminant-background
User=illuminant-background
WorkingDirectory=/var/www/illuminant.asjo.org
ExecStart=/bin/bash -c '/usr/local/bin/illuminant-background --config illuminant.conf 2>&1 | timestamp /var/log/illuminant/background.log'
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
```

`/etc/systemd/system/illuminant-http.service`:


```
[Unit]
Description=illuminant http server
After=postgresql.service

[Service]
Type=simple
User=illuminant-http
WorkingDirectory=/var/www/illuminant.asjo.org
ExecStart=/bin/bash -c '/usr/local/bin/illuminant-http --config illuminant.conf 2>&1 | timestamp /var/log/illuminant/http.log'

[Install]
WantedBy=multi-user.target
```

`/etc/systemd/system/illuminant-nntp.service`:

```
[Unit]
Description=Illuminant NNTP daemon
After=postgresql.service

[Service]
Type=simple
User=illuminant-nntp
WorkingDirectory=/var/www/illuminant.asjo.org
ExecStart=/bin/bash -c '/usr/local/bin/illuminant-nntp --config illuminant.conf 2>&1 | timestamp /var/log/illuminant/nntp.log'

[Install]
WantedBy=multi-user.target
```

* Adjust `illuminant.conf` in the folder you cloned the repository into.
* Start the three services.
* Configure your newsreader to connect to your server on port 11199 with your login and YOURPASSWORD.


Development
-----------

Illuminant is written in Haskell.

The source code can be found on [https://koldfront.dk/git/illuminant](https://koldfront.dk/git/illuminant)

Debug with `gnutls-cli localhost --port 11199 --insecure --crlf`

License
-------

GPLv2.

Author
------

Adam Sjøgren &lt;<asjo@koldfront.dk>&gt; - @asjo@illuminant.asjo.org

<!--
;;; Local Variables: ***
;;; eval: (auto-fill-mode -1) ***
;;; End: ***
-->