Moving partkeepr into docker

I like Partkeepr; it’s simple and powerful and manages my component inventory. But, it can be a bit of a faff to install, hence my previous guide to getting it working on Ubuntu. Things have moved on a bit for me, and this hassle is simply taking far too much of my precious time. Hardware fails now and then, and I’ve had to rebuild my Partkeepr hosting a few times. I was looking around for other solutions, but nothing could import my data, and the thought of manually repopulating thousands of part entries didn’t exactly fill me with excitement.

When poking around on dockerhub, I decided to search for some pre-build Partkeepr images, and as you’d probably expect, I found several promising candidates. Since I follow solid backup practices, I had a backup of my Partkeepr data and config directories and a dump file of the SQL database. I powered down the faulty machine and plugged the data disk into a spare box, which was sitting around for some other duties. The machine is an old Dell PC, which hosts my Calibre server and runs my backups. It doesn’t do much most of the time, and having already got Docker installed, it was obvious to try to wedge Partkeepr on there as well.

(optional) Ease of Management: Use Portainer

I like web-based management systems, so long as the hardware has enough resources to run with the associated overheads comfortably. The simplest solution is to upgrade the RAM to as much as possible without overthinking it. There are only so many command-line syntaxes I can keep track of! The first container I set up after installing Docker is Portainer. This makes configuring and managing running containers a breeze and doesn’t consume resources noticeably.

Installing Portainer on the command line is simple enough. For Linux:

# sudo docker volume create portainer_data

# sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce

This first command creates a docker volume for the data, and the second command will download the image if you don’t already have it, bind the data volume to that created earlier, map the network management port and run the image in the background.

Pointing your web browser at port 9443 will open the account creation page. Once you’re logged in, take some time to familiarise yourself with the GUI. It will be worth your time, I promise!

Install a Partkeepr Image (and a database)

The image I chose to use was f0rc3/partkeepr by Marc Ole Bulling, which has an associated GitHub page with plenty of instructions. I’ll reproduce those here with some additional notes. This is paired with a Partkeepr-compatible database of your choosing. I chose the official MariaDB image and pressed on.

First, you need to prepare your data area. I decided to use an external hard disk so I could plug it into something else if the machine died. Switch to this data area now.

# cd /path/to/data-area

I copied my old data (hosted in partkeepr/data and partkeepr/app/config) to ./data and ./config I also copied my database dump file here. Next, I wanted to locate my MariaDB data here as well, so I created a folder for that:

# mkdir config
# mkdir data
# mkdir db

Pulling down the images is simple enough:

# sudo docker pull f0rc3/partkeepr:latest
# sudo docker pull mariadb

Next, create and run the database:

# sudo docker run -p 127.0.0.1:3310:3306 --name partkeepr-mariadb -v /path/to/data-area/db:/var/lib/mysql -e MARIADB_ROOT_PASSWORD=<root passwd> -d mariadb

This doesn’t create the database (although you could do that here) but only sets the root password. We’ll create the database manually as we set up the Partkeepr installation. This way, we can ensure we can access the database to fix problems!

The last docker command will install and set up the Partkeepr web server in preparation for the configuration stage.

# docker run -d -p 127.0.0.1:7155:80 --name partkeepr-web -v /path/to/data-area/data:/app/data/ -v /path/to/data-area/config:/app/app/config -d f0rc3/partkeepr:latest

If you want to run Partkeepr on a different port, change the 7155 to whatever you have free.

Setup Partkeepr

Now, we can wander over to the Portainer server, check our two containers are running, and access the shell for the web server container.

If you have existing data, check you have data in /app/data. You should see four folders: files, iclogo, images and temp. These should all be owned by www-data:www-data.

Also, your Partkeepr configuration will be in /app/app/config. This will contain several YAML files, as well as parameters.php and parameters_setup.php. Again, check the ownership is www-data:www-data.

If you do not have existing data, create the app/data and app/app/config paths and set the correct ownership.

Finally, we need to make a copy of the authentication key in the file /app/app/authkey.php

# cat /app/app/authkey.php

Save the key for later.

Now, it’s time to run the setup process. Browse over to port 7155 (or whatever you mapped port 80 to when you set up the image) on the server host, and kick off the setup:

http://localhost:7155/setup

Click through until you get to the database setup page. You need to adjust this to point to the MariaDB container, fill in the required Partkeepr user details, and create the database.

The database host field must point to the docker internal network address of the MariaDB container. You can find this in the Portainer container view page or via the command line:

# sudo docker ps  # lookup the container ID field for mariadb and paste below
# sudo docker inspect <mariadb container ID>

This will print out a big pile of JSON text, but usually, at the bottom of the “Networks” section, there will be a tag for “IPAddress,” which is the value we seek.

Perhaps a more straightforward way would be to open the shell for the MariaDB container and do:

# hostname -I

Anyway, now we need to open a shell in the MariaDB container:

# sudo docker exec -it partkeepr-mariadb sh

We explicitly set the MariaDB root password earlier, so now we can manually go in, set up our users and databases, and reload any dump files we have, if applicable. In the shell, open the MariaDB client:

# mariadb -u root -p

After entering the MariaDB root password, we can get the database set up:

MariaDB> CREATE DATABASE partkeepr CHARACTER SET UTF8;
MariaDB> CREATE USER 'partkeepr'@'localhost' IDENTIFIED BY 'partkeepr';

This assumes you haven’t disabled password-based authentication in the MariaDB configuration, but by default, this should work.

Our example creates a user ‘partkeepr’ with the password ‘partkeepr’, but you can use whatever suits you as long as it matches the Partkeepr setup information on the database page.

Next, we need to grant full access permissions to this user:

MariaDB> GRANT USAGE ON *.* TO 'partkeepr'@'localhost' IDENTIFIED BY '<your partkeepr password>';
MariaDB> GRANT ALL PRIVILEGES ON partkeepr.* TO 'partkeepr'@'localhost';
MariaDB> FLUSH PRIVILEGES;
MariaDB> EXIT;

Next, if you have an existing database dump file, we can send that into the database we just created.

Still inside the MariaDB container shell, we cat the dump file on STDIN:

# cd /path/to/sql-dump-file.sql
# mariadb -u root -p < sql-dump-file.sql

To verify if this worked, open the MariaDB client again and poke around the database:

# mysql -u root -p
MariaDB> SHOW DATABASES;
MariaDB> USE partkeepr;
MariaDB> SHOW TABLES;

This should list several data tables with familiar-sounding names. If it does, we’re all set.

This is pretty much the end of the process. If you have existing data, click next a few times. It will identify your existing user and prompt you to log in. Now would be an excellent time to look around your parts and check the correctness of the images and document links! If you’re setting up a new database, you’ve more work to do. But that’s your problem 😀