Installation

Owned by Gert Burger
Last updated: Apr 30, 2019Version comment
3 min read

Supported Platforms

Canopy is officially supported on the following operating systems:

Operating SystemVersionNotes
Ubuntu Linux16.04 LTS64-bit Server edition
RedHat Enterprise Linux/Oracle Enterprise Linux/CentOSv7.3/7.464-bit. Requires rabbitmq-server package which can be sourced from EPEL or manually.


Canopy can run on other operating systems/distributions, such as Debian, Kali Linux and Mac OSX. However, Canopy will only be supported on the above operating systems

The following key dependencies on Linux based operating systems are noted:

Key DependencyDescription
PostgreSQL 9.x or Oracle DB 12DB server for storing/processing Canopy related data. Note that certain DB servers may require more resources.
Nginx 1.x or Apache 2.4/2.5Front end web server for serving the Canopy user interface
RabbitMQ Server 3.xBackend service for processing Canopy related tasks using the Celery framework
OpenJDK 8 JRE or Oracle Java 8Java runtime for document generation.

Platform installation guides

Install on Ubuntu 16.04

Canopy

As root:

  1. Copy Canopy license file to /etc/canopy/license
  2. apt install -f ./libtidy5_5.2.0-2_amd64.deb ./canopy_3.1.0_amd64.deb
  3. Setup a Database and Reverse proxy via steps in Installation#configuration section.

Canopy Document Server

As root:

  1. apt install openjdk-8-jre
  2. apt install -f ./canopy-docserver_0.0.11_amd64.deb

  3. systemctl restart canopy-docserver


Install on RHEL 7, Oracle EL 7 and CentOS 7

Canopy

As root:

  1. Install libtidy5 yum install ./libtidy5-5.2.0-2.3.x86_64.rpm
  2. Install rabbitmq-server package:
    1. On Centos you can install the epel-release package and the Canopy installation will source the correct depedencies.
    2. On RHEL/OEL you can either install epel-release or install rabbitmq-server from some other source.
  3. Copy Canopy license file to /etc/canopy/license
  4. Install Canopy yum install ./canopy-3.0.0-1.el7.centos.x86_64.rpm
  5. Setup a Database and Reverse proxy via steps in Installation#configuration section.

Canopy Document Server

  1. yum install java-1.8.0-openjdk.x86_64
  2. Install Canopy docserver yum install ./canopy-docserver-0.0.12-1.el7.centos.x86_64.rpm
  3. systemctl restart canopy-docserver

Example sources for packages

Configuration

As root:

  1. canopy-setup postgresql (Oracle users should see the Oracle DB Configuration section)

  2. canopy-setup nginx (Optional if you intend to configure your own reverse proxy. Apache users see Apache Configuration section)
    1. (RHEL) (Optional) Configure firewall access, the following commands would open up port 80/443:

      firewall-cmd --zone=public --add-service=https --permanent
      firewall-cmd --zone=public --add-service=https
      firewall-cmd --zone=public --add-service=http --permanent
      firewall-cmd --zone=public --add-service=http
    2. (RHEL) (Optional) Enable the SELinux httpd_can_network_connect option so that the reverse proxy can connect to Canopy
      setsebool -P httpd_can_network_connect 1
  3. canopy-manage setupdb --prod
  4. canopy-manage createsuperuser (Skip this step if you are going to import Canopy 2 data)
  5. Configure systemd persistent logging (See Logging configuration section)

Once the database has been set up and the admin user created, restart the canopy related services:

$ systemctl restart canopy canopy-celery


In order for links to be generated correctly, the EXTERNAL_BASE_URL setting should be updated in /etc/canopy/canopy.ini to the URL that your users will use to access this Canopy instance.

Logging configuration

Canopy uses systemd for logging and by default most Linux distributions do not persist systemd logs. The follow steps will configure systemd/journald to persist its logs to disk.

$ mkdir /var/log/journal
$ systemctl restart systemd-journald

If systemd is not configured to persist logs then they will not survive reboots.


Apache configuration

Required modules (beyond defaults):

  • ssl
  • proxy
  • proxy_http
  • headers
  • rewrite
  • deflate

An example config is provided in /opt/checksec/canopy/configs/apache.conf

Oracle DB configuration

Manual configuration is required to use an existing Oracle Database.


Note that Canopy will require the official Oracle instantclient (basic) 12.1 to be already installed on the server, correctly configured in ldconfig and sqlplus must be available in the standard PATH. If not then Canopy will fail to connect to the Oracle DB stating that libclntsh.so.12.1 cannot be found.


Instead of step 1 of the Configuration section the user should (as root) edit `/etc/canopy/canopy.ini`

Remove the DATABASE_URL line and add the following lines:

DATABASE_ENGINE=django.db.backends.oracle
DATABASE_NAME=10.0.0.1:1521/orcl
DATABASE_USER=canopy
DATABASE_PASSWORD=canopy

The above values should be updated to match the credentials and details of the configured Oracle DB.

The DATABASE_NAME setting can be any Oracle supported connection identifier, e.g. (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orclpdb1.localdomain)))

Continue with the remaining Configuration steps.

Debugging


Check if services are running:

systemctl status canopy canopy-celery canopy-docserver


Restart services:

systemctl restart canopy canopy-celery canopy-docserver


Get a service's logs:

journalctl -xe -u canopy


Follow a service's logs:

journalctl -xe -f -u canopy

Upgrading

As root:

  1. Install new package
  2. Restart services