PartKeepr on Debian "Jessie"

Example step-by-step installation of PartKeepr-0.79.

PartKeepr is a web-based application. Multiple users can access a single copy of PartKeepr through any modern web browser. As such, to get PartKeepr working, you will need to set up a "server."

This example will set up a standalone server whose sole responsibility is to provide PartKeepr. It will run in a Virtual Machine (VM) and will use Debian-8.3.0 (Jessie) Linux, Apache/2.4.10, PHP 7.0.3, and MySQL 5.5.47. To keep the system minimalistic, this installation will not include a full graphical desktop environment. Your system need not be exactly as described here. PartKeepr is flexible and you can set up your installation as you wish.

Disclaimer: This step-by-step example is provided merely for informational purposes, in the hopes of helping others to get going with PartKeepr. If you follow the steps described here, you do so entirely at your own risk. Be especially mindful that if your system will be exposed to the Internet or any untrusted network, you must consult with a security expert before deploying PartKeepr or any other technology.

As of PartKeepr-0.79, the system requirements for the server are:

• A UNIX-like system (Linux, BSD, etc.)
• Apache or nginx
• MySQL or PostgreSQL
• PHP 5.6 or higher with certain extensions

Create Virtual Machine and Install Debian Linux

Our example uses Debian Linux 8.3 "Jessie" as the operating system. If you are using something else, such as a different Linux distro, a BSD system, etc., please install it per its installation guide and skip to the next section.

If using a different version of Debian Linux or if your hardware/network scenario differs from ours, you can use the following steps as a general guide but you may have to make adjustments.

Obtain the ISO file (CD-ROM image) of Debian Linux 8.3 "Jessie" from debian.org. We used debian-8.3.0-amd64-i386-netinst.iso, which includes 32- and 64-bit versions.

The Debian installation guide is here: [1]

Following are the steps we performed:

Create a virtual machine in your virtualization platform of choice. In this example, our virtual machine is created in VMware and has 2 virtual processors, 2GB RAM, 100GB hard drive space, although this is probably far more than is really required.

Important: On our virtual machine, we created two virtual network interfaces. The first (which will become eth0 in Linux) is set to share the host machine's Internet connection via NAT. The second (eth1) is set to host-only (and could later be bridged to our home or office ethernet network instead). We configured it in this manner so that we could test the system from a web browser in the host machine.

On the initial screen of the installer, select "Advanced options." On the next screen, select "64 bit expert install" (if using a 64-bit system) or "Expert install" if using a 32-bit system.

In the following menu, select "Choose language." In the next several screens, choose the appropriate language and locale, such as English, United States, United States en_US.UTF-8. In the screen that asks for additional locales, you may press Tab and select Continue if additional locales are not needed.

Select "Configure the keyboard" and select the appropriate keymap, such as American English.

Select "Detect and mount the CD-ROM" and accept the defaults in the screens that follow.

Select "Detect network hardware."

Select "Configure the network." It should be safe to accept the defaults in the screens that follow. However, if you have configured the virtual machine with multiple network interfaces like we did, it is important that the one with Internet access be set as the primary interface. For Hostname, choose something appropriate (in our example, we chose PartKeepr).

Select "Set up users and passwords." In the following screens, accept shadow passwords (Yes) and do not allow login as root (No). When root login is disallowed, the installer will install sudo, create a user account, and add it to "sudoers" to allow administrative commands to be entered via "sudo." Note that the installer will not do this if you choose to allow root login. Provide a full name for the new user, followed by a username for the account and a suitable password. In our example, we will set the full name and the username to "admin" but you can use any valid username. Note that you will have to adjust several Linux commands we show later on to reflect the username you choose. Enter an appropriate domain name (in our example, we entered localdomain).

Select "Configure the clock." Accept NTP (Yes) and accept the default NTP server. Then select your time zone.

Select "Detect disks" followed by "Partition disks." Since this is a virtual machine, this example will use "Guided - use entire disk." If you are co-installing Debian Linux alongside other operating systems, you will need to make the appropriate adjustments in this step to avoid clobbering your other systems. In this example, we accept all the defaults and choose "Yes" when asked to write the changes to disk.

Select "Install the base system." The installer will begin copying files, which could take some time depending on your system's speed. When asked which kernel to install, accept the default (in our case, linux-image-amd64). When asked which drivers to include in initrd, choose the default (generic: include all available drivers).

Select "Configure the package manager." In the screen that follows, accept using a network mirror (Yes). For protocol, choose http. Select a mirror near you (in our case, United States). Select a Debian archive mirror (in our case ftp.us.debian.org). Leave the proxy field blank (unless you know of a need to enter something here). The installer will spend some time retrieving files from the mirror. When asked, decline to use non-free software (No) and contrib software (No). Accept receiving security updates (from security.debian.org) and release updates.

Select "Select and install software." The installer will retrieve some more files. When presented with "Software selection," uncheck "Debian desktop environment" and "print server." Check "web server," "SSH server," and "standard system utilities." The installer will then fetch and install those components.

Select "Install the GRUB boot loader on a hard disk." In our example, Debian Linux is being installed on a virtual machine where it is the sole operating system. If your system differs, make the necessary adjustments here. We selected to install GRUB boot loader to the master boot record (Yes), selected /dev/sda as the device for boot loader installation, and declined forcing GRUB to the EFI removable media path (No).

Select "Finish the installation." When asked whether the system clock is set to UTC, we selected Yes. When prompted, remove the installation media and allow the virtual machine to reboot.

Correct Possible Issues

At this point you should have a working text-based Debian Linux system and are ready to install PartKeepr's prerequisites.

Login using the username and password you supplied to the installer.

Verify the "sudo" command works

$ sudo ls
[type your password]

If sudo does not work at all, or if the system says that "this incident will be reported," then you probably opted to allow root login when you installed. In that case, the installer did not install sudo or set up your user account to have sudo access. To correct this, you must switch to the root user, install sudo, add your username to the sudo group, exit from the root user, log out, and log back in.

$ su
[type the root password]
# apt-get install sudo
# adduser yourusername sudo
# exit
$ logout

Now log back in and sudo should work.

Fix /etc/network/interfaces

If the virtual machine has multiple network interfaces, it is possible that additional interfaces beyond the eth0 are not configured. If this is the case, /etc/network/interfaces needs to be adjusted.

Edit /etc/network/interfaces using nano:

$ sudo nano /etc/network/interfaces

Make sure there is a pair of lines as shown below for each ethernet network interface:

allow-hotplug eth0
iface eth0 inet dhcp

allow-hotplug eth1
iface eth1 inet dhcp

Add as many as necessary (one pair for each ethernet network interface), paying attention to change the eth numbers.

Exit nano with ctrl+x and save changes.

Fix /etc/dhcp/dhclient.conf

If you have issues where domain names are not resolved correctly (for example, you cannot ping www.google.com) then you may have to adjust your resolver settings. However, if you add lines to /etc/resolv.conf, those will be overwritten the next time you reboot or the next time dhclient runs. What worked for us is to add a line to /etc/dhcp/dhclient.conf, instructing it to use additional nameservers beyond what is provided by the DHCP server.

Note: If you are using a more full-featured installation of Debian (with a desktop environment), you may have NetworkManager and will need a different solution. See the following pages: [2] and [3].

$ sudo nano /etc/dhcp/dhclient.conf

Add this line at the end of the file, assuming eth0 is the Internet-facing network interface:

append domain-name-servers 4.2.2.1, 4.2.2.2, 4.2.2.3;

Exit nano with ctrl+x and save changes.

Reboot Linux

$ sudo shutdown -r now

When done rebooting, log back in and verify that all network interfaces are working and that the resolver works.

$ ip addr

Check the output to verify that all network interfaces (eth0, eth1, etc.) have inet addresses.

$ cat /etc/resolv.conf

Check the output to verify that there are valid name servers.

$ ping -c 4 www.google.com

Verify that ping works. Use ctrl+c to stop pinging.

Install Prerequisites

Prepare additional repositories

To use a newer version of PHP than is available with Debian's default repositories at the time of this writing, we add the DotDeb.org repositories:

Edit /etc/apt/sources.list using nano:

$ sudo nano /etc/apt/sources.list

Add the following lines at the end:

# DotDeb.org (extra repo with up-to-date packages)
deb http://packages.dotdeb.org jessie all
deb-src http://packages.dotdeb.org jessie all

When ready, press ctrl+x, answer "y" to the save prompt, and press Enter once again to accept /etc/apt/sources.list as the filename.

Get the DotDeb key and add it to your trusted keys keyring:

$ gpg --keyserver keys.gnupg.net --recv-key 89DF5277
$ gpg -a --export 89DF5277 | sudo apt-key add -

This is per the instructions here: [4]

Update and upgrade:

$ sudo apt-get update && sudo apt-get upgrade

Install Apache, MySQL, PHP

Apache will already be installed if you checked the option for it in the Debian Linux installer. If not, you can install it now:

$ sudo apt-get install apache2 apache2-doc

Install the other needed packages

$ sudo apt-get install curl ntp mysql-server mysql-client php7.0 php7.0-apcu php7.0-curl php7.0-gd php7.0-intl php7.0-ldap php7.0-mysql

When prompted, enter a suitable password for the MySQL "root" user.

Verify Apache is working

Determine the IP address of the virtual machine. You can type "ip addr" at a prompt and look for inet. In our virtual machine, we set eth0 to share the host machine's Internet via NAT and we set eth1 to host only, so we look for the inet address of eth1.

Launch a web browser in the host computer or on another computer with network connectivity to the virtual machine and enter the IP address. If you see Apache2 Debian Default Page with the message "It works!" then Apache is working. Otherwise, you will need to determine if a problem is caused by lack of network connectivity to the virtual machine or some misconfigured or omitted item from above.

Install and Setup PartKeepr

Obtain PartKeepr

Return to the virtual machine and download PartKeepr using either wget or curl:

Make sure you are in your home directory:

$ cd

If using wget:

$ wget https://downloads.partkeepr.org/partkeepr-0.79.tbz2

If using curl:

$ curl -O https://downloads.partkeepr.org/partkeepr-0.79.tbz2

Extract to a suitable location. In this example, we will place PartKeepr in /var/www/partkeepr-0.79

$ sudo tar -xjvf partkeepr-0.79.tbz2 -C /var/www

Modify PartKeepr directory and file permissions

PartKeepr needs the ability to write into certain directories and files within its installation.

We opted to set our PartKeepr installation's ownership and permissions so that its files and directories are owned by our "admin" user and the "www-data" group. We set the files readable and writable by the owner and group, but inaccessible to everyone else. It is necessary to give the www-data group write access to the files because PartKeepr requires the ability to modify its files.

The "www-data" group already exists in the Debian system. If you are using a different operating system, you may need to check which group owns the web data files and make the appropriate adjustments in the commands below.

We configured ownership and permissions as follows:

$ sudo chown -R $(whoami):www-data /var/www/partkeepr-0.79
$ sudo find /var/www/partkeepr-0.79 -type d -exec chmod 770 {} +
$ sudo find /var/www/partkeepr-0.79 -type f -exec chmod 660 {} +

In the first command, the $(whoami) will be replaced by your admin user's username, in case you opted to use something other than "admin" earlier.

Setup Apache

Enable the Apache modules userdir and rewrite:

$ sudo a2enmod userdir rewrite

Modify Apache settings:

$ sudo nano /etc/apache2/apache2.conf

Add these lines:

<Directory /var/www/partkeepr-0.79/>
	AllowOverride All
</Directory>

Exit nano with ctrl+c and save the file.

Modify Apache web root:

$ sudo nano /etc/apache2/sites-available/000-default.conf

Comment the line DocumentRoot /var/www/html by placing a # in front of it and add a similar line which points to /var/www/partkeepr-0.79. (Later, this will be changed to /var/www/partkeepr-0.79/web, but due to a problem when PartKeepr-0.79's Setup is invoked initially, we begin without the web directory.)

# DocumentRoot /var/www/html
DocumentRoot /var/www/partkeepr-0.79

Exit nano with ctrl+c and save the file.

Make the same change to /etc/apache2/sites-available/default-ssl.conf:

$ sudo nano /etc/apache2/sites-available/default-ssl.conf

# DocumentRoot /var/www/html
DocumentRoot /var/www/partkeepr-0.79

Exit nano with ctrl+c and save the file.

Modify PHP configuration:

$ sudo nano /etc/php/7.0/apache2/php.ini

Locate the line:

max_execution_time = 30

You can find it by pressing ctrl+w (Where Is) and typing max_execution_time. Change the 30 to 120:

max_execution_time = 120

Locate the line:

;date.timezone =

Uncomment it by removing the initial semicolon and add an appropriate time zone:

date.timezone = America/Los_Angeles

In our case, we used America/Los_Angeles. You can look up the possible time zone settings in the PHP manual here: [5]

Exit nano with ctrl+c and save the file.

Reload Apache configuration:

Configuration changes made above will not take effect until Apache is instructed to reload its configuration files:

$ sudo service apache2 restart

Setup PartKeepr and MySQL

In a web browser on the host machine or other machine with network connectivity to the virtual machine, type the virtual machine's network address followed by /web/setup. For example, if the virtual machine's network address is 192.168.10.10, type 192.168.10.10/web/setup.

At this point, the PartKeepr setup wizard should appear in your web browser.

If the PartKeepr setup wizard does not appear, one of several issues might be preventing it. There might not be network connectivity between your browser machine and the PartKeepr machine. There might be something missing or misconfigured in the steps above. Double-check the configuration. Verify you know the virtual machine's IP address with the "ip addr" command. Restart Apache with the "sudo service apache2 restart" command. Or you can reboot the virtual machine with "sudo shutdown -r now" instead.

Initially, the Welcome screen is shown. Click "Next" to show the Prerequisites screen.

In the Prerequisites screen, PartKeepr performs tests to verify that it can run successfully. If any errors are shown, click the Show Errors button and try to correct the issues described in the popup window that appears. Most problems will be caused by having a version of PHP that is too old, not having all needed PHP modules installed, missing or incorrect web server settings, or incorrect ownership and/or permissions of the partkeepr-0.79 directory.

Once PartKeepr is satisfied that its prerequisites are fulfilled, click Next to show the Authentication Key screen.

PartKeepr will ask for a code from the app/authkey.php file. If PartKeepr was installed in /var/www/partkeepr-0.79, that file will be located at /var/www/partkeepr-0.79/app/authkey.php. It will be necessary to show that file's contents, copy the auth key code (which is a string of letters), and paste it into the Authentication Key field in the web browser. In our setup, we cannot copy and paste directly because the virtual machine does not have a graphical desktop environment and we are running Setup from a web browser on the host computer. This leaves us with two options. We can either type:

$ cat /var/www/partkeepr-0.79/app/authkey.php

to display the code and then manually type it into the web browser, or we can SSH into the virtual machine. If the host machine has SSH, then you can open a terminal on the host machine and type a command like the following, replacing "admin" with your username on the PartKeepr VM and replacing "ip_address" with the PartKeepr VM's IP address:

$ ssh admin@ip_address

Then, once in a SSH session, type the same "cat" command as above:

$ cat /var/www/partkeepr-0.79/app/authkey.php

This will show the authorization key and allow you to copy it from your graphical terminal and paste it into the web browser.

Don't forget to log out of the SSH session by pressing ctrl+d or typing "logout" at the prompt.

Once the code is pasted or typed, click Next to show the Existing Configuration screen. Since this is a new installation, there will be no configuration found.

Click Next again to show the Database Parameters screen. Select Database Type (in our case, MySQL). Check the option to "Show commands to create the database." This will display SQL statements that are incomplete at the moment. As you fill out the other fields, the SQL statements will update accordingly. Set the fields as follows:

• Database Hostname: localhost
• Database Name: PartKeepr
• Database Username: PartKeepr
• Database Password: choose a suitable password

At this point, the SQL commands will be shown. Do not click Next yet.

Return to the virtual machine and start the MySQL shell as the MySQL "root" user (which is not the same thing as the UNIX/Linux root user):

$ mysql -u root -p

You will be prompted for the password you set when you installed mysql with apt-get earlier. If all goes well, you will be presented with a "mysql>" prompt. Enter the commands shown in PartKeepr's setup exactly as shown, paying attention not to omit the semicolons at the end of each command.

After entering those commands, you can verify that a database titled PartKeepr was created:

mysql> SHOW DATABASES;

One of the rows displayed should be PartKeepr.

You can verify that a MySQL user called PartKeepr was created by typing:

mysql> SELECT User FROM mysql.user;

One of the rows displayed should be PartKeepr.

To exit the MySQL shell, type quit.

mysql> quit

This should print "Bye" and place you back at the system shell.

Returning to the web browser, click Next to show the Setup (1/2) screen. This should test for database connectivity successfully. Afterwards, it will set up the database schema, part units, default footprints, SI prefixes, default units, and default manufacturers. Then, it should check for existing users. Since this is a new installation, there will be no existing users yet.

Click Next to show the User Data screen. On this screen, create the PartKeepr administrator user. Enter a suitable username, password, and email address. Be particularly careful when typing the password as there is currently no field to type it a second time as a confirmation.

Below, in Authentication Method, there is a choice of HTTP Basic and WSSE. WSSE is described as more secure. However, some users experience problems with inability to log in due to the date and time not being correct in the virtual machine. Our virtual machine is configured to use NTP so WSSE should work. You can check the virtual machine's current date and time using the "date" command:

$ date

If the date and time displayed are correct, then WSSE will probably work in your scenario. If you encounter problems, then you can rerun setup later and switch to HTTP Basic.

Click Next to show Setup (2/2). This will set up the admin user, save configuration files, move legacy files, and warm up the cache. The last step takes a few moments. Wait for it to complete and then click Next to show the Setup Complete screen.

At this point, PartKeepr will ask you to set up a cronjob. Cron is a program that schedules tasks to run at given intervals. Please note that under Debian, cron jobs are configured a bit differently than other systems. Rather than add a line to /etc/crontab, we add a file in /etc/cron.d as follows:

$ sudo nano /etc/cron.d/partkeepr

Type the following contents, being particularly careful to copy the spaces and commas exactly. (Spaces separate between fields, whereas commas allow placing multiple items into a single field -- but only if there are no spaces after those commas!) Important: replace "admin" with your username:

0 0,6,12,18 * * * admin /usr/bin/php /var/www/partkeepr-0.79/app/console partkeepr:cron:run

This means: At minute 0 of hours 0, 6, 12, and 18, on all days of the month, on all months, on all days of the week, execute the file /var/www/partkeepr-0.79/app/console in the PHP interpreter under the admin user's account.

Note that the line shown above is slightly different than what PartKeepr told us to use. The "admin" field was added. This is because cron on Debian systems allows you to specify under which user's account the cron job should run. We prefer to run it as a regular user rather than root. Remember to replace "admin" with the Linux username you created during Linux installation.

Exit nano with ctrl+c and save the file.

In the web browser, click Submit to apply the settings and go to the PartKeepr login screen.

Change the web server root

Earlier, we stated that we would change the web server root to /var/www/partkeepr-0.79/web, so it would not be necessary to type the additional "/web" when accessing PartKeepr through a web browser. At this time we will make that change:

$ sudo nano /etc/apache2/sites-available/000-default.conf

Locate the line DocumentRoot /var/www/partkeepr-0.79 and add /web to the end of it:

DocumentRoot /var/www/partkeepr-0.79/web

Exit nano with ctrl+c and save the file.

Make the same change in /etc/apache2/sites-available/default-ssl.conf

$ sudo nano /etc/apache2/sites-available/default-ssl.conf

Exit nano with ctrl+c and save the file.

Restart Apache to reload its configuration files and make changes take effect:

$ sudo service apache2 restart

In the web browser, enter the virtual machine's IP address. If everything has been configured correctly, you will see the PartKeepr Login screen. Try logging in with the username and password you created in the setup screen above.