View source for PartKeepr on Debian "Stretch"

This is an example step-by-step installation of PartKeepr-1.4.0 on Debian 9 "Stretch."

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 walks through setup of a complete standalone PartKeepr server, covering installation and setup of the operating system, software dependencies, and PartKeepr itself. It will run in a Virtual Machine (VM) and will use Debian 9 "Stretch" Linux, Apache/2.4, PHP 7.0, and MariaDB 10.1 (a fork of MySQL). To keep the system minimalistic, this installation will produce a command line based system, not 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. This example can be followed closely or just used as a rough guide.

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. Furthermore if you are installing on a physical machine, rather than a virtual one, you must take the necessary precautions to avoid losing any other operating systems or data on that machine that you wish to keep.

As of PartKeepr-1.4.0, 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 (PHP 7 preferred) with certain extensions



== Choose User Names and Passwords ==


You will need to select some usernames and passwords for various parts of the system:
* Your user name and password for logging into Linux.
* A MySQL / MariaDB database root password.
* A password for the PartKeepr user that will be created in the database system.

This example will use admin for the Linux username, so if you are using something different you will need to adjust commands shown here accordingly.

Make a note of the passwords used in some secure fashion, so that you will be able to access and administer the system in the future!


== Create Virtual Machine and Install Debian Linux ==


Our example uses Debian Linux 9 "Stretch" as the operating system. This version of Debian was released on June 17, 2017 and is planned to be supported for five years [https://www.debian.org/News/2017/20170617].

If you are using a different operating system, 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.

An older version based on Debian 8 "Jessie" can be found here: [[PartKeepr on Debian "Jessie"]]

Following are the steps we performed:

Obtain an appropriate installation image for your system from debian.org [https://www.debian.org/distrib/]. We used debian-9.0.0-amd64-netinst.iso, which is the 64-bit PC version. The -netinst suffix indicates it is the small installation image, which downloads a smaller file than the full DVD, but requires an Internet connection during installation to fetch the packages it requires. By the time you read this, there may be a newer version available.

The Debian installation guide is here:
[https://www.debian.org/releases/stable/installmanual]

Create a virtual machine in your virtualization platform of choice. In this example, our virtual machine is created in VMware and has 1 virtual processor core (64-bit), 2GB RAM, 100GB hard drive space, although this is probably far more than is really required.

On our virtual machine, we created two virtual network interfaces. The first is set up to share the host machine's Internet connection via NAT. The second 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.

Make sure your virtualization software will boot the virtual machine from the CD or DVD image downloaded earlier and start it up.

On the initial screen of the installer, select "Advanced options." On the next screen, select "Expert install." (If there are different options for 32-bit and 64-bit, choose the one appropriate for your hardware.)

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 "Load installer components from CD," accept the defaults in the screen that follows, and wait for the installer to load the default components.

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 and Domain Name, choose something appropriate (in our example, we chose "PartKeepr" for the hostname and "localdomain" for the domain name).

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 and add your user account 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.

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 installing Debian Linux on physical hardware alongside other operating systems, you will need to make the appropriate adjustments in this step to avoid clobbering your other systems (and you should have a reliable backup just in case). 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, decline to scan for additional CDs or DVDs (No), 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 source repositories (Yes). 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.

Depending on how your system will boot, you may have to 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 (especially if you are installing Debian Linux alongside other operating systems), 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 setup the system and 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 first are not configured. If this is the case, /etc/network/interfaces needs to be adjusted.

Note that past versions of Debian Linux, such as Jessie, used names like eth0, eth1, etc., for network interfaces. This has been changed to a new naming method. To determine what the interface names are, it may be helpful to:

 $ cat /etc/network/interfaces

Look for a line like iface ens33 inet dhcp. In this case, ens33 is the name of one of our interfaces. Then:

 $ ls /proc/sys/net/ipv4/conf

and/or:

 $ ls /proc/sys/net/ipv6/conf

and look for similar names. In our case, the entries were: all, default, ens33, ens34, and lo. We conclude that ens34 is the name of our other network interface.

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 ens33
 iface ens33 inet dhcp

 allow-hotplug ens34
 iface ens34 inet dhcp

Add as many as necessary (one pair for each ethernet network interface), paying attention to use the correct interface names.

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: [https://wiki.debian.org/NetworkConfiguration] and [https://www.slightfuture.com/how-to/debian-dns-resolv].

 $ sudo nano /etc/dhcp/dhclient.conf

Add a line at the end of the file to specify additional DNS nameservers. In our example we will use public DNS nameservers provided by Google by adding this line at the end of the file:

 append domain-name-servers 8.8.8.8, 8.8.4.4;

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 (ens33 and ens34 in our case) have inet addresses.

 $ cat /etc/resolv.conf

Check the output to verify that there are valid name servers, including any you may have added in the previous step.

 $ ping -c 4 www.google.com

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


== Install Prerequisites ==


Update and upgrade:
 $ sudo apt-get update
 $ sudo apt-get upgrade


=== Install Apache ===

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 curl and ntp ===

Install curl and ntp:

 $ sudo apt-get install curl ntp


=== Install MariaDB ===

 $ sudo apt-get install mariadb-server mariadb-client

MariaDB is a fork of MySQL. As such you will see the name MySQL in many places.

When installation of MariaDB completes, run the mysql_secure_installation script to secure the database. This step allows you to set the database root password, disable remote root login and anonymous users, etc.

 $ sudo mysql_secure_installation

When prompted to "Enter current password for root (enter for none):" press Enter.

When prompted to "Set root password," press Y and Enter, then enter the desired password.

When prompted to "Remove anonymous users," press Y and Enter.

When prompted to "Disallow root login remotely," press Y and Enter.

When prompted to "Remove test database and access to it," press Y and Enter.

When prompted to "Reload privilege tables now," press Y and Enter.

You will need administrative privileges on the database to set it up for PartKeepr. We opted to create a database user authenticated by our system-level user credentials. For more information on this step see: [https://stackoverflow.com/questions/39281594/error-1698-28000-access-denied-for-user-rootlocalhost]. Note that we modified the commands to also create a PartKeepr user in the database.

In the steps below, replace admin with your username.

 $ sudo mysql -u root

 mysql> USE mysql;
 mysql> CREATE USER 'admin'@'localhost' IDENTIFIED BY '';
 mysql> GRANT ALL PRIVILEGES ON * . * TO 'admin'@'localhost';
 mysql> UPDATE USER SET plugin='unix_socket' WHERE User='admin';

Now we will set up a user and database for PartKeepr. Replace insert_password_here with a suitable password for the PartKeepr user. You will need to provide this password to PartKeepr later:

 mysql> CREATE USER 'PartKeepr'@'localhost' IDENTIFIED BY 'insert_password_here';
 mysql> UPDATE USER SET plugin='mysql_native_password' WHERE User='PartKeepr';
 mysql> FLUSH PRIVILEGES;
 mysql> CREATE DATABASE PartKeepr CHARACTER SET UTF8;
 mysql> GRANT USAGE ON *.* to 'PartKeepr'@'localhost';
 mysql> GRANT ALL PRIVILEGES ON PartKeepr.* TO 'PartKeepr'@'localhost';
 mysql> EXIT;

 $ service mysql restart


=== Install PHP and Extensions ===

 $ sudo apt-get install php php-apcu php-apcu-bc php-curl php-gd php-intl php-ldap php-mysql php-dom php-xml


=== 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 ens33 to share the host machine's Internet via NAT and we set ens34 to host only. Because we will run our web browser in the host, we look for the inet address of ens34.

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-1.4.0.tbz2

If using curl:

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


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

 $ sudo tar -xjvf partkeepr-1.4.0.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. This can be verified by typing:

 $ cat /etc/passwd | grep www

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-1.4.0
 $ sudo find /var/www/partkeepr-1.4.0 -type d -exec chmod 770 {} +
 $ sudo find /var/www/partkeepr-1.4.0 -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 this section:

 <Directory /var/www/partkeepr-1.4.0>
 	AcceptPathInfo on
 	Require all granted
 	AllowOverride All
 </Directory>

Exit nano with ctrl+x 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-1.4.0/web.

 # DocumentRoot /var/www/html
 DocumentRoot /var/www/partkeepr-1.4.0/web

Exit nano with ctrl+x 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-1.4.0/web

Exit nano with ctrl+x 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: [http://php.net/manual/en/timezones.php]

Exit nano with ctrl+x 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 MariaDB ===

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 /setup. For example, if the virtual machine's network address is 192.168.10.10, type 192.168.10.10/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-1.4.0 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-1.4.0, that file will be located at /var/www/partkeepr-1.4.0/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-1.4.0/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-1.4.0/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, we select MySQL. Set the fields as follows:

* Database Hostname: localhost
* Database Name: PartKeepr
* Database Username: PartKeepr
* Database Password: enter the password you selected earlier for the PartKeepr database user

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!):

 0 0,6,12,18 * * * www-data /usr/bin/php /var/www/partkeepr-1.4.0/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-1.4.0/app/console in the PHP interpreter under the www-data user's account.

Note that the line shown above is slightly different than what PartKeepr told us to use. The "www-data" field was added. This is because cron on Debian systems allows you to specify under which user's account the cron job should run. It must run as the same user that runs the web server.

Exit nano with ctrl+x and save the file.

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

From here, you can log in and begin using PartKeepr.