Add README

1 files changed, 139 insertions, 0 deletions

diff --git a/README.7 b/README.7
new file mode 100644
index 0000000..3e32545
--- /dev/null
+++ b/README.7
@@ -0,0 +1,139 @@
+.Dd July 16, 2020
+.Dt README 7
+.Os "Causal Agency"
+.
+.Sh NAME
+.Nm scooper
+.Nd web interface for litterbox
+.
+.Sh DESCRIPTION
+.Nm
+is a CGI and FastCGI
+web interface for
+.Lk https://git.causal.agency/litterbox "litterbox" .
+It provides IRC log listings
+and full-text search.
+.
+.Sh INSTALLING
+.Nm
+targets
+.Fx
+and requires
+.Lk "https://kristaps.bsd.lv/kcgi/" kcgi
+.Po
+.Fl lkcgi
+.Fl lkcgihtml
+.Pc
+and SQLite
+.Pq Fl lsqlite3 .
+.
+.Bd -literal -offset indent
+\&./configure
+make all
+sudo make install
+.Ed
+.
+.Pp
+By default,
+.Nm
+is statically linked
+so it can easily run in
+.Xr chroot 2
+with
+.Xr kfcgi 8 .
+The default install
+.Ev PREFIX
+is also set to
+.Pa ~/.local ,
+which is a convenient
+.Xr chroot 2
+path with access to the default
+.Xr litterbox 1
+database.
+.
+.Sh DEPLOYMENT
+.Nm
+automatically detects
+if it is being run as CGI
+or as a FastCGI worker.
+The
+.Xr kfcgi 8
+daemon included with
+.Xr kcgi 3
+can be used to run FastCGI workers.
+.
+.Pp
+.Nm
+can be configured on the command line
+or through environment variables.
+See
+.Xr scooper 1
+for details.
+.
+.Ss FastCGI & nginx
+Use
+.Xr kfcgi 8
+to run
+.Nm
+as the user who owns
+.Xr litterbox 1 :
+.Bd -literal -offset indent
+kfcgi -u www -s /var/run/scooper.sock \e
+	-U $user -p /home/$user/.local \e
+	-- /bin/scooper /share/litterbox/litterbox.sqlite
+.Ed
+.
+.Pp
+Configure
+.Xr nginx 8
+to serve
+.Nm
+at
+.Pa /scooper/ ,
+for example:
+.Bd -literal -offset indent
+location /scooper/ {
+	fastcgi_pass unix:/var/run/scooper.sock;
+	fastcgi_split_path_info (/scooper)(.*);
+	fastcgi_param PATH_INFO $fastcgi_path_info;
+	include fastcgi_params;
+}
+.Ed
+.
+.Sh FILES
+.Bl -tag -width "default.css" -compact
+.It Pa server.h
+shared declarations and inline functions
+.It Pa server.c
+CGI and FastCGI dispatch
+.It Pa networks.c
+networks page handler
+.It Pa contexts.c
+contexts page handler
+.It Pa events.c
+events page handler
+.It Pa search.c
+search page handler
+.It Pa html.c
+shared HTML generation
+.It Pa default.css
+default stylesheet
+.It Pa color.css
+IRC color definitions
+.It Pa css.sh
+CSS concatenation for static inclusion
+.El
+.
+.Sh CONTRIBUTING
+The upstream URL of this project is
+.Aq Lk https://git.causal.agency/scooper .
+Contributions in any form can be sent to
+.Aq Mt list+scooper@causal.agency .
+For sending patches by email, see
+.Aq Lk https://git-send-email.io .
+.
+.Sh SEE ALSO
+.Xr scooper 1
+.
+.Pp
+.Lk https://git.causal.agency/litterbox "litterbox"