predator_pics/README.md

Predator Pics (birds.bateleur.org)

Predator Pics is a website that uses the API of Wikimedia Common to display a random image of a bird of prey. There is a Mastodon / Fediverse bot called “Bot of Prey” that uses the API of this website as its backend.

How it works

1. The program choses a random category from the categories.txt file located in this repository
2. It then sends an API request to receive a list of all (<= 500) photos located within that category on Wikimedia Commons
3. It then chooses one of the photos it received at random, saves important metadata (like author, license and description) and displays it on the webpage

How to run and install it

If you wish to run your own instance of Predator Pics, you must have Ruby installed (tested on Ruby 3.2.2); you‘ll also need the bundler gem that you can install by running gem install bundler after having installed Ruby. It is generally recommended to not install Ruby through your distributions package manager – rather, install Ruby through a Ruby version manager like rbenv (https://rbenv.org).

Then clone this repository and install the required gems by running bundle install from your terminal within the cloned repository. Afterwards, start the server by running ruby server.rb. The server (usually thin) will then start in production mode and serve the website on localhost:4567.

Reverse proxy

If you wish to make Predator Pics accessible via the Internet, you‘ll want to use a reverse proxy. My preferred method of doing that is by using Caddy. First, install Caddy and then remove everything located in the /etc/caddy/Caddyfile file and paste the following into it, replacing example.com with your actual domain name:

example.com {
        encode zstd gzip

        reverse_proxy :4567
}

Autostart

You can use the predator_pics.service template and adjust it to your own needs and setup. Afterwards, move it to /etc/systemd/system and enable and start it with (sudo) systemctl enable --now predator_pics.