Installation

Barry O'Donovan edited this page Feb 4, 2017 · 21 revisions

This document is a step by step guide to installing ViMbAdmin from various sources. (if you are looking for a full setup with postfix and dovecot, you can find documentation here.)

Requirements

  • PHP >= 5.4 (with: mbstring);
  • PHP Composer;
  • Git (apt-get install git or yum install git-core);
  • A database - we officially support MySQL / MariaDB but any database supported by Doctrine2 DBAL should work fine;
  • Memcached is strongly recommended;
  • A web server such as Apache2 or Lighttpd (also can be tested or previewed via the built in PHP web server).

You'll also need various PHP5/7 libraries:

# for PHP5
apt-get install php5-cgi php5-mcrypt php5-memcache php5-json php5-mysql php-gettext libapache2-mod-php5
# for PHP7
apt-get install php7.0-cgi php7.0-mcrypt php-memcache php7.0-json php7.0-mysql php-gettext libapache2-mod-php7.0

For FreeBSD, the complete list of packages you will need to get started is this: php-composer php56 php56-ctype php56-filter php56-gettext php56-hash php56-json php56-mcrypt php56-openssl php56-phar php56-pdo php56-pdo_YOURDATABASETYPE php56-YOURDATABASETYPE These can be installed using pkg or portmaster.

Note

  • PHP 5.4 is a requirement for ViMbAdmin V3. It will NOT work with PHP 5.3.
  • Due to the size of some dependencies, it might be necessary to increase Composer's timeout, as described here.

Installation

Log into the server where you wish to install ViMbAdmin. In this document, I am going to assume your install path is /srv/vimbadmin and I will reference this using $INSTALL_PATH. You can thus copy and paste commands if you set the following appropriately:

export INSTALL_PATH=/srv/vimbadmin

You can install ViMbAdmin in a number of ways. In all cases you need PHP Composer installed (see requirements above).

  1. Via PHP Composer:

    composer create-project opensolutions/vimbadmin $INSTALL_PATH -s dev

    At the end of this process, composer will ask you:

    Do you want to remove the existing VCS (.git, .svn..) history?*

    Choose no.

  2. Via Git clone:

    git clone https://github.com/opensolutions/ViMbAdmin.git $INSTALL_PATH
    cd $INSTALL_PATH
    composer install --dev
  3. Via tarball (this method is discouraged as it will make updating more difficult):

    Find the latest release of ViMbAdmin from GitHub here. Find the URL of the tar.gz bundle and (changing filenames as appropriate):

    cd $(dirname $INSTALL_PATH)
    VIMBADMIN_VERSION=3.0.12
    wget https://github.com/opensolutions/ViMbAdmin/archive/${VIMBADMIN_VERSION}.tar.gz
    tar zxf ${VIMBADMIN_VERSION}.tar.gz
    mv ViMbAdmin-${VIMBADMIN_VERSION} $INSTALL_PATH
    cd $INSTALL_PATH
    composer install

Filesystem Permissions

If you plan to run under Apache / other web server, ensure you set the ownership on the var/ directory appropriately. For example, for Apache2 under Ubuntu:

chown -R www-data: $INSTALL_PATH/var

Database Setup

ViMbAdmin requires a backend database. We use the Doctrine2 DBAL and ORM so, in theory, any of the databases that Doctrine2 DBAL supports should work fine. We tend to use MySQL / MariaDB exclusively for testing and production so these instructions relate to that.

Instructions for other databases: PostgreSQL; SQLite

Log into your MySQL (or other) database and create a new user and database:

CREATE DATABASE `vimbadmin`;
GRANT ALL ON `vimbadmin`.* TO `vimbadmin`@`localhost` IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

NB: 2015-02-02 - due to #124, the database currently needs to be called vimbadmin.

Change the host as appropriate above and chose a secure random password. Note the host, database name, user and password for later.

Configuration

We ship a stock / reference configuration file. You need to copy this as follows:

cp $INSTALL_PATH/application/configs/application.ini.dist $INSTALL_PATH/application/configs/application.ini

You now need to set your database parameters from above in this file. You'll find these near the top and here is an example:

resources.doctrine2.connection.options.driver   = 'pdo_mysql'
resources.doctrine2.connection.options.dbname   = 'vimbadmin'
resources.doctrine2.connection.options.user     = 'vimbadmin'
resources.doctrine2.connection.options.password = 'password'
resources.doctrine2.connection.options.host     = 'localhost'

Please see Configuration page and work your way through your application.ini and update the settings as appropriate. In particular, you need to configure a mail relay.

Application Environment

The section of application.ini that is used by the application (e.g. production or development) is taken from $INSTALL_PATH/public/.htaccess. At a minimum you need to copy this file from the example included. You can update it to suit your own system later.

cp $INSTALL_PATH/public/.htaccess.dist $INSTALL_PATH/public/.htaccess

Database Creation

Now that your configuration is set and you have setup a database and user in MySQL, you need to create the database schema:

cd $INSTALL_PATH
./bin/doctrine2-cli.php orm:schema-tool:create

If all goes well, you should see:

$ ./bin/doctrine2-cli.php orm:schema-tool:create
ATTENTION: This operation should not be executed in a production environment.

Creating database schema...
Database schema created successfully!

Web Server Set-Up

PHP Built-In Webserver for Testing

You can easily run ViMbAdmin under the built in web server for testing purposes as follows:

cd $INSTALL_PATH
php -S localhost:8080 -t public/

You should now find ViMbAdmin under http://localhost:8080/.

Apache2

You need to tell Apache where to find ViMbAdmin and what URL it should be served under. In this example, we're going to serve it from /vimbadmin (e.g. www.example.com/vimbadmin). As such, we create an Apache configuration block as follows on our web server:

Alias /vimbadmin /srv/vimbadmin/public

<Directory /srv/vimbadmin/public>
    Options FollowSymLinks
    AllowOverride FileInfo

    # For Apache <= 2.3:
    Order allow,deny
    allow from all

    # For Apache >= 2.4
    # Require all granted    
</Directory>

You may need to edit the above if you're using a different URL or file system path.

Ensure mod_rewrite is enabled:

a2enmod rewrite

Restart Apache and you can now browse to your new installation.

Lighttpd

You need to tell lighty where to find ViMbAdmin and what URL it should be served under. In this example, we're going to serve it from /vimbadmin (e.g. www.example.com/vimbadmin). As such, we create an alias as follows on our web server configuration:

url.rewrite = (
    "^/vimbadmin/(.*)\.(.+)$" => "$0",
    "^/vimbadmin/(.+)/?$" => "/vimbadmin/index.php/$1"
)       
alias.url = ( "/vimbadmin" => "/srv/vimbadmin/public" )

Nginx

You need to tell nginx to find ViMbAdmin and what URL it should be served under. In this example, we're going to serve it from a custom server name (e.g. http://vimbadmin.example.com). As such, we create a virtual host config file as follows on our web server configuration:

server {
    listen      80;
    server_name vimbadmin.example.com;
    root        /opt/vimbadmin/public;

    index index.php;

    # Logs
    access_log  /var/log/vimbadmin/access.log;
    error_log   /var/log/vimbadmin/error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # Pass the PHP scripts to FastCGI server
    location ~ \.php$ {
        # Prevent Zero-day exploit
        try_files $uri =404;

        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        #NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini

        fastcgi_pass    unix:/var/run/php5-fpm.sock;
        fastcgi_index   index.php;
        fastcgi_param   SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include         fastcgi_params;
    }
}

Welcome to Your New ViMbAdmin Installation

You should now be greeted with a page welcoming you. If you didn't set the security salt above, then the installer will provide random strings for these. Place this in vimbadmin/application/configs/application.ini as instructed before continuing. If you did set it, then enter it in the Security Salt input box.

This is a security step to ensure that only the person performing the installation can create a super administrator.

Now enter a username (which must be an email address) and a password.

Once you click save, you're done! Log in and work away.

Enabling Other ViMbAdmin Features

Next Steps

The next step is configuring a fully fledged mail system (Postfix, Dovecot for example) to use the above.