Vervis/INSTALL.md

Vervis is still in early development. These instructions may be incomplete
and/or slightly outdated. At the time of writing, you can get a running Vervis
instance if you follow the steps below.

Check the version of OpenSSL installed on your system. For example:

    $ apt show openssl

Currently Vervis is using a slightly old software configuration, and until I
fix that, it doesn't build with OpenSSL 1.1 and needs the older 1.0 or 1.0.1
version. If your distro has 1.1, see if you can grab 1.0 or 1.0.1 in some way,
either through the distro package or by downloading OpenSSL manually from its
website, or some alternative package manager such as GNU Guix.

UPDATE: If you proceed with the steps below and `stack build` throws an error
while building `HsOpenSSL`, there's a chance you can still use OpenSSL 1.1
successfully if you run these commands:

    $ stack build HsOpenSSL --flag HsOpenSSL:-fast-bignum
    $ stack build

Install dependency library development packages. It's very likely you already
have them all installed, and if you're missing some, the build process will
inform you. But it's still nice to have a list here. The list below isn't a
complete list, it's just libraries that people have found missing while
building, and let me know.

- PostgreSQL client library
- ZLib

On Debian based distros, installation can be done like this:

    $ sudo apt install libpq-dev zlib1g-dev

Install stack. To install stack, go to its [website](https://haskellstack.org)
and follow the instructions.  If you have some old version, such as one
installed from FPComplete's old debian repo, you may need to upgrade it.

Install Darcs. You can grab it from your distro, e.g.:

    $ sudo apt install darcs

If you're going to create a Git repository on Vervis, you'll need Git too, you
can install it from a distro package too, e.g.:

    $ sudo apt install git

Clone the Vervis repo:

    $ darcs clone https://dev.angeley.es/s/fr33domlover/r/vervis
    $ cd vervis

Install GHC. Unless you prefer to use a distro package or PPA or some other
source, the easiest way is to install via stack:

    $ stack setup

Some of the dependency libraries need to be manually downloaded. Either because
I've written them and haven't released yet, or because they have unreleased
changes, or because I'm using a patched version of some library and the patch
hasn't found its way upstream.

In the `stack.yaml` file, under the `packages` field, there is a list of such
libraries. While `stack` supports fetching dependencies from Git repositories,
it doesn't support Darcs (if that changes and I haven't noticed, let me know!),
so we need to download them by ourselves. A line in the `packages` list that
looks like this needs manual download:

`  - '../some-library-name'`

These details change often because of all the unreleased libraries and patches,
so until there are sane releases for everything, the instructions here aren't
always up to date. Basically it works like this:

- Those extra repos should be found at the
  [Vervis project page](https://dev.angeley.es/s/fr33domlover/p/vervis)
- If something is missing there, try my
  [Darcs Hub page](https://hub.darcs.net/fr33domlover)
- Use `darcs clone` to grab the library source code

As of May 24, 2018, you can grab these libraries by simply running the
[`clone-deps.sh`](./clone-deps.sh) script.

Update `stack.yaml` to specify the paths in the `packages` section if needed:

    $ vim stack.yml

Generate a new SSH key with a blank password:

    $ ssh-keygen -t rsa -f config/ssh-host-key

Install PostgreSQL. You'll need the server and the client library development
files.

    $ sudo apt install postgresql libpq-dev

Switch to `postgres` system user:

    $ sudo su - postgres

Create a PostgreSQL user.

With password:

    $ createuser --no-createdb --no-createrole --no-superuser --encrypted --pwprompt vervis

No password (if you run Vervis as a user by the same name as the DB user):

    $ createuser --no-createdb --no-createrole --no-superuser vervis

Create a PostgreSQL database:

    $ createdb --encoding=UTF8 --owner=vervis vervis

Update the settings to specify correct database connection details and other
settings.

    $ cp config/settings-default.yaml config/settings.yml
    $ vim config/settings.yml

Build.

    $ stack build

For convenience, at least on actual deployments, you may wish to run the Vervis
SSH server on port 22, so that people don't have to specify a custom port. For
that to work, the user that runs the Vervis server needs to get permission to
bind to ports below 1024. There are several ways to do that. One of them is to
use file capabilities to give the Vervis executable the permission to bind to
such ports (if you prefer not to trust the code, try one of the other methods,
such as sudo):

    $ sudo setcap CAP_NET_BIND_SERVICE=+ep `stack exec which vervis`

Run.

    $ stack exec vervis

Browse to `http://localhost:3000` and have fun!

`yesod devel` is another way to run the application, useful for rapid
development, but I haven't been using it and I'm not sure it works, possibly I
broke something along the way. But feel free to try!