Native Installation on Linux

"Native" installation - what's the added value?

A "native" installation means an installation without any virtualization. Native "on the bare metal" is ideal for debugging and performance. You'll have better control about basically everything on your machine.

Related Pages

Shellscripts in the mdis-installer (opens new window) gitlab repository
mDIS-Installation on Virtualbox: general, detailed
Installation as Docker container
System Settings

Detailed Instructions

• Example: Ubuntu 18.04 LTS server

• The installation has to be conducted by a user with "sudo" privileges. The instructions assume the Linux username "administrator". If you plan to use "administrator":

  adduser administrator administrator; usermod -aG sudo administrator

• If your username is different (e.g. "mdis"), adapt the commands accordingly.

Assumptions

• Admin has a good understanding of a modern Linux system (AMD x64 centric view taken here).

• Suitable Linux operating system is already installed and configured. Check list on mDIS for Virtualbox page for distributions. Install mDIS on a virtual machine first for practice, and then install a "native" version on localhost on your standalone PC, without any virtualization.

• Networking is configured, Linux server is accessible over the network. Port 22 (SSH), 80 (HTTP) or 443 (HTTPS) are accessible. Other ports for filesharing (FTP, SMB), or debugging, etc., are optional.

• Instructions below are given for Debian (opens new window)-based (opens new window) Linux Distributions (such as Ubuntu), and their respective package management systems (apt, dpkg, etc.).

• If you'd like to practice, perform a "dry-run" of the installation inside a Virtualbox Linux guest, before "going native".
  Changing your "bare metal" localhost configuration might conflict with current applications and services you might have installed before. For instance, there might already be a different webserver running and listening on port 80 (e.g. nginx instead of Apache described here) which might conflict with the mDIS web interface.

• Even later start thinking about installing mDIS on a cloud server on the public internet.

Prerequisites

Installing Prerequisites on your Host System

Update package resources

sudo apt update
sudo apt upgrade

Reboot if necessary.

Install software packages

You can use the package manager of your distribution to install these packages. They will be installed system-wide. The necessary shell commands are given further below.

• MySQL-Server (or MariaDb-Server)
• Apache Web Server
• PHP with extensions:
  • gd
  • xml
  • mysql
  • mbstring
  • zip
  • intl
• composer
• imagemagick
• git
• npm and nodejs, optional: nvm
• ssh (client and server)

The ssh metapackage is a convenient way to install both the OpenSSH client and the OpenSSH server. SSH server is optional for running mDIS on localhost on a standalone PC. However package ssh is needed if you want to administer mDIS remotely.

Install some important binaries first

sudo apt install mysql-server apache2 imagemagick ssh git

PHP should be php7. In 2019 the current version is PHP 7.3 but your Linux might come with a different version. It should be at least PHP 7.3.

In 2022 we have tried to install mdIS with PHP 8.1 but is a bit more finicky during installation of mDIS 3rd-party code-packages and execution of .yii tasks.

sudo apt install php php-gd php-xml php-mysql php-mbstring php-zip php-intl composer

Install NodeJS (opens new window), the Javascript Runtime.

To do so, you can use nvm (opens new window), the bash script to manage multiple active node.js versions.

Read the nvm documentation (opens new window).

(You can use apt-get to install it, but it's not recommended, because you have less control over which node version will be installed.)

This downlads and runs a shellscript, directly. You may want to inspect that script https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh (opens new window) first to see what it does.

The Script-URL didn't change in 4 years, 2018-2022.

# The script clones the nvm repository to ~/.nvm
# and adds the source line to your profile
# (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).
#
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

Close the shell window.
Open a new shell to have nvm in your PATH.

# this installs nodejs
nvm ls-remote --lts     #   list only long term support versions
nvm install   --lts 16  #   in 2022 the most recent lts version is Node 16
nvm use 16

Alternatively you can use the package manager of your Linux Distribution, but this will likely install an even older version of nodejs.

apt install nodejs npm

Regarding client-side JavaScript, in 2021 have been some changes of the 3rd party dependencies that mDIS requires. To run mDIS on Node 16 or Node 14, both require a few node-packages (sass-loader) with slightly different, but specific version numbers. These should be specified in the package.json file, in the mDIS top level directory. (TODO explain better)

mDIS Installation

Create dis directories

The mDIS app directory does not have to be named dis (or /var/www/dis). It can be named anything you like.

Create a directory for the dis website. This should usually be in /var/www.
You can call it dis. To be more flexible, create a subdirectory of your choice, and then create a symlink /var/www/dis -> /path/to/your-subdirectory. This way you can have multiple dis installations on the same server (one active, the others "dormant").

#### Create *dis* directory and set unixuser as owner

sudo mkdir -p /var/www/mdis-myproject
sudo cd /var/www
sudo ln -s mdis-myproject dis
# substitute username appropriately
sudo chown youruser:somegroup /var/www/dis

# grab mDIS code from git, (or copy an existing dir...).
# (not shown here)

# git clone ...

# after "git clone", you will need to change ownership
# of this directory and its subdirectories, again.

See below for details about permissions.

WARNING

Running the web server process under an account that has sudo privileges is not secure and can attract malicious hackers.
Running this setup might be practical only on your localhost "network" (with only 1 physical computer), or perhaps in your intranet where you know what's going on. Do not connect an mDIS configured like this to the wider public Internet!

Get mDIS code with git-clone

Install mDIS from the repository server (Credentials required)

Clone the repository from the Gitlab server to the dis website directory.

# Optional: Use the su command to switch to
# the administrator account. (or whatever  name you chose):
# su - administrator
# or do sudo -u administrator git clone ...
git clone https://gitlab.informationsgesellschaft.com/dis/dis  /var/www/dis

Cloning into an existing directory is only allowed if the directory is empty.

Install 3rd Party Code

Install PHP dependencies and JavaScript/Node modules. Use composer and npm.

Install 3rd party dependencies. This is a one-off task.

Use command-line-tool composer to install the required PHP dependencies (also mentioned briefly above) for setting up the backend.

cd /var/www/dis
composer update composer # optional

composer update --prefer-dist
composer install
mkdir backend/runtime
composer run-script post-create-project-cmd

Use command-line-tool npm to install the required Node modules, required to build the frontend.

npm install
# optional: security updates - if know what you are doing:
# npm audit fix

Create mysql database and user

Install MySQL as required by the installer. Create mysql user root. If it was already installed, lookup root's credentials.

As mysql root user, create a database named "dis" with character set utf8mb4 and collation utf8mb4_unicode_ci (UTF-8, multibyte character set for full unicode, case insensitive sorting order). You can use other character sets (mysqlk has many available) as long it is a case-insensitive character set from the utf8 "family".

Instead of "dis". you can also call this new empty database mdis_myproject, but then you have to change the database name in other scripts and config files accordingly.

Create a mysql user (perhaps named disuser), and assign a random password. Allow disuser to connect from localhost. You may need to give this user additional permissions if you want to allow database access from other hosts (e.g. a backup server) from within your network.

# create database "dis".
# You can also call it mdis_myproject
sudo mysql -u root -e "CREATE DATABASE dis CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# this assigns a 50 character password to disuser
PASSWORD=$(echo "$(openssl rand -base64 50)" | tr -d [:space:])
sudo mysql -u root -e "GRANT ALL ON dis.* TO 'disuser'@'localhost' IDENTIFIED BY '${PASSWORD}';"
sudo mysql -u root -e "FLUSH PRIVILEGES;"

Create yii configuration file to access the database

Create a file ".env" in the dis directory. You can use the file ".env-dev" as a template. Enter the randomly created password from above:

# first make sure you are not overwriting your own .env file
# then:
bash -c 'cat > .env' << EOF
MYSQL_ROOT_PASSWORD=
MYSQL_DATABASE=dis
MYSQL_USER=disuser
MYSQL_PASSWORD=$PASSWORD
MYSQL_HOST=localhost
YII_DEBUG=true
YII_ENV=dev
EXTERNAL_ALLOWED_IP=$(hostname -I) # e.g. 172.21.0.1
EOF
unset PASSWORD

Details of these settings can change slightly depending on your computing environment. Use your developer knowledge to set appropriate values.

Initialize database content

Run the yii scripts to

• copy the model and form templates from the version-controlled default location to the respective active folders (outside version control, where they can be adapted to the present project),
• create the required tables, and
• install some users and test data.

# this command keeps all tables, but might throw some errors
./yii migrate --interactive=0
#
# this variant of the command drops all existing tables.
# (run this if tables have been redesigned substantially):
# ./yii migrate/fresh --interactive=0

# additional tasks
./yii seed/users
./yii seed/example-dump
./yii seed/form-permissions # backend, in *.php files

The last 3 seed/ tasks are defined in backend/commands/, e.g. in file SeedController.php and in file backend/modules/api/common/controllers/FormController.php, method updateAccessRights().

Compile the web application.

Compile the mDIS .vue files to JavaScript, and bundle .css and .js files.

npm run build

The front-end is now ready to be served.

Configure web server

• Setup the configuration files for the dis website.
• Disable the default website
• Enable the apache rewrite module
• Restart the web server

sudo bash -c 'cat > /etc/apache2/sites-available/dis.conf' << EOF
<VirtualHost  *:80>

  ServerAdmin webmaster@localhost
  DocumentRoot /var/www/dis/web

  <Directory /var/www/dis/web>
    RewriteEngine on
     RewriteCond %{REQUEST_FILENAME} !-f
     RewriteCond %{REQUEST_FILENAME} !-d
     RewriteRule . index.php
  </Directory>


  ErrorLog \${APACHE_LOG_DIR}/error.log
  CustomLog \${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
EOF

sudo a2dissite 000-default.conf
sudo a2ensite dis.conf
sudo a2enmod rewrite
sudo systemctl reload apache2

Run web server

Run it under account of administrator or mdis (or whatever you chose). Alternatively run it as www-data and assign the group permissions accordingly.

sudo sed -i 's/www-data/administrator/g' /etc/apache2/envvars
# command to change ownership of /var/www/dis/web to administrator ...

# restart webserver
sudo systemctl reload apache2

Subdirectory management

Default Permissions

TODO: explain both options better (change dir owner, or do not change dir-owner but make certain subdirs group-writable).

Make some subdirectories writable

Working with the mDIS Template manager will create new PHP files in directories backend/. By default, the Web Server Process will write to this directory (and some other directories), but some other unixusers might as well.

To avoid access right problems after changes in the subdirectories of backend/, configure the web server such that it runs under the account of the user "administrator".

Alternatively, make some subdirectories writable to the unixgroup (chmod -R g+w ...), or make them world-writable (chmod -R go+rwxw ...). Making them world-writable is a last-resort solution. You should do thisd if mDIS continues to fail to work properly.

Important Directories

Make sure the web server process has write access to the following directories:

backend/dis_templates/forms    # code-generated .json files for input forms
backend/dis_templates/models   # code-generated .json files for models/tables
backend/forms                  # code-generated .php files for input forms
backend/models                 # code-generated .php files for tables
src/forms                      # contains *.vue.generated files

Also make log directories writable, and file upload directories.

TBC

Avoiding "permission denied" errors

You also want to avoid File Permission problems. In the long run you are likely to encounter such problems, when you manually work on the command line. This entails such common tasks as uploading files, working with backups, file renaming, making copies, etc.

Directory Permissions

Create these directories with the permission 2775 (rwxrwsr-x) and assign the group of the directory to the www-data group.

chmod 2775 backend/dis_templates/forms

This sets the Setgit bit on the directory. New files created in these directories will have the same group owner as the parent directory.

Make your unix-user a member of the www-data group. This avoids "permission denied" errors when unixuser and webserver process access each other's files in these directories.

File Permissions

Setting Default Permissions for Files

For new files which will be created or uploaded into in these directories, set the default permissions to 664 (rw-rw-r--) or 2644 (for new files will have group of parent directory) . One way to achieve this is by putting the command

umask 002

into the .bashrc file of the unixuser.

TODO - docteam

• verify/double-check all the above. Setup testscripts for checking this on concrete installations.
• Remove or point out "Debianisms", perhaps.
• Move this content to a "best practices" page, or a different page.

Access Control Lists

ACLs in the context of Unix filesystems: They extend (or constrain) the access rights of individual files and directories. For details: read man 5 acl and/or man getfacl, man setfacl. You might need to install the acl package first.

ACLs in the context of networking: ACLs installed on a Router or on a Firewall provide more fine-grained security. On production servers accessible from the internet you should use Access Control Lists (ACLs) to constrain network traffic.

TODO : explain it better.

Read the following Wikipedia article for more information: Access-control list (opens new window)

How to Make all new files in a directory accessible to a group (opens new window)