Honk Server Setup Guide (Simpler Mastodon)

Honk

Prerequisites

The official docs do a good job of explaining the build and install process. You should definitely read them first. However, there were a few things which were hard to find in the docs and some which were unclear enough that I had to read the source code to find the answers to.

You will require:

• golang compiler v1.13+
• libsqlite
• a webserver with a TLS cert (not self-signed) e.g. nginx/letsencrypt
• (nice to have) ImageMagick or GraphicsMagick for image file conversion

Building is straightforward. make in the top level directory should work and produce a honk executable in the top level directory. You can run everything from the top level directory but I copied the executable to /usr/local/bin and installed the other directories in the system path /var/lib/honk.

There are some other directories which you will need for a full installation. They are mentioned in various places throughout the official docs but here they all are in one place. You can create them all at initial install. Maybe under /var/lib/honk or wherever you install permanent servers on your machine.

$datadir/
  views/
    favicon.ico icon.png # website favicon available if present here
    local.css # your override for default css: colors etc. (see file views/style.css for inspiration)
    local.js
  memes/
    # images here can be inlined in messages with [meme:] prefix
    # also my avatar image extension requires avatar images in this directory
  emus/
    # images to be used as stickers in messages

$viewdir/
  views/ # copy the views directory from the source tree to here (html templates for web if)
  docs/ # copy the docs directory from the source tree to here (for help menu)

These commands should create the directories you need

For example with these paths:
  rundir=/var/lib/honk
  datadir=$rundir/db
  viewdir=$rundir

mkdir -p $datadir/views
mkdir -p $datadir/memes
mkdir -p $datadir/emus
mkdir -p $viewdir
cd $honktoplevelbuilddir
cp -r views $viewdir
cp -r docs $viewdir

honk Initial Setup

To create the initial, empty, sqlite database run the init command below. You will be asked for your username and password (you will use these at the web interface to log in), the web server name which will reverse proxy your honk server. Note this web server must have TLS and a non-self-signed certificate (e.g. letsencrypt). Mastodon peer servers will not accept self-signed certs. The listen address is a unix socket path via which your webserver/reverse-proxy will connect. (It is possible to use an internet socket instead - see honk docs).

honk -datadir $datadir -viewdir $viewdir init
  username: $yourusername
  password: $youruserpassword
  listen address: /var/lib/honk/honk.sock
  server name: $webserver-hostname # mine is honk.deckc.hair

chown -R myuser:myuser db

After init you can run the admin tool to customize some text and behavior. It's not necessary at this point.

honk -datadir $datadir -viewdir $viewdir admin

Run honk like this: ($datadir and $logfilepath must be writable)

logfilepath=/var/log/honk/honk.log
honk -datadir $datadir -viewdir $viewdir -log $logfilepath

Web Server Setup

This covers the setup for nginx and should give at least an idea of what to do for other web servers. Getting a cert from letsencrypt is outside the scope of this doc. I used the acme.sh tool rather than the python tool. You must use $servername for the cert although letsencrypt does now allow wildcard certs for all subdomains.

$ vi /etc/nginx/nginx.conf
server{
  listen              443 ssl;
  listen              [::]:443;
  server_name         $servername;
  ssl_certificate     /etc/certs/$servername_ecc/fullchain.cer;
  ssl_certificate_key /etc/certs/$servername_ecc/$servername.key;
  ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
  ssl_ciphers         HIGH:!aNULL:!MD5;
  location / {
      proxy_pass       http://unix:$listenaddress;
      proxy_set_header Host      $host;
      proxy_set_header X-Real-IP $remote_addr;
  }
}

Now point your web browser at https://$servername/ and the honk interface should appear. You will be able to log in and then follow the honk user guide and other docs from here.

First steps - Following

The first thing you will probably want to do is follow some users from honk (or mastodon). You'll need that user's handle. Either of the 2 formats @nandalism@honk.deckc.hair or https://mastodon.something/users/someuser/ will do.

• go to menu at top left and select honkers.
• paste the user's handle e.g. @nandalism@honk.deckc.hair in the url field.
• name: can be a human-style name for the user, leave blank to use the handle username.
• combos: you can put a group name here, which can be useful to group users with the same combo into separate feeds.
• now press add honker

Now comes the moment of truth. The new honker will appear below and expanding details should show flavor: sub (this might take a few moments and a refresh to appear). If this doesn't seem to happen check your honk log on the server at $logfilepath. The usual reasons for this are, the server name you gave at init not matching your web server's host name or your TLS cert being invalid. Unfortunately the error will be appearing on the remote e.g. mastodon server containing the user you are following and you cannot see it.

Check that the path for your user exists e.g. https://honk.deckc.hair/u/nandalism. The remote server will query that to find your public key for authentication. Make sure your cert is not self-signed. This was the trickiest part of setup since there is no feedback from the remote server other than a 401 Unauthorized error or something similar.

See my other article on a honk extension for avatar images.