Skip to content

Installation

Jump to bottom Edit New page
Frank Lanitz edited this page Mar 23, 2024 · 30 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 - but you will need to adjust for modern versions of Linux, etc.)

Requirements

  • PHP >= 8.0;
  • PHP Composer;
  • Git (apt-get install git or yum install git-core);
  • A database - we officially support MySQL but any database supported by Doctrine2 DBAL may work;
  • Memcached is 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 PHP libraries:

apt-get install php-cgi php-memcache php-json php-mysql php-gettext php-xml libapache2-mod-php

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 --prefer-dist --no-dev opensolutions/vimbadmin

    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 --prefer-dist --no-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.4.0
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 --prefer-dist --no-dev

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;

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
    
    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        /srv/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/php8.0-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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally