INTRODUCTION
The VBoard Account Management System (AMS) is a PHP web application which sits on a MySQL database. This feature enables this web platform to run on Linux or Windows servers that supports PHP/MySQL.
The requirements of AMS installation are listed below.
- MySQL 5.6
- A web server (nginx, apache, iis)
- PHP 5.6+ (lower than PHP7)
- PHP-CLI 5.6+ (lower than PHP7)
- Virtual Hosts or dedicated web server (modify DocumentRoot)
There are two steps to follow for installation of Account Management System.
- Installation of web server
- Installation of AMS
Further sections will explain how to install AMS and upgrade the version of AMS. You can use following programs in those sections.
- XAMPP: During the installation of web server on a Windows server, XAMPP will be used. You can download XAMPP installation file from Apache Friends. We suggest you to download the version that supports PHP 5.6. You can use “Shell” button that is on XAMPP control panel to open Shell to run shell commands.
- PuTTY: You can use PuTTY when you need to run shell commands to perform installation and version upgrade on Linux server from Windows system via remote connection. You can download PuTTY installation file from PuTTY.
- WinSCP: WinSCP is used for performing secure file transfer from Windows to remote Linux server. You can download WinSCP installation file from WinSCP. PuTTY is automatically installed with the installation of WinSCP. To open PuTTY go to “Commands” menu then click “Open in PuTTY” in WinSCP.
INSTALLING WEB SERVER ENVIRONMENT
In this section, installation of web server environment which is the first step of AMS installation will be explained. Once the environment is installed, there is no need to set up environment again for further AMS installations or upgrades. If you already have web server running with PHP/MySQL, you can skip this section and go to the next section (Install AMS).
The most common and recommended installation is “LAMP” (Linux, Apache, MySQL and PHP). Installation is also possible to install on Windows by using XAMPP or by using IIS.
In following subsections, installing environment on Linux and on Windows is explained.
INSTALL ON LINUX
In this section, web server installation on Linux will be explained. Ubuntu 14.04LTS or Ubuntu 16.04LTS is recommended. There are some notes further down for other distributions; however the whole procedure is very similar.
We need to setup Apache and PHP. This procedure will be explained for Ubuntu 14.04 LTS and for other distributions in the following subsections.
Ubuntu
In this subsection, installation of Apache, MySQL and PHP5 will be explained. Follow the steps that stated below respectively and enter related commands.
- Install Apache 2.x Webserver
sudo apt-getinstall apache2
- Install MySQL Server
sudo apt-getinstall mysql-server
- Install PHP5
sudo apt-getinstall php5 php5-mysql php5-gd
- Restart Apache 2 Webserver if necessary
sudo /etc/init.d/apache2 restart
- On Ubuntu, DOM, libXML, gettext and JSON extension is already compiled on PHP5.
CentOS 5.x / Redhat RHEL 5.x
In this subsection, installation of web server on CentOS 5.x/Redhat RHEL 5x will be explained. Apache, MySQL and PHP5 installations are the same. You can follow the steps that mentioned in previous subsection.
Since JSON extension is not include in CentOS 5.x or Redhat RHEL 5.x, you should install it. You can follow these steps to install:
- Install JSON PHP Extension
yum install php-devel
If you have more than 8MB of memory limit for PHP, install with PEAR
pear install pecl/json
If you have less than 8MB of memory limit for PHP, PEAR failed to install… Use PECL
pecl install json
- Active JSON extension
vim /etc/php.d/json.ini
# JsonExtension
extension=json.so
- Save file and restart the Apache webserver
/etc/init.d/httpd restart
INSTALL ON WINDOWS
In this section, web server installation on Windows system by using XAMPP will be explained. You can follow the steps that are stated below.
- Download the XAMPP installation file from Apache Friends. Installing PHP 5.6 supported version is suggested.
- Run XAMPP installer.
- Select the components that you want to install. Make sure Apache, MySQL, and phpMyAdmin components are selected then click “Next” button on the screen that appears.
- After you pressed “Next”, below screen appears for installation folder selection. By default, XAMPP installs to “c:\xampp”. Unless you need to move it somewhere else, then that’s a good choice. If you do select a different directory, remember it for the next step when we install AMS.
- The installer will now run, and extract a number of files to the folder you select to install XAMPP. When the extraction of files is completed, press “Finish” button to complete installation.
- After the installation run XAMPP Control Panel. It should open up, and if everything went to plan, look like the screen shot.
- At this point, you need to press Start buttons for both Apache and MySQL. As you click each, your screen should now look like the below:
- If you want to start Apache and MySQL automatically when starting XAMPP Control Panel, click “Config” button on top right of the XAMPP Control Panel. Then check Apache and MySQL boxes in “auto start of sections module” section and then press Save.
Before we install AMS, we need to configure a few things on XAMPP to make it a bit more secure.
- From XAMPP Control Panel, click “Config” button, on the first line next to Admin button as seen in following screenshot and click “phpMyAdmin” to open “config.inc.php” file.
- In “config.inc.php” file, change the first line below with the second line.
$cfg[‘Servers’][$i][‘auth_type’] = ‘config’
$cfg[‘Servers’][$i][‘auth_type’] = ‘http’
- After changing the line and saving the file, Restart Apache and MySQL.
- You will also need to configure “php.ini” file, which can be viewed by the context menu shown in the figure above, during installing CMS.
- In the XAMPP Control Panel, click the “Admin” button next to MySQL. This will load a web browser and take you to an application called PHPMyAdmin that was installed along with XAMPP. It will let us setup a password for the “root” MySQL account. The “root” account on MySQL has privileges to add new users, create databases etc. So needs to have a strong password.
- From the PHPMyAdmin screen, click “User Accounts” at the top of the screen. You’ll see the database users that exist already listed. We’re interested in the one called “root” that has “localhost” in the “Host” column. Click the blue “Edit Privileges” symbol to the right of the word “Yes”.
- On top of page, you find the “Change Password” box. Enter a new password in both the password boxes and click “Go”. On a piece of paper, write down “MySQL Admin User details. We’ll need these later when installing AMS.
Now we are ready to extract AMS package.
INSTALLING AMS
In this section installation of AMS will be explained. It is assumed that a web server running with PHP and MySQL is available. If not, please look into previous section.
Installation of AMS on web server is performed according to following steps.
- Placing AMS package
- Starting AMS Installation
- Pre-Requisities
- Creating The Database
- Creating Administrator Account
- Final Configuration
- Complete
PLACING AMS PACKAGE
In this subsection, transferring AMS installation files to web server and web server configurations will be explained.
- Now it is required to transfer AMS installation package to server. When the AMS installation archive is extracted, the extracted archive should look like below:
- In the simplest of web server configurations the name of this folder will be the name of the URL you use to access the AMS. For example if you name folder as AMS, the URL of the AMS will be http:\\localhost\AMS
That process will be explained in detail for Windows and Linux in following subsections.
After extracting the AMS archive into appropriate location, we are ready to start the AMS installation
PLACING AMS PACKAGE ON UBUNTU
Follow the instructions stated below respectively.
- Copy AMS directory (e.g. ams-v1.0.zip) to your user’s home folder (/home/<user-name>/) in your web server.
- Extract the zip you downloaded inside your webserver’s document root (eg /var/www/vsign) and ensure the webserver has permissions to read and write those files:
cd /var/www
sudo unzip ~/ams-v1.0.zip
sudo mv ams-v1.0 ams
- Change transferred folder’s owner as www-data
sudo chown www-data:www-data -R ams
- Make a directory for the server library. Make sure the webserver has permission to write to this location:
sudo mkdir /ams-library
sudo chown www-data:www-data -R /ams-library
PLACING AMS PACKAGE ON WINDOWS
Transfer AMS installation directory (e.g. ams-v1.0.zip) to web server then extract to web server’s DocumentRoot location. For example, if DocumentRoot “C:/xampp/htdocs” and folder that you extract to is “ams” then associated location will be “C:/xampp/htdocs/ams”.
STARTING AMS INSTALLATION
Navigating to http:\\your.server\path (e.g. http:\\localhost\ams) will automatically start the installation.
The installation is in a wizard format that contains 5 steps in total. The wizard will guide the installer through the process of installing AMS.
PRE-REQUISITES
Please follow the steps below:
- After navigating to http:\\your.server\path, the below page appears.
- This page contains a detailed check list of all the items required for a successful installation. Each item will have either:
- A tick – the item is present and correct
- An exclamation mark – the item is present but may not be configured correctly
- A cross – the item is missing
- Any items with an exclamation mark or a cross should be corrected. When any item with an exclamation mark or a cross is solved, the Retest button must be used to run this step again. Exclamation mark or cross stem from PHP modules that did not configured correctly. This problem can be solved by either activating missing modules in your “php.ini” file related to your server’s PHP settings or setting some values according to minimum configuration settings. Necessary solutions can be found on the installation page. To sum up, check the necessary extensions are whether active or not as stated below.
extension=php_curl.dll
extension=php_fileinfo.dll
extension=php_gd2.dll
extension=php_gettext.dll
extension=php_mysql.dll
extension=php_mysqli.dll
extension=php_pdo_mysql.dll
extension=php_soap.dll
extension=php_intl.dll
extension=php_openssl.dll
- Also set following parameters to minimum value as stated.
max_execution_time=120 (min. 120 sn.)
post_max_size=16G(min. 128M)
upload_max_filesize=16G(min. 128M)
- After changing the line and saving the file (ini), don’t forget to restart Apache.
For Linux run following command
sudo service apache2 restart
For Windows, press “Start/Stop” buttons located on xampp control panel.
- Once all the items are ticked press Next button to advance.
CREATING THE DATABASE
After pre-requisites step is passed, the below page appears.
The AMS can install into a new database, or an existing one. We recommend a new database. Because, AMS does not prefix its table names and may conflict with content in an existing database. The choice for a new or existing database can be made by switching between the two available tabs.
Whether you chose an existing database or a new one, the installer will need to collect some information about that database to allow the AMS to connect, read and write.
The installer will need the following information:
- HostThe host name for your MySQL installation – in the majority of cases this will be “localhost”.
- Admin UsernameThe “root” user name for your MySQL installation. This is only used for the installation and is only required if you have asked the installer to create a new database.
- Admin PasswordThe “root” password. This is only used for the installation and is only required if you have asked the installer to create a new database.
- Database NameThe name for the AMS database. Give a name you choose.
- Database User name: The user name for the AMS to use to connect to the database. Give a name you choose – usually this can be the same as admin username.
- Database PasswordThe password to use to connect to the database. Give a password you choose – usually this can be the same as the admin password
After you fill the form, press Next button. The installer will now create / populate database for AMS. You should see a series of dots appear on the screen as this happens. It can take a few moments to complete.
CREATING ADMINISTRATOR ACCOUNT
After creating database step is passed, the following page appears:
Each installation will require at least one “Super User” level Administrator to manage the system, apply upgrades and configure the advanced settings. Just give any user name and password you choose.
This user name and password should be kept safe as it will be required when the installation is complete.
FINAL CONFIGURATION
After creating administrator account step is passed, the following page appears:
Fill in the blanks on the appeared screen, in order to set last settings of AMS.
- Library Location: Location that AMS stores its documents and media files. This directory is generated when placing previous installation files.For example, “/ams-library/” for Linux, “C:\ams-library” for
- Server Key: This key will be used to authorize screens that trying to connect to AMS. A key is generated automatically while installation. After installation is completed, the AMS Key can be viewed or can be changed via Settings page of AMS web interface.
COMPLETE
The installation is now complete and the system is ready to log in.
Now you can use user name and password of administrator account you created during installation process.
UPGRADING AMS VERSION
In this section, the steps for upgrading AMS version will be explained. In following subsections, you can follow the detailed process of the version upgrade on Windows and Linux system.
UPGRADING ON LINUX
- You can follow the next steps with the following assumptions.
MySQL administrator ID: mysqladmin
AMS database name: amsdb
Server’s <DocumentRoot>directory: /var/www/html
AMS installation directory: <DocumentRoot>/ams
New AMS installation archive: ams-new.zip
- (Optional) Clone your existing AMS database and give necessary permissions. It is possible to upgrade the version without cloning however it will be harder to undo the process in case of an error occurrence. To see how to clone your database, check out the next section “CLONING DATABASE”.
- Backup the file “settings.php” which located in your existing AMS installation directory. For example, you can copy it to your user’s home folder.
sudo cp settings.php ~
- Backup your existing AMS database.
mysqldump –u mysqladmin –p amsdb> ~/amsdb.sql
- Transfer new version’s installation archive to the server. For example transfer the archive to your user’s home folder below:
/home/<your-username>/
- Copy AMS new version’s installation files to your existing AMS installation directory. You can perform following steps in order to do that.
cd /var/www/html
sudo unzip ~/ams-new.zip
sudo chown www-data:www-data -R ams-new
sudo cp –avr ams-new/. ams
- Copy “settings.php” file that you backed up to your existing Vsign installation directory.
sudo cp –rf ~/settings.php ams
- Enter http:\\your.server\path (For example, http:\\localhost\ams) in the web browser address bar.
- Login as administrator.
- Navigate through automatic given version upgrade steps.
UPGRADING ON WINDOWS
- You can follow the next steps with the following assumptions.
MySQL administratorID: mysqladmin
AMS database name: amsdb
- (Optional) Clone your existing AMS database and give necessary permissions. It is possible to upgrade the version without cloning however it will be harder to undo the process in case of an error occurrence. To see how to clone your database, check out the next section “CLONING DATABASE”.
- Backup the file “settings.php” which located in your existing AMS installation directory.
- Backup your existing AMS database.
mysqldump –u mysqladmin –p amsdb>amsdb.sql
- Transfer new version’s installation archive to the server.
- Copy AMS new version’s installation files to your existing AMS installation directory.
- Copy “settings.php” file that you backed up to your existing AMS installation directory.
- Enter http:\\your.server\path (For example, http:\\localhost\ams) in the web browser address bar.
- Login as administrator.
- Navigate through automatic given version upgrade steps.
CLONING AMS DATABASE
In this section, you will find explanation to how to backup and reconfigure your AMS database. Relevant commandsare processed through Shell that is on the server.
- You can follow the next steps with the following assumptions.
MySQL administrator ID: mysqladmin
MySQL AMS Database User ID: amsdbuser (generally selected same with MaSQL administrator ID)
Existing MySQL database: amsdb
New MySQL database: amsdbnew
- Following command is run in order tobackup the database to a file.
mysqldump –u mysqladmin –p amsdb>amsdb.sql
- Run following command then enter mysql admin password.
mysql –u mysqladmin –p mysql
- Following commands are run in order to generate new database.
create database amsdbnew;
grant all priviliges on amsdbnew.* to `amsdbuser`@`localhost`;
use amsdbnew;
source amsdb.sql
quit;
- Generated database’s name can be changed if desired. You need to change settings in the “settings.php” file which located in AMS installation directory.
POST-INSTALLATION SETTINGS
Once your AMS is installed, there’s some additional setup required to enable all functionality and to keep things running smoothly.
TIMEZONE
In order to set AMS timezone, complete following steps:
- Go to the Settings page, and then the Regional tab.
- Select the nearest major city in your timezone.
- Click Save at the bottom of the page.
AMS Timezone must not be confused with User Timezone.
User Timezone (configured via Users Page à User à Edit) is used in all dates displayed on AMS pages. However in the background, User Timezone is converted to AMS Timezone and is saved as AMS Timezone.
LANGUAGE DETECTION
By default, the AMS will use the language preferences set in your web browser to auto-detect which language to display in the AMS interface.
- Go to Settings page of the AMS, and then move to the Regional tab.
- Untick the Detect Language (DETECT_LANGUAGE) tick box.
- Select a suitable default language.
- Save your changes.
DEFAULT LANGUAGE
AMS will need to know which language file to take it’s translations from. If language detection is disabled and if no user language is defined, AMS use this language by default.
- Go to Settings page of the AMS, and then move to the Regional tab.
- Select Default Language (DEFAULT_LANGUAGE) value from the list.
- Save your changes.
USER LANGUAGE
If language detection is disabled, AMS pages use this language. User Language selection is done via the menu opened by clicking the profile button at top right corner of AMS.
UPGRADING AMS VERSION
In this section, the steps for upgrading AMS version will be explained. In following subsections, you can follow the detailed process of the version upgrade on Windows and Linux system.
UPGRADING ON LINUX
- You can follow the next steps with the following assumptions.
MySQL administrator ID: mysqladminAMS database name: amsdbServer’s <DocumentRoot>directory: /var/www/html AMS installation directory: <DocumentRoot>/amsNew AMS installation archive: ams-new.zip
- (Optional) Clone your existing AMS database and give necessary permissions. It is possible to upgrade the version without cloning however it will be harder to undo the process in case of an error occurrence. To see how to clone your database, check out the next section “CLONING DATABASE”.
- Backup the file “settings.php” which located in your existing AMS installation directory. For example, you can copy it to your user’s home folder.
sudo cp settings.php ~
- Backup your existing AMS database.
mysqldump –u mysqladmin –p amsdb> ~/amsdb.sql
- Transfer new version’s installation archive to the server. For example transfer the archive to your user’s home folder below:
/home/<your-username>/
- Copy AMS new version’s installation files to your existing AMS installation directory. You can perform following steps in order to do that.
cd /var/www/htmlsudo unzip ~/ams-new.zip sudo chown www-data:www-data -R ams-newsudo cp –avr ams-new/. ams
- Copy “settings.php” file that you backed up to your existing Vsign installation directory.
sudo cp –rf ~/settings.php ams
- Enter http:\\your.server\path (For example, http:\\localhost\ams) in the web browser address bar.
- Login as administrator.
- Navigate through automatic given version upgrade steps.
UPGRADING ON WINDOWS
- You can follow the next steps with the following assumptions.
MySQL administratorID: mysqladminAMS database name: amsdb
- (Optional) Clone your existing AMS database and give necessary permissions. It is possible to upgrade the version without cloning however it will be harder to undo the process in case of an error occurrence. To see how to clone your database, check out the next section “CLONING DATABASE”.
- Backup the file “settings.php” which located in your existing AMS installation directory.
- Backup your existing AMS database.
mysqldump –u mysqladmin –p amsdb>amsdb.sql
- Transfer new version’s installation archive to the server.
- Copy AMS new version’s installation files to your existing AMS installation directory.
- Copy “settings.php” file that you backed up to your existing AMS installation directory.
- Enter http:\\your.server\path (For example, http:\\localhost\ams) in the web browser address bar.
- Login as administrator.
- Navigate through automatic given version upgrade steps.
CLONING AMS DATABASE
In this section, you will find explanation to how to backup and reconfigure your AMS database. Relevant commandsare processed through Shell that is on the server.
- You can follow the next steps with the following assumptions.
MySQL administrator ID: mysqladminMySQL AMS Database User ID: amsdbuser (generally selected same with MaSQL administrator ID)Existing MySQL database: amsdbNew MySQL database: amsdbnew
- Following command is run in order tobackup the database to a file.
mysqldump –u mysqladmin –p amsdb>amsdb.sql
- Run following command then enter mysql admin password.
mysql –u mysqladmin –p mysql
- Following commands are run in order to generate new database.
create database amsdbnew; grant all priviliges on amsdbnew.* to `amsdbuser`@`localhost`;use amsdbnew; source amsdb.sqlquit;
- Generated database’s name can be changed if desired. You need to change settings in the “settings.php” file which located in AMS installation directory.
POST-INSTALLATION SETTINGS
Once your AMS is installed, there’s some additional setup required to enable all functionality and to keep things running smoothly.
TIMEZONE
In order to set AMS timezone, complete following steps:
- Go to the Settings page, and then the Regional tab.
- Select the nearest major city in your timezone.
- Click Save at the bottom of the page.
AMS Timezone must not be confused with User Timezone.
User Timezone (configured via Users Page à User à Edit) is used in all dates displayed on AMS pages. However in the background, User Timezone is converted to AMS Timezone and is saved as AMS Timezone.
LANGUAGE DETECTION
By default, the AMS will use the language preferences set in your web browser to auto-detect which language to display in the AMS interface.
- Go to Settings page of the AMS, and then move to the Regional tab.
- Untick the Detect Language (DETECT_LANGUAGE) tick box.
- Select a suitable default language.
- Save your changes.
DEFAULT LANGUAGE
AMS will need to know which language file to take it’s translations from. If language detection is disabled and if no user language is defined, AMS use this language by default.
- Go to Settings page of the AMS, and then move to the Regional tab.
- Select Default Language (DEFAULT_LANGUAGE) value from the list.
- Save your changes.
USER LANGUAGE
If language detection is disabled, AMS pages use this language. User Language selection is done via the menu opened by clicking the profile button at top right corner of AMS.