Install

In Brief

  1. Install PostgreSQL 9.5+

  2. Install Python 3.6+

  3. Explode source tarball (eg tar xf furemcape.tar.gz -C /usr/local/src/furemcape)

  4. Set up config files (eg touch /etc/defaults/furemcape /etc/furemcape.yml)

  5. Create databases (optional)

  6. Run installer (eg cd /usr/local/src/furemcape && make install)

Details

Install PostgreSQL

Furem Cape requires PostgreSQL 9.5 or newer. It uses two logical databases: hitdb (for recording processed log entries) and issuedb (for recording potential issues). Both can reside on the same PostgreSQL server and use the same user.

So you could set up two separate, standalone PostgreSQL servers, one for hitdb and one for issuedb; or you could set up one standalone PostgreSQL, and run both hitdb and issuedb on it; or you could just install PostgreSQL on the same server as the other Furem Cape components.

Install Python

Furem Cape requires Python 3.6 or newer. The Furem Cape components (other than the PostgreSQL databases) all run as Python services or command-line applications.

Explode Source Tarball

Explode the Furem Cape source tarball to /usr/local/src/furemcape – ie run these commands:

mkdir /usr/local/src/furemcape
tar xf furemcape.tar.gz -C /usr/local/src/furemcape

Set Up Config Files

Place the Furem Cape environment variables file at either /etc/defaults/furemcape or /usr/local/etc/defaults/furemcape; and the main Furem Cape configuration file at either /etc/furemcape.yml or /usr/local/etc/furemcape.yml. Both could be blank initially – they just need to exist. See /usr/local/src/furemcape/installer for sample files (sample.env for the environment variables file and sample.yml for the configuration file).

At minimum, the furemcape.yml config file should contain the database connection parameters for hitdb and issuedb. These are the defaults:

hitdb:
  host: localhost
  port: 5432
  database: hitdb
  username: hitdb
  password: hitdb

issuedb:
  host: localhost
  port: 5432
  database: issuedb
  username: issuedb
  password: issuedb

Create Databases

If you don’t create the hitdb and issuedb databases first, the Furem Cape installer will attempt to create them by running the following commands:

su -c psql postgres < /usr/local/src/furemcape/hitdb/create.sql
su -c psql postgres < /usr/local/src/furemcape/issuedb/create.sql

This will create empty hitdb and issuedb databases on the local host, and create new hitdb and issuedb users as owners of each, respectively. If you don’t want that, create the databases yourself manually (as well as the user or users with which Furem Cape will access them). Furem Cape expects to access each database as a user who is an owner of the database (ie is permitted to create, drop, or alter tables in the database).

Run Installer

Now run the Furem Cape installer, by changing into the /usr/local/src/furemcape directory and running make install as root. If you have a restrictive umask, change it temporarily to 002, so that the installer creates files/directories with the proper permissions:

cd /usr/local/src/furemcape
sudo (umask 002; make install)

The installer (a series of command-line shell and python scripts) will prompt you with several confirmations about things that it’s going to install. If you already created the databases, instead of running the full installer, just run the parts that install the core Furem Cape code and services:

cd /usr/local/src/furemcape
sudo (umask 002; make install.code && make install.services)

This will install a bunch of python packages in a virtual environment under /usr/local/virtualenvs/furemcape; several executable scripts at /usr/local/bin/furemcape-*, and several services named furemcape-*. You can list the services running under systemd with the following command (with the --all flag to include inactive units):

systemctl status furemcape* --all

Example: Ubuntu 18.04

For example, following are the sequence of commands you’d use to install Furem Cape on Ubuntu 18.04.

Install PostgreSQL

The following command will install a PostgreSQL 10 server on your local host:

sudo apt install postgresql

It will automatically create a postgres user that you can use to administer the server, and start a systemd postgresql service for the server. You can use the psql command line tool to access the server as the root user by running sudo -u postgres psql.

Install Python

The following command will install Python 3.6 with virtualenv support:

sudo apt install python3 python3-venv

Explode Source Tarball

If you don’t have the git client installed, install it with the following command:

sudo apt install git

Then clone the Furem Cape source repository and create a tarball from it with the following commands:

git clone https://git.sr.ht/~axr10/furemcape
(cd furemcape; git archive --format tar.gz master) > furemcape.tar.gz

Then explode the tarball with the following commands:

sudo mkdir /usr/local/src/furemcape
sudo tar xf furemcape.tar.gz -C /usr/local/src/furemcape

Set Up Config Files

The following command will create the necessary config files (as empty files):

sudo touch /etc/defaults/furemcape /etc/furemcape.yml

You will need to edit the furemcape.yml config later in order to get Furem Cape to do something, but it can be empty initially (as long as you use the defaults for the database connections).

Create Databases

The “Run Installer” step below will create the databases automatically on the local host, so this step isn’t necessary.

Run Installer

If you don’t have make installed, install it with the following command:

sudo apt install build-essential

Then run the Furem Cape installer with the following commands:

cd /usr/local/src/furemcape
sudo (umask 002; make install)

The installer will create the hitdb and issuedb PostgreSQL databases on the local host, install the Furem Cape Python code in a virtual environment under /usr/local/virtualenvs/furemcape, and installing the Furem Cape services as systemd units.

Troubleshooting

Check Services

If running systemctl status furemcape* --all shows all active services with no errors, everything has been installed okay. If some services are inactive or snippets of stack traces are showing, try looking at the full logs with journalctl. For example, the following will show the combined logs from all the furemcape services:

journalctl -u furemcape*

You can use Vim keybindings to navigate up and down (or search) in journalctl; for example shift-G will take you to the last line.

Check Permissions

Check the permissions of the following files and directories; they all should be readable by the furemcape user or group (and the bin files executable by the furemcape user/group):

  • /etc/default/furemcape (or /usr/local/etc/default/furemcape)

  • /etc/furemcape.yml (or /usr/local/etc/furemcape.yml)

  • /usr/local/bin/furemcape-*

  • /usr/local/src/furemcape

  • /usr/local/virtualenvs/furemcape

Check Database Connectivity

Check that you can access the databases from the local host with the PostgreSQL command-line client:

psql -h localhost -p 5432 hitdb hitdb

You should be able to connect, and if you run the \dt at the hitdb=> prompt (once logged in), you should see several tables listed (including the hit table in the hitdb, and the issue table in the issuedb).