Installation

Supported platforms

Canopy is officially supported on the following operating systems:

Operating System	Version	Notes
Ubuntu Linux (Highly recommended)	20.04/22.04/24.04 LTS	x86-64 architecture
RedHat Enterprise/Oracle Enterprise/Rocky/Alma Linux	8.x/9.x	x86-64 architecture

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

Key Dependency	Description
PostgreSQL 12.0+	Database server for storing/processing Canopy data. Note that certain database servers may require more resources.
nginx 1.x	Front-end web server for serving the Canopy user interface.
RabbitMQ Server 3.x/4.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.

Overview

The following high level steps need to be completed for a Canopy installation:

1. Install the Canopy and Canopy document server packages (See Platform installation guides section below)

2. Configure the Canopy database, reverse proxy, etc. (See Configuration section)

For upgrades see Upgrading

Platform installation guides

Install on Ubuntu 20.04/22.04/24.04

Canopy

As root:

1. Install Canopy packages:

   apt install -f ./canopy_3.1.0_amd64.deb
   

2. Copy your Canopy license file to /etc/canopy/license. Canopy will output your license details at the top each time you run canopy-manage. This allows you to easily verify if the license is installed properly and if its still valid.

3. 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 8/9, Oracle EL 8/9 and Rocky/Alma Linux 8/9

Canopy

As root:

1. Install rabbitmq-server package:

   1. On Rocky/Alma Linux 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 3.x/4.x from https://www.rabbitmq.com/install-rpm.html#downloads and install their Erlang distribution from https://github.com/rabbitmq/erlang-rpm/releases Check https://www.rabbitmq.com/docs/which-erlang to see which version of erlang should be used with rabbitmq.

      RHEL makes this difficult, use Ubuntu if you want a much simpler installation that is easier to maintain and keep secure over time.

2. Install Canopy:

   yum install ./canopy-3.10.7.el8.x86_64.rpm
   

3. Copy your Canopy license file to /etc/canopy/license. Canopy will output your license details at the top each time you run canopy-manage. This allows you to easily verify if the license is installed properly and if its still valid.

4. 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
   

   Note

   On RHEL 9 when EPEL is in use, Java 17 will be an indirect dependency of Rabbitmq (via erlang). This by default will cause problems as the Canopy docserver only supports Java 1.8/8. Configure the system java version to be 1.8 via update-alternatives –config java

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 for EL 8 can be sourced from https://dl.fedoraproject.org/pub/epel/8/Everything/x86_64/Packages/e/epel-release-8-21.el8.noarch.rpm.

• epel-release for EL 9 can be sourced from https://dl.fedoraproject.org/pub/epel/9/Everything/x86_64/Packages/e/epel-release-9-8.el9.noarch.rpm.

Configuration

As root:

1. Setup PostgreSQL:

   canopy-setup postgresql
   

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. Configure systemd persistent logging (see the Logging configuration section).

Once the database has been set up restart the Canopy services:

systemctl restart canopy canopy-celery

You can now browse to the Canopy server’s address and create an admin user.

Note

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/sample_configs/apache.conf.

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

Get logs for all services for today:

journalctl -u canopy -u canopy-celery -u canopy-docserver --since today

Upgrading

Although the upgrade process is the same for minor and patch releases of Canopy, it is advised to perform backup prior to minor release updates.

Patch release upgrades (e.g. upgrading from 3.2.3 to 3.2.4) are designed to be low risk and our release notes will contain anything you should be aware of. Downgrading to a lower patch release of the same minor version is usually supported.

Some patch releases may contain database migrations, which might affect the ability to downgrade within the minor release.

Minor release upgrades (e.g. upgrading from 3.2.3 to 3.3.0) are inherently more risky as we use them to perform schema changes to the database and other migrations.

Warning

Downgrading to a lower minor release is not supported and backups are highly recommended.

Warning

The postinstall process that is executed during package upgrades can take hours or even days to complete on resource limited instances. This is greatly affected by database latency and available memory.

This process can be executed before upgrading to reduce the work required during an upgrade:

canopy-manage postinstall

Additionally this process can be interrupted and started again later.

See Backups and recovery on how to perform backups.

As the root user:

1. Install new package via apt/yum. Make sure to check the output of the package installation process to see if there are any errors.

2. Restart services:

   systemctl restart canopy canopy-celery canopy-docserver
   

Note

If Canopy, or any of its services, fail to start after an upgrade then the first place to look are the service logs:

journalctl -e -u canopy -u canopy-celery -u canopy-docserver

Check the logs for any obvious errors that might indicate failure. If the upgrade process failed to migrate the database schema, or perform other maintenance tasks, then there will be errors stating this with the actions to take.

Warning

The database must be accessible during the upgrade. If it is not, critical migrations will not be applied.

The migrations can be manually executed prior to restarting the services by running the postinstall command:

canopy-manage postinstall

Configuring a Proxy or other environmental variables

Canopy uses systemd to manage its processes and it requires environment variables to be set in the systemd service override files for both the canopy and canopy-celery services when operating behind a proxy.

These same steps can be followed for any other environmental variables that need to be set.

Setting proxy environment variables

To configure proxy settings for Canopy services using the recommended systemd approach:

1. Edit the systemd service configuration for the canopy service:

   systemctl edit canopy
   

2. Add the proxy environment variables in the editor that opens:

   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:8080"
   Environment="HTTPS_PROXY=http://proxy.example.com:8080"
   

3. Save and exit the editor.

4. Similarly, edit the canopy-celery service:

   systemctl edit canopy-celery
   

5. Add the same environment variables and save:

   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:8080"
   Environment="HTTPS_PROXY=http://proxy.example.com:8080"
   

6. Restart the services to apply the changes:

   systemctl restart canopy canopy-celery
   

Note

You can verify that the environment variables are correctly set by checking the service environment:

systemctl show canopy --property=Environment
systemctl show canopy-celery --property=Environment