I love Bookstack, actually I think it’s one of the best wiki project existing.

It’s well documented, it works like charm, the developer is very active (and he’s also a very kind person, which has nothing to do with the software, but it’s always a pleasure interact with him) and it has very nice features:

• a nice and responsive design
• drafts autosave
• MFA out of the box
• diagrams.net integration

It also works perfectly fine in a docker container, technically the official project do not offer a container image, but there are two groups building them and they’re referred directly in the official documentation.

Recently I started to sort things out on my beloved Raspberry PI 5, in particular I’m moving services so I can reverse proxy them on a single Apache httpd instance (you know I still love Apache :D ), today I moved around Bookstack, in particulare I did two things:

1. change Bookstack hostname (for example from https://site.domain.tld to https://newsite.domain.tld )
2. make Bookstack work under a specific url context (for example https://site.domain.tld/bookstack instead of https://site.domain.tld ).

On my environment I’m using the LinuxServer.io docker image, so check the project site for details, and also I’m using docker compose, if you’re not familiar with it start using it for Reorx’s sake.

Backup

First of all take a damn backup, it’s mandatory.

Seriously I’m not joking.

Stop the containers

cd /data/docker/bookstack ; docker compose down

Backup files with a simple tar, restic, kopia, whatever you want, but DO IT!

cd /data/docker/ ; tar -cpzf /backup/bookstack-backup.tar.gz bookstack

Change Bookstack hostname

This process is documented on the Bookstack documentation (LINK), but still I decided to mention it because the procedure is a little bit different on a docker container, so it’s worth spent a few words about it.

First of all you have to change the APP_URL configuration variable, in case of a docker container it’s enough to change the environment variable on the docker-compose.yaml file, so open the file and change the variable to the new url

Now you must replace the old url from the database record with the new one using the bookstack:update-url command, in case of a docker container you must identify where’s the Laravel framework artisan file and launch it accordingly to the documentation.

docker exec -it bookstack php /app/www/artisan bookstack:update-url https://site.domain.tld https://newsite.domain.tld

After that clear the cache using

docker exec -it bookstack php /app/www/artisan cache:clear

Restart the docker container to change the environment variable you previously changed with the new url.

cd /data/docker/bookstack ; docker compose down ; docker compose up -d

Done, now your Bookstack instance should be reachable to the new url.

Change Bookstack root context

This change is a little bit tricky, because it involves some webserver changes.

First of all you must repeat the same process used for changing the url hostname of your Bookstack instance, this time including the context you want to use (for example /bookstack ).

Let’s quickly review the steps:

1) Change the APP_URL environment variable in the docker-compose.yaml (APP_URL=https://newsite.domain.tld/bookstack in this case)

2) Replace the url in the database using the bookstack:update-url

docker exec -it bookstack php /app/www/artisan bookstack:update-url https://newsite.domain.tld https://newsite.domain.tld/bookstack

3) Clear Bookstack cache

docker exec -it bookstack php /app/www/artisan cache:clear

4) Restart the docker container to change the environment variable you previously changed with the new url.

cd /data/docker/bookstack ; docker compose down ; docker compose up -d

Now you must review the webserver configuration inside your docker container, in case of the LinuxServer.io container there’s a nginx instance running inside the container, you can fine its configuration inside the /config/nginx/ directory inside the container.

If you followed the LinuxServer.io recommendations the /config directory should be a persistent volume (or a persistent path on your docker host), so any changes in the nginx configuration files should not be lost in case of a container restart.

In my case the config persistent volume is located in the /data/docker/bookstack/bookstack-config directory, so the nginx configuration is located in the file /data/docker/bookstack/bookstack-config/nginx/site-confs/default.conf.

Apply this patch

wget https://tasslehoff.burrfoot.it/pub/bookstack-nginx.patch ; \
patch /data/docker/bookstack/bookstack-config/nginx/site-confs/default.conf < bookstack-nginx.patch

Reload nginx configuration

docker exec -it bookstack nginx -s reload

Done, now your Bookstack instance should work at the new url https://newsite.domain.tld/bookstack

Recently I had a nice discussion on a forum on Kubernetes, for me the topic was crystal clear since the first time I used it and understood a little bit about it, but sometimes this discussion repeats on the web, so I decided to save here my thoughts on this, so I can copy and paste it in the future to save some time…

I have to be honest, my experience with K8s always been the 2nd image…

When I first came in contact with K8s my first impression was: “this is a fantastic tool to solve a problem… that almost nobody has”.

Now after two years working as a sysadmin in a company extremely involved in K8s, where I learned, teached, installed, configured, fixed countless K8s cluster my conclusion is: “this is a fantastic tool to solve a problem… that almost nobody has”.

At the end of the day, despite all the buzzwords the main reason to use K8s is scalability, horizontal scalability, there are no other advantages.

Some people thinks the main advantage is the declarative approach to infrastructure, but I disagree; first of all K8s does not force you to use a declarative approach, you can do everything with an imperative approach (kubect create bla bla bla… instead of using manifests).
On the other hand also docker (with docker-compose) can do the same, so why use a more complex tool (K8s, which is much more complex) to get the same result?

No K8s approach, its objects, its object relations everything is built with one purpose: scalability.

But honestly who cares about scalability?

If you’re a Facebook or Amazon or Microsoft of Google obviously it’s important and necessary.
If you’re a big campus lab with thousands of services or the Cern datacenter or other examples like that it’s important and almost necessary.

But even if you’re a big company honestly nobody gives a damn about scalability from a technical point of view.

Ok HA is important, maybe distribute load on a couple of nodes makes things easier for maintenance, but in most of the case if you plan a good maintenance window and announce it correctly to your users nobody cares.

On top of that scalability works well with stateless applications, but in reality in my experience (25 years in the IT industry) stateless applications are the exception, the vast majority of applications are stateful, so it’s not that simple to scale up and make everything work ok, you have to deal with a lot of details (persistent data, sticky sessions, concurrency and so on…).

So what’s the end result in so many companies?

K8s cluster everywhere (in a lot of case single node “clusters”) requested by some manager who don’t understand a thing about them, installed by some consultant company, completely abandoned and managed by nobody, with a couple of applications made with statefulsets or deployments with only one replica.

Logging management is a pain in the a$$, backups are a paint in the a$$, and everybody hopes it will run forever because nobody in the company knows how to deal with problems, exceptions, certificates expirations and so on…

The very opposite of the basic principle that should be applied in the IT, the KISS principle.

I just finished my first long ride on my bike (~ 2000 Km in 4 days) after 3 years of riding and more than 42k Km on the bike.

This was my fist group ride, until now I done all the 42k Km on my bike as solo rider.

It was a blast, I really enjoyed it but I also made mistakes and learned a lot, here’s some suggestions I can give as a newbye:

Don’t underestimate the “emulation effect” of the group.

Riding with people with more experience or more powerful bikes than you means that you’ll always try to keep the pace and ride like them: DON’T DO IT.
Keep your pace, ride at your speed, nowadays everyone has a phone which can work as a GPS navigator, maybe you’ll arrive later, that’s fine, but don’t underestimate the danger of riding at other people speed or pace.

Riding comfort matters.

Riding is hard for your body, don’t feel ashamed to stop to make you butt rest or to drink some water.

Long rides are like marathons, completing them is already like winning them.

Consider riding underpants (like these https://www.revitsport.com/us_en/motorcycle-pants-airborne-2-black ) and a comfort seat, usually riding gear is not comfortable and will scratch you skin after hours of riding, those underpants prevent this and will help with sweat.

A mistake I did was using underwear like this and the last days they caused me a huge pain on the edges because of rubber bands, small details like that can make a huge difference between a comfortable and fun ride and a constant pain in the ass (literally).

Take it easy, take your time

Don’t let the trip consist only in riding riding and again riding, otherwise you’ll end up exhausted.

If you found a stunning panoramic view stop and enjoy it, this will help your mind and your body.

If you want to take a photo stop and do it, remember: it’s not a race, it’s an holiday.

Start early, end early.

Usually I hate to get up early in the morning, but in a riding trip it’s the best solution.

Riding when you’re exhausted is too dangerous, you’ll risk mistakes that can be fatal; also consider that, as I said, riding is hard for your body, you’ll see very soon that even if you to sleep early (early than your usual habits) you’ll fall asleep in no time.

Get a good H2O protection gear.

Riding wet is an awful experience, that may seem obvious but it still true.

Get an helmet with pinlock

Ride early in a chilly morning or under the rain may cause your visor to get foggy.

Buy a helmet with a pinlock ready visor, and mount the pinlock, it’s the cheapest and most effective way to prevent this problem, it will make a huge difference, believe me.

Stop when you don’t enjoy riding anymore.

After hours and hours of riding is perfectly normal to not feel the ride enjoyable, that’s the moment you have to stop, take a break or find a place to rest, don’t force you to reach your goal for the day.

For the series “Thing I can’t live without” (or maybe “dear stupid mega corporate, this is how you should make your software setup”) I would like to suggest NVCleaninstall.

I have to admit I’m an Nvidia hater since the good old 3dfx days, but sometimes it happens to install of update drivers on other people’s computer that sadly use Nvidia GPUs.

NVCleaninstall is the only way to install or update Nvidia GPU drivers without installing bloatware and useless services, it’s simple to use, it’s clean and straightforward and can automatically check when new drivers are release, it’s a small gem every Nvidia user should know and use.

You’re welcome.

Just a quick tip to remind myself how to properly commit some data that needs to be encrypted with git-crypt.

First of all, if you need to change files pattern or paths of the data you need to encrypt you have to change your .gitattributes file:

1. git clone the encrypted repo
2. modify .gitattributes
3. git add & git commit
4. git push

In case you only have to change encrypted files or add new encrypted files

1. git clone the encrypted repo
2. unlock it with “git-crypt unlock <key path>”
3. verify files are not crypted with “git-crypt status ; file <encrypted files path>”.
   If they’re shown as “data” it means they’re still encrypted (unless they’re binary data by themself)
4. add/change files
5. git add & git commit
6. git-crypt lock
7. verify files are encrypted before pushing repo with “git-crypt status ; file <encrypted files path>”
8. git push

After all this you can blame yourself for turning one more simple thing into a hard one.