Drop #135 (2022-11-11): 🛠️ Weekend Project Edition

Honk If You Like The Fediverse!

So, you've committed to abandoning the bird site, joined a 🐘 instance, or three, and are now a citizen of the Fediverse. This is 👍🏽! But, what if you want to dig into this brave new universe a bit and see how it works? Or, perhaps you wish to engage with a specific set of other folks without committing to a particular/existing BBS node?

Running a full-on Mastodon instance means dealing with PostgreSQL, Redis, Ruby (ugh), and NodeJS. Sure, Docker is an option, but this is still a big project, and it's more than likely that you're not a Ruby programmer (which makes it difficult to poke at the code to bend it to your will).

What if I told you there's a way to run your own ActivityPub (Stream/et al.) server, that:

• is built with Golang (requires libsqlite3)

• uses SQLite for persistence

• compiles in seconds

• sets up in minutes

• takes almost no system resources

• supports custom emojis

• allows markdown in posts (including source code block syntax highlighting)

• features location check-ins (like Foursquare back in the old days)

• enables filtering and censorship (for abuse prevention)

• sports a tiny but quite useful API

• lets folks consume your activity stream as an RSS feed

If that sounds more to your liking, let me introduce you to Honk by Ted Unangst (@tedu@honk.tedunangst.com), and walk you through my Honk (@bob@honk.hrbrmstr.de) setup.

Prepare To Honk

You can either use Mercurial and:

$ hg clone https://humungus.tedunangst.com/r/honk

or grab a tarball and expand it (do either of these things on the box you will be running Honk). Then, just:

$ cd honk
$ make

and in a couple of seconds you'll have a honk server binary ready to use. Best to move it to a custom app directory after reading the manuals to see what else you need to move with it.

Now, you're also going to need a "TLS terminating reverse proxy". We'll be using Nginx since it is nigh ubiquitous and straightforward to setup. If you've never setup an HTTPS Nginx instance. Nginx drops in nicely almost everywhere, and this isn't a terrible certbot/nginx 'splainer. The rest of this drop assumes you have an Nginx instance ready to configure for honking.

I'm hosting my actual Honk instance on an overkill home data science server (you can use a Raspberry Pi to run Honk), which is exposed to one of my internet-facing Nginx reverse proxy servers via Tailscale. Using a setup like this means you can go super-cheap ($5/mo) on a VPS. You can also 100% just run Honk on the same internet-facing box as you do Nginx, just make sure to follow the specific guidance for that setup below, and mebbe spring for a slightly bigger server. FWIW I use SSD Nodes (full-disclosure: that is an affiliate link).

Finally, you'll need a FQDN configured that points to your reverse proxy. Mine is honk.hrbrmstr.de which has an A record pointing to my internet-facing VPS. Your stream handle will be @user@ThisFQDNyouChose, so pick one you can live with.

Make sure all three of those things are ready for the remaining steps.

Configure + Run Honk

This part is pretty straightforward. Run:

$ ./honk init

on the box you're running Honk from. It's going to ask you for four pieces of information:

• username: the username you want. Again, this will be your @username@TheHonkFQDNyouChose identity, so pick one you can live with.

• password: the password you want; pick a long passphrase from a password manager generator that you'll keep in said password manager. Honk does not support MFA. Attackers will find you. You cannot hide. Just make it hard for them.

• listenaddr: host + port Honk will listen on. If running Honk on the same system as Nginx, make it something like 127.0.0.1:31337 so Honk itself is only accessible locally. I used my the home server’s Tailscale IP address that my VPS can connect to.

• servername: the FQDN you configured in the previous section.

If you mess up, just remove the SQLite databases Honk just made and start over.

Feel free to get all fancy with whatever system service/init runner you like, but I just run Honk from a custom application directory with:

$ nohup ./honk &

You leave out the nohup and &, or tail -f nohup.out, if you want to see the log as you configure Nginx in the next section.

Configure Nginx

Remember that this bit assumes you've installed Nginx and set it up with a certbot TLS certificate. See above for links to resources to help you do that.

Now you need to tell Nginx where to serve up your honk instance. Modify your base config to look something like this:

server {

  server_name honk.example.com;

  location / {
    proxy_pass http://127.0.0.1:31337;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme; 
  }

  listen 443 ssl; # managed by Certbot

  ssl_certificate /etc/letsencrypt/live/honk.example.com/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/honk.example.com/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}

server {

  if ($host = honk.example.com) {
    return 301 https://$host$request_uri;
  } # managed by Certbot

  listen 80;

  server_name honk.example.com;

  return 404; # managed by Certbot
  
}

Replace the proxy_pass, honk.example.com, and 127.0.0.1:31337 values with your specific config.

Restart Nginx and go to honk.example.com. If you don't see the Honk main page, check the Nginx logs and the Honk logs and give it a go again.

Go Honkin' Crazy

The Honk docs are useful and quite fun reads.

• The user manual should be required reading so, at the very least, you can grok the honking terminology.

• The server manual shows you some options you can use when starting Honk, explains how to customize Honk's (it supports some fun customizations), explains user management, and some additional care and feeding tips. Read this thoroughly.

• The composition manual is a must-read since it shows off all the post composition features.

• The filtering and censorship system manual will help you deal with any abuse.

• The ActivityPub manual explains what Honk does and does not support in that protocol.

• The API manual has all the information you need to use your Honk instance via some programming language or just curl.

Stuff To Try!

• Follow folks on other servers! Hit me up at @hrbrmstr@mastodon.social or @bob@honk.hrbrmstr.de if you want to test following out (and get a reply).

• Customize your site CSS! Make it yours. The manuals provide all the information you need to do this.

• Add custom emoji and other components (again, the manuals are great).

• Write an API wrapper package, so you can use your instance programmatically (this is a good way to make a bot).

• Look at the toys/ subdirectory. It has some fine example programs you can riff from (or just use):

  • autobonker.go - repeats mentioned posts

  • gettoken.go - obtains an authorization token

  • saytheday.go - posts a new honk that's a date based look and say sequence

  • sprayandpray.go - send an activity with no error checking and hope it works

  • youvegothonks.go - polls for new messages

• Import your toots or Twitter archive

• Start a Honk instance for one of the communities you're in. Honk really cannot support a very large community, but moderately sized communities can use Honk vs deal with a full-on Mastodon instance.

• Poke around the SQLite databases Honk uses.

• Help someone else set up a Honk instance

• Customize the Honk codebase and show off your additions

Get Familiar With The Protocols

WebFinger (mentioned yesterday) is the on-ramp to poking at things, and I prefer playing with instances I own vs annoy folks trying to run "real" Mastodon servers. Honk lets you play without being a bad netizen.

$ webfinger acct:bob@honk.hrbrmstr.de

drops the following to the terminal:

{
  "aliases": [
    "https://honk.hrbrmstr.de/u/bob"
  ],
  "links": [
    {
      "href": "https://honk.hrbrmstr.de/u/bob",
      "rel": "self",
      "type": "application/activity+json"
    }
  ],
  "subject": "acct:bob@honk.hrbrmstr.de"
}

Visit the aliases in a private browser session (so no cookies/etc. are used, and you see what the world sees) or just curl it from the terminal.

Explore links:

$ curl \
    --header "Accept: application/activity+json" \
    https://honk.hrbrmstr.de/u/bob

drops the following to the terminal (see what happens w/o that custom Accept header, too):

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "followers": "https://honk.hrbrmstr.de/u/bob/followers",
  "following": "https://honk.hrbrmstr.de/u/bob/following",
  "icon": {
    "mediaType": "image/png",
    "type": "Image",
    "url": "https://honk.hrbrmstr.de/a?a=https%3A%2F%2Fhonk.hrbrmstr.de%2Fu%2Fbob&hex=1"
  },
  "id": "https://honk.hrbrmstr.de/u/bob",
  "inbox": "https://honk.hrbrmstr.de/u/bob/inbox",
  "name": "bob",
  "outbox": "https://honk.hrbrmstr.de/u/bob/outbox",
  "preferredUsername": "bob",
  "publicKey": {
    "id": "https://honk.hrbrmstr.de/u/bob#key",
    "owner": "https://honk.hrbrmstr.de/u/bob",
    "publicKeyPem": "CLIPPED B/C TOO BIG FOR SUBSTACK"
  },
  "summary": "BIO CLIPPED B/C TOO BIG FOR SUBSTACK",
  "tag": [
    {
      "href": "https://honk.hrbrmstr.de/o/rstats",
      "name": "#rstats",
      "type": "Hashtag"
    },
    {
      "href": "https://honk.hrbrmstr.de/o/blm",
      "name": "#blm",
      "type": "Hashtag"
    }
  ],
  "type": "Person",
  "url": "https://honk.hrbrmstr.de/u/bob"
}

Try all those endpoints and see what they drop (feel free to hit my server)

FIN

Honk is a great way to explore the various components of the Fediverse and I encourage folks to use it to get more familiar/comfortable with this tech. Drop comments if you run into any issues or have q's (feel free to honk/toot q's as well). ☮