Skip to content

2. Installing

Jump to bottom
Jean J. de Jong edited this page Jun 2, 2022 · 38 revisions

The back-end for operating is a web server (Apache, PHP, MySQL, and a virtual host setup pointing to the public sub-folder...). You need MySQL version 8.0 or greater (or MariaDB 10.3 or greater), supporting virtual columns and window functions.

These instructions are provided for Ubuntu Server editions. They have been tested with Jammy (22.04). You may need to adapt them for other Linux distributions.

NOTE that the user interface has only been developed and tested with recent FireFox releases (60 is known to not work). There may be artifacts with other web browsers - share your issues with us.

0. Automated installation

A fully unattended installation script is available for a fresh install of a vanilla Ubuntu 20.04 server. Download it on your server, make it executable, and run it with sudo:

wget https://github.com/jjdejong/phpip/raw/master/doc/install-phpip-ubuntu.sh
chmod a+x install-phpip-ubuntu.sh
sudo ./install-phpip-ubuntu.sh

You may then skip the rest of the below instructions up to the "Upgrading" section. If something doesn't work, check the below details.

You can only execute this script once, on a freshly installed Ubuntu system. If it fails, you need to finish the installation manually from the point at which it failed, using the instructions below.

1. Installing the required packages

Make sure your software is up to date and add the Universe repository. In a console, type:

sudo add-apt-repository universe
sudo apt update
sudo apt upgrade

1.1. Apache, PHP and MySQL

Install these and other needed dependencies (Git and Composer) as follows:

In a console, type:

sudo apt install apache2 apache2-utils mysql-server mysql-client php php-common libapache2-mod-php php-cli php-mysql php-json php-readline php-xml php-curl php-zip php-mbstring unzip git composer

Launch Apache and MySQL at startup:

sudo systemctl enable apache2
sudo systemctl enable mysql

Create the database phpip accessible with all privileges by user phpip with password phpip (change that in production!):

echo "CREATE DATABASE phpip DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER phpip@localhost IDENTIFIED BY 'phpip'; GRANT ALL PRIVILEGES ON phpip.* TO phpip@localhost; SET GLOBAL log_bin_trust_function_creators = 1;" | sudo mysql

(This command assumes that mysql has been freshly installed with default options, where no password is required for root when running mysql with sudo.)

The command SET GLOBAL log_bin_trust_function_creators = 1; is for MySQl >= 8, when binary logging is enabled. You probably also need to add the following to the my.cnf configuration file: log_bin_trust_function_creators = 1;

1.2. phpIP

The code can be installed anywhere with the virtual host approach, but it makes sense to install it in /var/www/html/phpip. Create the folder and change its owner to yourself so that you don't need to use sudo to work there:

sudo mkdir /var/www/html/phpip
sudo chown <your login> /var/www/html/phpip

Clone the phpip Git repository to the folder /var/www/html/phpip:

git clone https://github.com/jjdejong/phpip.git /var/www/html/phpip

Install Laravel's dependencies:

cd /var/www/html/phpip
composer install

Create an .env file with your database credentials. You can copy the provided .env.example file (and tailor it later):

cp .env.example .env

Generate a fresh Laravel configuration:

php artisan key:generate
php artisan config:clear

Set some write permissions for the web server:

chmod -R g+rw storage
chmod -R g+rw bootstrap/cache
chgrp -R www-data storage
chgrp -R www-data bootstrap/cache

2. Configuring Apache

2.1 Quick start and check

To run a quick test, point your browser to http://localhost/phpip/public.

You should see a cover page with a login link. You won't get past that, because no tables or users have been installed yet in MySQL.

2.2 Virtual host in Apache

This is maybe the most complex configuration section.

  • In the console, type:
sudo nano /etc/apache2/sites-enabled/phpip.conf
  • Paste the following in nano's edit window:
<VirtualHost *:80>
    ServerName phpip.local
    DocumentRoot /var/www/html/phpip/public
    ErrorLog /var/log/apache2/phpip-error.log
    CustomLog /var/log/apache2/phpip-access.log combined
</VirtualHost>
<Directory /var/www/html/phpip/public>
    Options Indexes MultiViews FollowSymLinks
    DirectoryIndex index.php
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>
  • Enable mod_rewrite in Apache:
sudo a2enmod rewrite
  • Save and reload Apache:
sudo systemctl restart apache2
  • You then need to create a DNS entry mapping name "phpip.local", i.e. the value of parameter ServerName in the above VirtualHost definition, to the IP address of your server. If this is obscure to you, the simplest is to add the following line in the "hosts" file of the workstations that will access phpIP:
<your server's IP address>    phpip.local

On Windows workstations, the "hosts" file is usually in: c:\windows\system32\drivers\etc\hosts

On Macs and Linux workstations, it is located in /etc/hosts.

Now point your browser to http://phpip.local.

You should see the cover page and login link again. You still won't get past that, because you have no database yet.

  • If you are accessing phpIP on the Internet, you'll want to use HTTPS. The virtual host configuration file would then look something like this with Let's Encrypt certificates (change all occurrences of example.com to your domain):
<VirtualHost *:80>
  RedirectPermanent / https://phpip.example.com/
</VirtualHost>

<VirtualHost *:443>
  SetEnv HTTPS On
  ServerName phpip.example.com
  DocumentRoot /var/www/html/phpip/public
  SSLEngine on
  SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
  SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
  SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
  SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
  SSLProtocol All -SSLv2 -SSLv3
  ErrorLog /var/log/apache2/phpip.example.com-error.log
  CustomLog /var/log/apache2/phpip.example.com-access.log combined
  <IfModule mod_headers.c>
    Header always set Strict-Transport-Security "max-age=15552000; includeSubDomains"
  </IfModule>
</VirtualHost>

<Directory /var/www/html/phpip/public>
  Options Indexes MultiViews FollowSymLinks
  AllowOverride All
  Order allow,deny
  Allow from all
</Directory>

3. Database

3.1 Starting a new database

  • Run php artisan migrate --seed This creates a blank database with basic configuration. You're ready to go with the credentials phpipuser:changeme.

  • For playing around with sample data, further run

php artisan db:seed --class=SampleSeeder

3.2 Migrating an existing v1 installation

Migrate the v1 database

  • Backup the phpip MySQL schema.
  • Upgrade the phpip schema with the script provided in /database/migrations/sql.
  • Apply further updates to the tables using Laravel's "migration" process, i.e. run php artisan migrate from the root folder - this will apply any new script present in database/migrations since last running that command.

Migrate the passwords

You need to update the password field of your users. Logins are based on the login and password fields in the actor table only (they are no longer replicated in the MySQL users table). Authorizations will be implemented through the default_role field of the users.

The passwords are hashed with bcrypt instead of md5, and don't use a user-provided salt. So you need to change all the md5+salt passwords of v1 to bcrypt ones.

  • Using the password reset functionality of the UI: make sure your users have emails and configure your mail service in the .env file. If you have no mail service, set MAIL_DRIVER=log. In the login screen, use the "Reset password" function. A reset mail will be sent with a link to change the password. If you have no mail service the reset mail body is logged in /storage/logs/<latest file>. Copy the reset link you find there in your browser, and you're done.
  • Or changing the password hashes manually in the actor table with a bcrypt hash. You can generate a bcrypt hash using the command
php -r 'echo password_hash("your password",PASSWORD_BCRYPT) . "\n";'

To fire a quick test, run php artisan serve, and point your browser to http://localhost:8000.

3.3 Upgrading

The software is under continuous development and improvement, so a rolling release model is used. To stay up to date, regularly pull the new commits by running the following commands in the phpip installation folder (e.g. in /var/www/html/phpip):

  • git pull and
  • composer install (only required when you see the composer.json and composer.lock files updated)

The database structure may be updated too, so you need to apply the new migration scripts appearing in database/migrations. When you see such files being added, run the following in the installation folder, which will apply the latest scripts:

php artisan migrate

Upgrading to PHP 8.1 on Ubuntu 20.04 as of commit e9db842 (9/02/2022)

Ubuntu 20.04 does not provide PHP 8. Running composer install will fail. You need to run the following commands to upgrade PHP from a PPA repository:

sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt -y upgrade
sudo apt -y remove php7.4* php-*
sudo apt -y install php php-common libapache2-mod-php php-cli php-mysql php-json php-readline php-xml php-curl php-zip php-mbstring composer
cd /var/www/html/phpip
rm -rf vendor/*
composer install

(Run the two last commands with the account that owns the phpip folder, or with sudo.)

3.4 Production

In production, you don't need all the packages used for development. Run the following to delete those:

composer install --optimize-autoloader --no-dev
Clone this wiki locally