roygbyte.com/1/install_wallabag_on_openbsd.gph

  URI:

INSTALL WALLABAG ON OPENBSD

Preamble
----------------------------------------------------------------------
I wasn't reading much. I'd fallen out of my love to tuck into books of
fiction and have my days surrounded by stories of lives lived in far
off times and places. I've always said that having a good book on the
go contributes positively to my mental health. To read a story about
someone else is a bit like a bloodlet followed by a blood transfusion:
my brain's excess narrative energy is poured out and restored with a
zeal not my own. So why wasn't I reading books? My interests
changed. The fiction I usually sought and sucked dry didn't appeal as
stongly. Instead, I was becoming interested in reading technical blogs
and their articles on hardware, software, and programming. I was
accumulating bookmarks in browsers and notebooks. This was exciting. I
saw that my mind was thirsty to learn from the swarm. But I would need
the right tools to succeed. I would need to use a piece of software
like Wallabag.

I'd learned about Wallabag by way of people on the KOReader project,
one of whom nicely granted me access to their Wallabag instance a few
years ago. I wanted to install my own Wallabag instance now, and I
wanted to do it on OpenBSD. There are no full tutorials on the
procedure that I could find, and notes on Wallabag's documentation
sometimes only indirectly relevant. So this would be a bit of a
challenge for me. Well, I'm happy to say that I have succeeded. The
experience was rewarding and the outcome exciting. I am reading
interesting voices and ideas much more now. In a way, it's like I am
curating my own person magazine. I bring this ever-growing publication
with me throughout the internet, reading it whenever occasion or
interest arrives. Happily, I am again filling my days with worlds and
ideas.

Documented in the remainder of this writing are my notes regarding an
installation of Wallabag on OpenBSD. The process roughly included:

- Installing system dependencies
- Configuring httpd and PHP
- Preparing database user and table
- Installing Wallabag dependencies
- Configuring chroot environment

These notes were taken quickly, so it's possible there are
inaccuracies. Be warned!

Installation notes
----------------------------------------------------------------------
PHP
......................................................................
I had installed PHP and configured a PHP-FPM pool for a WordPress
installation running on my server. So to get PHP setup for Wallabag
was a simple process. The software documentation listed a few
additional PHP dependencies I needed to install.

I remembered how much I like the PHP initialization file format, where
activating extensions simply require moving files into a folder. Easy!

Afterwards, I restarted the PHP-FPM process: `doas rcctl restart
php82_fpm'

httpd
......................................................................
The rewrite rule was easy to figure out. I used the same PHP-FPM
process as WordPress, and pretty well the same location matches,
too. I picked up a new pieced of learning, which is the association
between the request's URL and its being rewritten with the addition of
the `app.php' file. That rewritten URL leads to the file that will be
consumed by the PHP-FPM socket. Like WordPress, some asset files need
to be served.

server "wallabag.roygbyte.com" {
listen on * tls port 443
listen on * port 80
tls {
certificate "/etc/ssl/roygbyte.com.fullchain.pem"
key "/etc/ssl/private/roygbyte.com.key"
}
location "*.css" { pass }
location "*.svg" { pass }
location "*.js" { pass }
location "*.ico" { pass }
location "*.png" { pass }
location "*.woff" { pass }
location "*.woff2" { pass }
location "*.php*" {
fastcgi socket "/run/php-fpm.sock"
}
root "/htdocs/wallabag.roygbyte.com/web"
location match "^/(.-)$" {
request rewrite "/app.php/%1"
fastcgi socket "/run/php-fpm.sock"
}
}

Database
......................................................................
Wallabag needs a table, and a user with access to that table. The
project's instructions provided details that I followed.

Wallabag
......................................................................
Composer is needed for project dependencies. I generally followed
instructions on , except I put Composer into its own directory. Then,
I make the executable available by adding the directory to my path:
`export PATH'"$PATH:$(pwd)"=.

I cloned the project repository into the directory served by
`httpd'. As instructed, I ran `make install'. From here, the
software's instructions were mostly self-evident. The only trouble I
ran into was during th server configuration process. Entering values
with special characters resulted in a error. So I had to manually
review and edit the production configuration's `yml' file,
`app/config/parameters.yml'. Some values with special characters
needed to be enclosed by single quotes.

It was necessary to change the password for the account created during
the installation, invoking `php bin/console --env=prod
fos:user:change-password'.

I think at somepoint I also ran an installation command from the
console, as I have this in my notes: `php bin/console wallabag:install
--env=prod'. I think running this skips installing Composer
dependencies.

Permissions
......................................................................
The web server process' user must be able to read all the files in the
Wallabag directory. The user must also be able to write to `data',
`config', and `web'. Simple `chmod' got me that, but I did run into
some problems along the way. To troubleshoot, I found that the
Wallabag log file in the project's `var' folder to be
helpful. Likewise, errors were emitted to the PHP-FPM process' error
log. If there were directories or files it needed to access, an error
was raised and I made the compatible modification.

chroot environment
......................................................................
With everything above finished, I could log on to my Wallabag instance
and add articles. Strangely, they failed to download when fetched
through the web interface. But I could manually invoke a console
command to get them. Weird! Well, turns out that cURL wasn't able to
verify host certificates because itself was lacking certificate!

,----
| httplug.ERROR: Error: cURL error 77: error setting certificate verify locations: CAfile: /etc/ssl/server.crt CApath: none
`----

I knocked many hours into this issue before the arriving at the
realization stated above. To fix I just had to copy my system's root
certificate into the PHP-FPM chroot environment.

,----
| cp /etc/ssl/cert.pem /var/www/etc/ssl/server.crt
| rcctl restart php82_fpm
`----

This isn't a perfect solution, and it may not even be the correct
solution. The certificate probably needs to be updated regularly. I'm
not yet sure how to maintain this process. Maybe a cron job that
periodically copies the certificate into the chroot environment.

Wallabag seems to include a certificate file inside of a `etc' folder
inside of the project directory. Probably, the better configuration
would be to create a PHP-FPM pool specifically for Wallabag and chroot
it to the Wallabag folder. For another time, maybe.