Canopy
Canopy

Installation

Supported platforms

Canopy is officially supported on the following operating systems:

Operating System Version Notes
Ubuntu Linux 16.04/18.04 LTS 64-bit Server edition
RedHat Enterprise Linux/Oracle Enterprise Linux/CentOS v7.3+ 64-bit

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 Dependency Description
PostgreSQL 9.3+ or Oracle DB 12 Database server for storing/processing Canopy data. Note that certain database servers may require more resources.
nginx 1.x or Apache 2.4/2.5 Front-end web server for serving the Canopy user interface.
RabbitMQ Server 3.x Back-end service for processing Canopy related tasks using the Celery framework.
OpenJDK 8 JRE or Oracle Java 8 Java library for document generation.

Platform installation guides

Install on Ubuntu 16.04/18.04

Canopy

As root:

  1. Copy your Canopy license file to /etc/canopy/license.

  2. (Ubuntu 16.04 only) Install libtidy5:

    apt install -f ./libtidy5_5.2.0-2_amd64.deb
    
  3. Install Canopy packages:

    apt install -f ./canopy_3.1.0_amd64.deb
    
  4. Setup a database and reverse proxy via steps in the Configuration section.

Canopy Document Server

As root:

  1. Install Java 8:

    apt install openjdk-8-jre
    
  2. Install Canopy Docserver package:

    apt install -f ./canopy-docserver_0.0.11_amd64.deb
    
  3. Restart Docserver services:

    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 dependencies.
    2. On RHEL/OEL you can either install epel-release or install rabbitmq-server from some other source.
  3. Copy your Canopy license file to /etc/canopy/license.

  4. Install Canopy:

    yum install ./canopy-3.1.0-1.el7.centos.x86_64.rpm
    
  5. Setup a database and reverse proxy via steps in the Configuration section.

Canopy Document Server

  1. Install OpenJDK 8 JRE or Oracle Java 8:

    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. Restart Docserver services:

    systemctl restart canopy-docserver
    

Example sources for packages

  • epel-release can be sourced from Fedora.

Configuration

As root:

  1. Setup PostgreSQL:

    canopy-setup postgresql
    

    Note

    Oracle users should see the Oracle DB configuration section.

  2. Setup nginx:

    canopy-setup nginx
    

    Optional if you intend to configure your own reverse proxy.

    Note

    Apache users see the Apache configuration section.

    1. (RHEL) (Optional) Configure firewall access. The following commands would open up ports 80 and 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 may connect to Canopy:

      setsebool -P httpd_can_network_connect 1
      
  3. Initialise database (schema and initial data):

    canopy-manage setupdb --prod
    
  4. Create an initial admin user:

    canopy-manage createsuperuser
    

    Skip this step if you are going to import Canopy 2 data.

  5. Configure systemd persistent logging (see the Logging configuration section).

Once the database has been set up and the admin user created, restart the Canopy 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 but by default most Linux distributions do not persist systemd logs. The following commands 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.

Additionally one should adjust the default rate limit for logging as there might be times when Canopy emits large bursts of logs.

In /etc/systemd/journald.conf, set the following:

RateLimitBurst=0  # Disable rate limiting

and reload journald:

systemctl restart systemd-journald

Please see man journald.conf or https://www.freedesktop.org/software/systemd/man/journald.conf.html for more information on how to configure logging.

Apache configuration

Required modules

The following Apache modules are required, over and above what is installed by default:

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

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

Oracle DB configuration

Manual configuration is required to use an existing Oracle Database.

Note

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, 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 database.

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