Canopy Client Portal configuration¶

This page contains instructions for configuring the Canopy Client Portal with a Canopy instance, after installation.

Note

Canopy Portal is in beta testing at the moment. Once it is generally available, instructions will be provided on how to gain access to a license for running this additional service.

Step-by-step guide¶

Installation on Ubuntu 16.04/18.04 or RHEL/OEL/CentOS 7¶

As root:

Install Canopy Portal

Ensure you are installing one of the supported versions available from https://clients.checksec.com. The below filenames are for illustration purposes only.
1. Ubuntu:
  apt install -f ./canopyportal_0.0.2~18.04_amd64.deb
2. RHEL/OEL/CentOS 7:
  yum install -y ./canopyportal-0.0.2.el7.x86_64.rpm
Initialise the DB:
```
canopyportal-manage setupdb --prod
```
Create the first user (Use an email address for username):
```
canopyportal-manage createsuperuser
```
Setup a webserver to act as reverse proxy:
```
canopyportal-setup nginx
```
Restart the service:
```
systemctl restart canopyportal
```
Confirm restart was successful by viewing logs:
```
journalctl -u canopyportal
```

Linking the Portal to Canopy¶

Create a Portal user that will sync data from Canopy:
```
canopyportal-manage createsuperuser
```
Note

This user account’s details must not be shared with the clients who are the target users of the Portal. Separate Portal user accounts should be created for them (step 6).
Log into the Portal’s administration interface, with the new super user account at https://CANOPYPORTAL/admin/.
Add an API token for the super user which will be used to sync data from Canopy to this Portal instance:
1. Click + Add next to Tokens, or go directly to the Add Token page.
2. Select the super user in the combo box.
3. Click Save.
In Canopy’s admin section, ensure that a Portal entry exists for the newly installed Portal. Copy the hexadecimal token, created in step 3, to the Auth Token field of the Portal entry.
In Canopy, associate the appropriate client(s) with the new Portal entry: Clients List → <Select client> → Edit → Portal field.

Creating Portal users¶

Create and link Portal users to the appropriate Canopy client(s):

Portal users not linked to any clients, will not be able to log into the standard (non-admin) web interface, even if they are super/admin users.
1. Select a user from the Portal’s administration user list.
2. Select the client(s) whose data that user needs access to, in the Clients field (at the time of writing, it is the last field on the page).
3. Click Save.
(Optional) Log into the Portal with users associated with clients, to check that the expected data is accessible.

To force a sync with the newly added Portal, select the Portal from the Portal list (Admin → Portals) in Canopy and click the Manually synchronize portal toolbar button. All portals can also be manually synced via the command line by running:

canopy-manage portals --sync

Logging configuration¶

Canopy Portal 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 Portal 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.