-
Notifications
You must be signed in to change notification settings - Fork 102
Installation
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.)
- PHP >= 8.0;
- PHP Composer;
- Git (
apt-get install git
oryum 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
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).
-
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.
-
Via Git clone:
git clone https://github.com/opensolutions/ViMbAdmin.git $INSTALL_PATH cd $INSTALL_PATH composer install --prefer-dist --no-dev
-
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
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
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.
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.
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
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!
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/.
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.
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" )
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;
}
}
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.
The next step is configuring a fully fledged mail system (Postfix, Dovecot for example) to use the above.