How to install php-login-one-file on Ubuntu 12.04 LTS

This tutorial will show you how to install the one-file version of php-login.net‘s login script (see the full GitHub repository here) on a standard Ubuntu server – in a very short and a very detailed way.

THE VERY SHORT TUTORIAL:

If you prefer a short tutorial, do it like this: Copy the content of the php-login-one-file folder to your server’s web root (or whereever you want to have it) and run _install.php (in the _installation folder), which will create a database file in the project’s root folder. Make sure you have PHP 5.3.7+ with SQLite extension and PDO installed (see long tutorial).

THE VERY DETAILED TUTORIAL:

THE BASIC REQUIREMENTS:

1. A server, in this tutorial we’ll use Ubuntu 12.04 LTS as the operation system.
2. Apache installed on the server.
3. PHP 5.3.7 or higher installed on the server (this includes PHP 5.4+ and PHP 5.5+). PHP introduced some hashing algorithms (that are used in this script) in version 5.3.7, so you definitely need this. This tutorial will show you how to check your PHP version and how to upgrade PHP.
4. You should be able to access your server via SSH.
5. You should know the basics of how a server works, how to login via SSH, how to use the linux command line and how to copy files to your server.

THE FURTHER REQUIREMENTS:
Find out which version of PHP your server runs

This script does not use MySQL, but a simple SQLite database file (which is in this case just a file), so we need to make sure that the installed version of PHP is able to handle SQLite:

Create a file called phpinfo.php on your local computer and put the following stuff in there:

<?php
phpinfo();

The function phpinfo(); shows the entire configuration and settings of PHP, so it’s perfect for inspecting and finding out what your installed version of PHP can do and what not. I think it’s a good idea to create such an phpinfo.php on every new server you set up.

Copy the file to your server’s web root folder, usually /var/www/ ! For easily accessing a server via SSH in Windows 7/8 I can recommend WinSCP and Putty. WinSCP let’s you log in via your SSH credentials (username and password OR via SSH key file) and look at your server like in a FTP tool while Putty is a simple, but effective command-line tool. WinSCP will automatically open Putty (already connected to your server) when you log in.

When you have moved the phpinfo.php file to your web root, open your browser and go to

http://www.yourdomain.com/phpinfo.php

You’ll see something like this:

Is your PHP version 5.3.7 or higher ? Fine, then let’s go on ! If not, then you are using a very old version of PHP that should be updated instantly.

By the way, you can also find out your installed PHP version by doing this on the linux command line (but we did it the above way to check if your server displays php files correctly ;)

php -v

THE FURTHER REQUIREMENTS:
Update the PHP version (if older than 5.3.7)

Updating PHP is a big topic, so let’s do it the quick way. To update PHP, log into your server and do this on the command line (or “shell” or “bash”, whatever you call it):

sudo apt-get update

to let your system (beside some other stuff) check for updateable software, then do this to upgrade PHP:

sudo apt-get --only-upgrade install php5

After this is done, restart the Apache server with:

sudo service apache2 restart

Now check the installed version of PHP with a simple:

php -v

Is it 5.3.7 or higher now ? Perfect ! If not, then you should contact your server provider, hoster etc. and ask for an update or simply get a modern server somewhere else. It’s 2013, ladies, and the 5.3 branch of PHP has officially reached the End of Life, which means no more updates for this branch. Seriously, there is really no good reason to use a 4 year old version of PHP.

THE FURTHER REQUIREMENTS:
Install SQLite extension (if not installed)

This version of the login script does not use a MySQL database, it simply creates a little file in a subfolder of your web project. One file for each database table by the way. This kind of database is called SQLite, and PHP needs a special SQLite extension to work with this stuff. To check if the SQLite extension is installed, search for this box on your phpinfo.php output screen:

Does it say sqlite in the right column ? If not, install the PHP SQLite extension with

sudo apt-get install php5-sqlite

(if you have problems, check How to enable SQLite3 for PHP on StackOverflow)

and restart the Apache server (to load the new extension) like this

sudo service apache2 restart

To prove everything is installed correctly, reload your phpinfo.php screen and have a look. It should look like this:

THE INSTALLATION PROCESS:
Copy the script to your server

This step is easy: Delete the phpinfo.php from your server (as it is not necessary anymore and will give potential attackers informations about your server) and copy the contents of the php-login-one-file folder to your web root, usually /var/www/.

THE INSTALLATION PROCESS:
Making the “database” folder writeable

By default the www folder on your web root path /var/www/ might not be writeable by PHP. Folder/file rights on linux are a huge and complex topic, so we only do it the quick way here, so let’s go to /var/ on the command line by doing

cd /var

and changing the right of the “database” folder with

sudo chown -R www-data:www-data www

By the way, if this does not work, try setting full acess to the folder. Note that 777 is insecure as it gives too much rights on the folder, but for development purposes it’s okay.

sudo chmod 777 www

THE INSTALLATION PROCESS:
First run, creating the database

Open your browser and start the installation function inside the script by calling

http://www.yourdomain.com/_installation/_install.php

which will create the user database file within the root folder. The script is now ready to go under your web address:

http://www.yourdomain.com/

Make sure to delete the _install.php file now ! To always have a look into your one-file database simply call _debug.php. Also make sure to delete this file when you are running a real app!

IMPORTANT SECURITY NOTICE:

In the default setup the database – which is only a simple users.db file – can be downloaded directly. To prevent this, change the path of your database file! A path that is not accessable by public is perfect. The .htaccess in the project does not work in every setup.

SOME FINAL THOUGHTS

Your app is now running. To be honest, this tutorial was a little bit overcomplicated. When you are reading this post you probably want to create a very simple tool, based on a one-file login system, so you probably have rent a simple and pre-configured server that already has a modern version of PHP and the PDO / SQLite extension installed. Usually copying the script files to the server and calling the install script is everything you have to do.

SOME WORDS ABOUT LOCAL & REMOTE DEVELOPMENT

It’s always a good decision to develop LOCALLY, which means directly on your own computer, or even better, within a virtual machine hosted on your system. Usually, developing on a live server on the web might be critial, because your tools might have no or weak passwords, your app is in development and therefore attackable, or simply because you just mistyped a bash command and your server now tries to download the entire web. This can kill you if you pay for every gigabyte of traffic. Believe me ;)

When developing locally, you could install PHP, MySQL etc by hand or use a pre-combined and pre-configured easy-to-handle development bundle, like Ampps [Win, Mac], EasyPHP [Win], WampServer [Win], SecureWAMP [Win] or even Xampp [Win, Mac, Linux]. A lot of people seems to use Xampp, but I wouldn’t recommend this, as it’s by far the worst of all those.