<commit_before>Installing CAIRIS
=================

Installation via Docker
~~~~~~~~~~~~~~~~~~~~~~~

If you have Docker installed on your laptop or an available machine, the easiest way of getting up and running with the web application is to download the CAIRIS container from `Docker hub <https://hub.docker.com/r/shamalfaily/cairis/>`_.  Like the live demo, this is built from the latest version of CAIRIS in GitHub, and uses `mod_wsgi-express <https://pypi.python.org/pypi/mod_wsgi>`_ to deliver the CAIRIS web services.

There are two options for running the container, a full install of everything or a smaller install which doesn't provide pdf export functionality:

For the full install (with pdf export functionality) download and run the container, the documentation container, and its linked mysql container:

.. code-block:: bash
 
   sudo docker run --name cairis-mysql -e MYSQL_ROOT_PASSWORD=<PASSWORD> -d mysql:5.7 --thread_stack=256K
   sudo docker run --name cairis-docs -d -v cairisDocumentation:/tmpDocker -v cairisImage:/images -t shamalfaily/cairis-docs
   sudo docker run --name CAIRIS -d --link cairis-mysql:mysql --link cairis-docs:docs -P -p 80:8000 --net=bridge -v cairisDocumentation:/tmpDocker -v cairisImage:/images shamalfaily/cairis

For the smaller install (without pdf export functionality) download and run the container, and its linked mysql container:

.. code-block:: bash
 
   sudo docker run --name cairis-mysql -e MYSQL_ROOT_PASSWORD=<PASSWORD> -d mysql:5.7 --thread_stack=256K
   sudo docker run --name CAIRIS --link cairis-mysql:mysql -d -P -p 80:8000 --net=bridge shamalfaily/cairis

The *docker run* commands will create and start-up CAIRIS, but you will need to create an account before you can use it.  To do this, run the below command - replacing test and test with your desired username and password. 

.. code-block:: bash

   docker exec -t `docker ps | grep shamalfaily/cairis | head -1 | cut -d ' ' -f 1` /addAccount.sh test test TestUser

Once the containers have been installed then, in the future, you should use *docker start* rather than *docker run* to start up the already downloaded containers.

.. code-block:: bash
 
   sudo docker start cairis-mysql 
   sudo docker start CAIRIS

The containers can be stopped using *docker stop*, i.e.

.. code-block:: bash

   sudo docker stop CAIRIS
   sudo docker stop cairis-mysql

To update your docker containers, stop the docker containers and run the below commands to remove any old containers and volume files. Following that, you can re-run the above *docker run* commands to install and run the container.  Don't forget to re-add your user account!

.. code-block:: bash

   sudo docker rm $(sudo docker ps -aq)
   sudo docker rmi --force $(sudo docker images -q)
   sudo docker volume rm $(docker volume ls)


Please feel free to use this container to evaluate CAIRIS, but do not use it for operational use without configuring the default credentials first.  The scripts used to build the container can be found on `GitHub <https://github.com/cairis-platform/cairis/tree/master/docker>`_, and provides a useful template for getting started.

Ubuntu CAIRIS Virtual Machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have VMWare then you can download an Ubuntu CAIRIS virtual machine from `here <https://drive.google.com/open?id=1DT6B_3DaoZ1a8XAI8QAhigq8LPu7lrOJ>`_ .  This VM was created using the quickInstall.sh script described in the section below.  To login to the VM, the username/password is <PASSWORD>/<PASSWORD>.  The account contains a short-cut to Chromium, which has the Persona Helper chrome extension installed.


Installation and configuration via GitHub (automated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have a clean Ubuntu 19.04 VM, you can quickly install and configure CAIRIS and its dependencies with the command below, replacing my-secret-pw with your desired root password for MySQL.

.. code-block:: bash

   sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get dist-upgrade -y && sudo apt install curl -y && sudo apt install net-tools -y && curl -s https://cairis.org/quickInstall.sh | bash -s my-secret-pw

In addition to configuring and installing CAIRIS, the script creates an initial user account (username: test, password: <PASSWORD>), starts cairisd.py as a service, and restarts the VM.  You can use *journalctl* to check the CAIRIS log file.

.. code-block:: bash

   journalctl -u cairis.service -f

This script also adds an alias so, in future, you can update CAIRIS by running the below command:

.. code-block:: bash

   update_cairis

Installation and configuration of server with account registration via GitHub (automated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have a clean Ubuntu 19.04 VM, want to quickly install CAIRIS for multiple users, but don't want to use the defaults associated with the quickInstall.sh script, then you can run the more bespoke serverInstall.sh script as below, replacing (i) my-secret-pw with your desired MySQL root password, (ii) mymailserver.com with the name of your private (with SSL) outgoing mail server, (iii) 465 with this mail server's port, (iv) <EMAIL> with your mail server username, and (v) mypassword with this account's password.

.. code-block:: bash

   sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get dist-upgrade -y && sudo apt install curl -y && sudo apt install net-tools -y && curl -s https://cairis.org/serverInstall.sh | bash -s my-secret-pw mymailserver.com 465 admin@mymailserver.com mypassword

Although no update_cairis alias is created, we do provide a `rebuildServer.sh <https://cairis.org/rebuildServer.sh>`_ script which, if run from cron each night, will rebuild and reconfigure CAIRIS while still retaining the user accounts created on the server.  This script takes the same command line arguments as the serverInstall.sh script.

Once the server is running, users can register for accounts using the Register link on the login page.  The account name should be a valid email address.  When an account is created, an email is sent to the user and the user is logged in.  If the Reset link is clicked and the acccount name is provided, CAIRIS will email instructions for resetting the password to the user.

Installation and configuration via GitHub (manual)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<commit_msg>Additional configuration and server rebuild instructions (Issue #470)<commit_after>Installing CAIRIS
=================

Installation via Docker
~~~~~~~~~~~~~~~~~~~~~~~

If you have Docker installed on your laptop or an available machine, the easiest way of getting up and running with the web application is to download the CAIRIS container from `Docker hub <https://hub.docker.com/r/shamalfaily/cairis/>`_.  Like the live demo, this is built from the latest version of CAIRIS in GitHub, and uses `mod_wsgi-express <https://pypi.python.org/pypi/mod_wsgi>`_ to deliver the CAIRIS web services.

There are two options for running the container, a full install of everything or a smaller install which doesn't provide pdf export functionality:

For the full install (with pdf export functionality) download and run the container, the documentation container, and its linked mysql container:

.. code-block:: bash
 
   sudo docker run --name cairis-mysql -e MYSQL_ROOT_PASSWORD=<PASSWORD> -d mysql:5.7 --thread_stack=256K
   sudo docker run --name cairis-docs -d -v cairisDocumentation:/tmpDocker -v cairisImage:/images -t shamalfaily/cairis-docs
   sudo docker run --name CAIRIS -d --link cairis-mysql:mysql --link cairis-docs:docs -P -p 80:8000 --net=bridge -v cairisDocumentation:/tmpDocker -v cairisImage:/images shamalfaily/cairis

For the smaller install (without pdf export functionality) download and run the container, and its linked mysql container:

.. code-block:: bash
 
   sudo docker run --name cairis-mysql -e MYSQL_ROOT_PASSWORD=<PASSWORD> -d mysql:5.7 --thread_stack=256K
   sudo docker run --name CAIRIS --link cairis-mysql:mysql -d -P -p 80:8000 --net=bridge shamalfaily/cairis

The *docker run* commands will create and start-up CAIRIS, but you will need to create an account before you can use it.  To do this, run the below command - replacing test and test with your desired username and password. 

.. code-block:: bash

   docker exec -t `docker ps | grep shamalfaily/cairis | head -1 | cut -d ' ' -f 1` /addAccount.sh test test TestUser

Once the containers have been installed then, in the future, you should use *docker start* rather than *docker run* to start up the already downloaded containers.

.. code-block:: bash
 
   sudo docker start cairis-mysql 
   sudo docker start CAIRIS

The containers can be stopped using *docker stop*, i.e.

.. code-block:: bash

   sudo docker stop CAIRIS
   sudo docker stop cairis-mysql

To update your docker containers, stop the docker containers and run the below commands to remove any old containers and volume files. Following that, you can re-run the above *docker run* commands to install and run the container.  Don't forget to re-add your user account!

.. code-block:: bash

   sudo docker rm $(sudo docker ps -aq)
   sudo docker rmi --force $(sudo docker images -q)
   sudo docker volume rm $(docker volume ls)


Please feel free to use this container to evaluate CAIRIS, but do not use it for operational use without configuring the default credentials first.  The scripts used to build the container can be found on `GitHub <https://github.com/cairis-platform/cairis/tree/master/docker>`_, and provides a useful template for getting started.

Ubuntu CAIRIS Virtual Machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have VMWare then you can download an Ubuntu CAIRIS virtual machine from `here <https://drive.google.com/open?id=1DT6B_3DaoZ1a8XAI8QAhigq8LPu7lrOJ>`_ .  This VM was created using the quickInstall.sh script described in the section below.  To login to the VM, the username/password is cairisuser/cairisuser.  The account contains a short-cut to Chromium, which has the Persona Helper chrome extension installed.


Installation and configuration via GitHub (automated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have a clean Ubuntu 19.04 VM, you can quickly install and configure CAIRIS and its dependencies with the command below, replacing my-secret-pw with your desired root password for MySQL.

.. code-block:: bash

   sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get dist-upgrade -y && sudo apt install curl -y && sudo apt install net-tools -y && curl -s https://cairis.org/quickInstall.sh | bash -s my-secret-pw

In addition to configuring and installing CAIRIS, the script creates an initial user account (username: test, password: <PASSWORD>), starts cairisd.py as a service, and restarts the VM.  You can use *journalctl* to check the CAIRIS log file.

.. code-block:: bash

   journalctl -u cairis.service -f

This script also adds an alias so, in future, you can update CAIRIS by running the below command:

.. code-block:: bash

   update_cairis

Installation and configuration of server with account registration via GitHub (automated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have a clean Ubuntu 19.04 VM, want to quickly install CAIRIS for multiple users, but don't want to use the defaults associated with the quickInstall.sh script, then you can run the more bespoke serverInstall.sh script as below, replacing (i) my-secret-pw with your desired MySQL root password, (ii) mymailserver.com with the name of your private (with SSL) outgoing mail server, (iii) 465 with this mail server's port, (iv) <EMAIL>@<EMAIL> with your mail server username, and (v) mypassword with this account's password.

.. code-block:: bash

   sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get dist-upgrade -y && sudo apt install curl -y && sudo apt install net-tools -y && curl -s https://cairis.org/serverInstall.sh | bash -s my-secret-pw mymailserver.com 465 <EMAIL> mypassword

In addition to the above, you also need to update my MySQL server system variables.  You can do this by adding or updating the below values to your mysqld.cnf file.  In Ubuntu 19.04, you can find this in /etc/mysql/mysql.conf.d, but the file location might differ depending on your OS.


.. code-block:: bash
   thread_stack = 256K
   max_sp_recursion_depth = 255

Once these changes have been made, you need to restart MySQL or reboot your server.  

When working with very large models, you may get memory errors when viewing goal models or carrying out model validation checks.  If you do, you could consider increasing the thread_stack size.  For example, increasing the size to 1024K made it possible to valid even really big system-of-system models, but you can increase or decrease this size based on your server's performance and the number of users you expect the server to support.

Although no update_cairis alias is created, we provide a `rebuildServer.sh <https://cairis.org/rebuildServer.sh>`_ script which, if run from cron each night, will rebuild and reconfigure CAIRIS while still retaining the user accounts created on the server.  This script takes the same command line arguments as the serverInstall.sh script, with the addition of additional arguments for the name of the account running CAIRIS, and the accounts home directly.  For example, if the account running CAIRIS is *sfaily* and the home directory in */home/sfaily* then, to rebuild the server at 0200 each morning you should run *sudo crontab -e* and add the following line to your crontab


.. code-block:: bash
   0 2 * * * /home/sfaily/rebuildServer.sh my-secret-pw mymailserver.com 465 <EMAIL> mypassword sfaily /home/sfaily > /home/sfaily/rebuild.log 2>&1

This script outputs the rebuild log to rebuild.log, which can be useful for troubleshooting any problems.

Once the server is running, users can register for accounts using the Register link on the login page.  The account name should be a valid email address.  When an account is created, an email is sent to the user and the user is logged in.  If the Reset link is clicked and the acccount name is provided, CAIRIS will email instructions for resetting the password to the user.

Installation and configuration via GitHub (manual)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{'fraction_non_alphanumeric': 0.1006027852837248, 'fraction_numerical': 0.008314279775514447, 'mean_word_length': 4.254459410265745, 'pattern_counts': {'":': 0, '<': 26, '<?xml version=': 0, '>': 28, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2707554', 'n_tokens_mistral': 4181, 'n_tokens_neox': 3786, 'n_words': 1945}