srv/README

(*) Introduction

LOOP is an NNTP server written in Common Lisp.

(*) Assumptions

We assume

  - you run SBCL

  - you have Quicklisp installed and knows how to use it

  - you know how to use a TCP server such as 

      https://cr.yp.to/ucspi-tcp.html

  - you know how to manage a daemon with 

      https://cr.yp.to/daemontools.html

  - you have git and knows how to use it

(*) How to install it

LOOP is not in the Quicklisp repository, so we'll instruct you to
install it as a local project.  Go to

  ~/quicklisp/local-projects/

and say 

  $ git clone https://git.antartida.xyz/loop/srv loop
  $ cd loop
  $ make

If you just installed SBCL and quicklisp, the build might take a
little while to download dependencies.  Be patient.  Now you have the
executable loop.  Try it out:

--8<-------------------------------------------------------->8---
$ ./loop --help
NAME:
  loop - An NNTP server for a circle of friends.

USAGE:
  loop [options] [arguments ...]

OPTIONS:
      --change-passwd <VALUE>   <username> <new-password> changes password
      --create-account <VALUE>  <username> <invited-by> creates a new account
      --help                    display usage information and exit
      --logging                 turn on debug logging on stderr
      --version                 display version and exit
  -l, --list-accounts           lists accounts
  -r, --repl                    run a REPL on port 4006
  -s, --server                  runs NNTP server reading from stdout

AUTHORS:
  Circling Skies <loop@antartida.xyz>

LICENSE:
  GPL v3
--8<-------------------------------------------------------->8---

You can talk to the NNTP server with -s:

--8<-------------------------------------------------------->8---
$ ./loop -s
200 Welcome! Say ``help'' for a menu.
quit
205 Good-bye.
--8<-------------------------------------------------------->8---

It's time to choose a directory from which LOOP will run.  Say you
choose $HOME/loop.  Then say 

  $ echo $HOME/loop > conf-home
  $ make install

It's time to create an account you.  Whenever you run loop, make sure
you're in its home directory because it will look for the file
accounts.lisp always relatively to the current working directory of
the process.  (So, if you set up a cron job later on, make sure the
job, too, sets LOOP's home directory as its current working
directory.)

(*) Create your account

LOOP requires authentication for most things, so you should create an
account for you right away.  Accounts are kept in accounts.lisp in
your installation directory.  Every time you create an account, you
must specify who is inviting this new account into the LOOP---because
we keep a tree of accounts.  The root account is called anonymous, so
your first account must be invited by the anonymous account.  So you
can say

  ./loop --create-account you anonymous

The anonymous account has no special power.  It exists solely because
the graph of accounts needs a root.

(*) How to expose it to the network

Run your TCP server of choice.  For instance, if you're using djb's
tcpserver and would like LOOP to listen on port 1024, tell your shell

--8<-------------------------------------------------------->8---
$ tcpserver -v -HR 0.0.0.0 1024 ./loop -s
tcpserver: status: 0/40
--8<-------------------------------------------------------->8---

Using another terminal, telnet to your host on port 1024:

--8<-------------------------------------------------------->8---
$ telnet localhost 1024
Trying 127.0.0.1...
Connected to antartida.xyz.
Escape character is '^]'.
200 Welcome! Say ``help'' for a menu.
quit
205 Good-bye.
Connection closed by foreign host.
--8<-------------------------------------------------------->8---

Directories daemon/ and daemon-tls/ in LOOP's source code have sample
scripts to use with djb's tcpserver and daemontools.  If you have
never done this, it will be better education if you learn to use
daemontools and ucspi-tcp before going live with a LOOP community.
It's easy and fun.

(*) Systems with no installation issues

We installed LOOP just fine on

  FreeBSD 14.1, 14.2 with SBCL 2.4.9.
  Debian GNU/Linux 8.11 codename jessie with SBCL 1.2.4.debian.

(*) Systems with installation issues

We installed LOOP on Ubuntu 24.04 (24.01.1 LTS) codename noble with
SBCL 2.2.9.debian.  We found that CLSQL could not load the shared
object libsqlite3.so because ``apt install libsqlite3'' installs the
library at 

  /usr/lib/x86_64-linux-gnu/libsqlite3.so.0.8.6

with a symbolic link to libsqlite3.so.0, but not to libsqlite3.so.
SBCL is trying to load libsqlite3.so, so a solution is to just tell
your system to

  ln -s libsqlite3.so.0 libsqlite3.so

at /usr/lib/x86_64-linux-gnu.