Moving the DB server

Relocating the DB server requires only a minor change on the web server. The following steps are necessary

1. login to the web server either as root, or as another user through, ssh
2. open the site config file for editing (you will need to use sudo if not logged in as root). The path below is correct as at 2014-04-04 however may change if the web server is subsequently moved.

   nano /var/www/vhosts/blincref.com/httpdocs-app/assets/implementation/impl.config
   

3. locate the database configuration section and update the IP address of the fmpHost

   fmpHost                                                         = xxx.yyy.zzz.aaa
   

4. save and exit nano

All future requests will use the new FileMaker host.

Placing the website offline

If the website needs to be placed into offline mode (for example to allow time for a DB server migration) take the following steps

1. login to the web server either as root, or as another user through, ssh
2. open the site config file for editing (you will need to use sudo if not logged in as root)

   nano /var/www/vhosts/blincref.com/httpdocs-app/assets/implementation/impl.config
   

3. locate the 'other configuration' section and set the site mode to offline.

   siteMode                                                        = offline
   

4. save (CTRL-O) and exit (CTRL-X) nano

All requests from that moment forward will receive an error message saying that the site is offline and that they should try again at a later time.

To put the site back online, follow the above steps, however set the siteMode as online

siteMode                                                        = online

Moving the web server

sudo apt-get install apache2
sudo apt-get install php5
sudo apt-get install php5-curl
sudo apt-get install mysql
sudo apt-get install php5-mysql
sudo apt-get install libapache2-mod-auth-mysql

Create the folders

Give Apache ownership of them

Create apache config files

Enable rewrite engine

These instructions assume that installation is to be on a *nix web server, running Apache, and that the person following them is able to access the server via ssh (either as root, or as a user who has sudo permissions).

Before beginning ensure that you have Apache and PHP installed and functional. You will also need to create the virtual host (if multiple sites are being hosted on the same server) which will be used for the site. Either use the VPS hosting providers control panel (if such a thing exists) or ​this guide may be useful if you are unfamiliar with this process. Also ensure that

• the relevant SSL certificate has been installed in the Apache config for the server/virtual host
• AllowOverrides is enabled for the virtual host to allow the .htaccess file which will be deployed with the site to be parsed
• The following (optional in some Apache/PHP installs) modules are installed and enabled
  • Apache: mod_rewrite (used to map URLs to the index.php front controller)
  • PHP: cURL (required to interact with the remote FMS)

Both the installation and future site maintenance deployments make use of SVN to install and update source code on the server. Ensure that the SVN command line client is installed

svn --version

should return a version number, and must also show a module which is able to handle the https scheme. Sample output will look like:

svn, version 1.6.11 (r934486)
   compiled Jun 23 2012, 00:44:03

Copyright (C) 2000-2009 CollabNet.
Subversion is open source software, see http://subversion.tigris.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).

The following repository access (RA) modules are available:

* ra_neon : Module for accessing a repository via WebDAV protocol using Neon.
  - handles 'http' scheme
  - handles 'https' scheme
* ra_svn : Module for accessing a repository using the svn network protocol.
  - with Cyrus SASL authentication
  - handles 'svn' scheme
* ra_local : Module for accessing a repository on local disk.
  - handles 'file' scheme

If an error is returned, then the SVN client will need to be installed. Use

sudo apt-get install subversion

For the remainder of these instructions it is assumed that the web root for the server/virtualhost is

/var/www/app.blincref.com

this may vary depending on the specific version of *nix in use, other virtual hosts etc. Amend subsequent commands to match the specific path to the web root. Note also that the default user for Apache is www_data, however that may not be the case on the server in question, again, amend subsequent commands as required.

1. find the current version of the site from the subversion repository
   • browse to ​https://svn.msdev.co.uk/blinc/release/ (you will have to login using the credentials supplied)
   • in the list identify the most recent version. Note that the list sorts alphabetically, not numerically, so the latest version may not be at the bottom. At the time of writing 2014-04-04 the current version is 1.11
2. make the web root writeable by PHP

   sudo chown www_data:www_data /var/www/app.blincref.com
   

3. save the attached install.php file to the web root folder. This can be achieved using

   wget https://trac.msdev.co.uk/blinc/raw-attachment/wiki/ServerMigration/install.php -O /var/www/app.blincref.com/install.php
   

4. edit the install.php file to set three parameters in the file, the supplied SVN username and password, and the current version identified in step 1 above.

   nano /var/www/app.blincref.com/install.php
   
   and modify:
   
   $svnUsername                                            = '** SVN Username **';
   $svnPassword                                            = '** SVN Password **';
   $version                                                = '** Current version **';
   

5. in a web browser navigate to the install.php file, e.g. ​https://app.blincref.com/install.php. This will export the necessary code into place on the server. It may take several minutes to complete.
6. once complete delete install.php

   rm /var/www/app.blincref.com/install.php
   

7. create the local configuration file by copying the default file

   sudo cp /var/www/app.blincref.com/assets/implementation/impl.config.default /var/www/app.blincref.com/assets/implementation/impl.config
   

8. modify the config file to set the correct FileMaker host (as for moving the DB server above). Depending on other changes which may also have occurred it may be necessary to adjust other settings in this file, for example the configuration for sending mail.
9. create the certificate and upload folders and give PHP write access to them

   sudo mkdir /var/www/app.blincref.com/assets/certificates
   sudo mkdir /var/www/app.blincref.com/assets/uploads
   sudo chown www-data:www-data /var/www/app.blincref.com/assets/certificates
   sudo chown www-data:www-data /var/www/app.blincref.com/assets/uploads
   

10. browse to the site to confirm that all is working: ​https://app.blincref.com

If using OVH and a failover IP address enable the IP alias

ifconfig eth0:0 192.168.1.6 up

Troubleshooting

The most likely problems will arise form file permissions or module configuration.

1. If the install fails, ensure that you have given the (correct) web user write access to the document root folder
2. if you receive errors when attempting to run the app, firstly ensure that you have set the DB server parameters correctly, and that they have been saved to the config file.
3. depending on the server configuration other error messages may be displayed on screen to indicate where issues may lie. If not (which they shouldn't be - all errors should be turned off in the php.ini file on a production server), add the following to the top of index.php immediately after <?php:

   error_reporting(E_ALL);
   ini_set("display_errors", 1);
   

   • you may see (many) depreciation errors, these can be ignored
   • you should see the cause of the actual problem, likely a php fatal error, this should indicate where the cause of the problem is, and Google should be able to provide a solution to that issue.