Deployment Guide

Introduction

This guide will walk you through a production Synapse User Interface deployment. The Synapse UI will register with AHA for service discovery and future devops tasks, and therefore this guide assumes the Synapse Deployment Guide has been followed.

As in the Synapse Deployment Guide, docker-compose will be used as a light-weight orchestration mechanism.

Preparation

With the Synapse Deployment Guide completed, the following items will be needed before starting the Synapse UI deployment:

Access to the running AHA and Cortex containers.
The previously chosen network name; referred to as <yournetwork> in this guide.
A host prepared as specified by Prepare your Hosts.
SMTP server configuration options for invitation emails and password recovery.
A netloc value comprised of the hostname and optional port that users will use to connect to the Synapse UI.

Netloc

netloc refers to the hostname and optional port that the Synapse UI should expect to be reached via. It is used in the generation of invitation emails and SAML authentication (if configured). An incorrect value will prevent users from registering and logging in to the Synapse UI.

netloc defaults to loop.vertex.link:4443 for test deployment purposes. In real deployments it should be set appropriately to something such as ui.syn.acmecorp.com.

Replacing the automatically generated self-signed HTTPS certificate with your own is strongly recommended in production deployments. The common name (CN) on the certificate should match your selected netloc value. See Use Custom HTTPS Certificates for more information.

We will use <yournetloc> in the following configs to specify locations that should be replaced with your selected netloc.

Bootstrap an Admin User

An admin user account with a password is required to log in to the Synapse UI and invite other users.

The Synapse UI authenticates users via the Cortex it is connected to, so all Cortex users are Optic users without any extra configuration.

To add a new admin user to your connected Cortex, run the following command from inside the Cortex container:

python -m synapse.tools.moduser --add --admin true visi --passwd secret

Deployment

Inside the AHA container

Generate a one-time use provisioning URL:

python -m synapse.tools.aha.provision.service 00.optic

You should see output that looks similar to this:

one-time use URL: ssl://aha.<yournetwork>:27272/<guid>?certhash=<sha256>

On the Host

Create the container directory:

mkdir -p /srv/syn/00.optic/storage
chown -R 999 /srv/syn/00.optic/storage

Create the /srv/syn/00.optic/docker-compose.yaml file with contents:

version: "3.3"
services:
  00.optic:
    user: "999"
    image: vertexproject/optic:v2.x.x
    network_mode: host
    restart: unless-stopped
    volumes:
        - ./storage:/vertex/storage
    environment:
        - SYN_OPTIC_AXON=aha://axon...
        - SYN_OPTIC_CORTEX=aha://cortex...
        - SYN_OPTIC_NETLOC=<yournetloc>
        - SYN_OPTIC_HTTPS_PORT=443
        - SYN_OPTIC_AHA_PROVISION=ssl://aha.<yournetwork>:27272/<guid>?certhash=<sha256>
        # SMTP configuration options
        - [email protected]  # The "from" address for emails sent by the application
        - SYN_OPTIC_EMAIL_HOST=email.acmecorp.com
        - SYN_OPTIC_EMAIL_PORT=587
        - SYN_OPTIC_EMAIL_AUTH={"user":"foo","pass":"secret"}

Note

Don’t forget to replace your one-time use provisioning URL!

Note

In the event that you’re an unprivileged user attempting to bind a privileged port, such as in the above example, you will need to ensure the Linux sysctl net.ipv4.ip_unprivileged_port_start is set to a value lower than the port you are attempting to bind.

For the above example, net.ipv4.ip_unprivileged_port_start should be set to a value of 443 or less to allow user 999 to bind port 443. You can accomplish this via the sysctl command:

sysctl net.ipv4.ip_unprivileged_port_start=443

Editing /etc/sysctl.conf or writing to the /proc/sys file system will also produce the desired result.

Start the container:

docker-compose --file /srv/syn/00.optic/docker-compose.yaml pull
docker-compose --file /srv/syn/00.optic/docker-compose.yaml up -d

Remember, you can view the container logs in real-time using:

docker-compose --file /srv/syn/00.optic/docker-compose.yaml logs -f

Log in to the Synapse UI

The admin user created on the Cortex should now be able to log in to the Synapse UI at https://<yournetloc>. See the Log in to Optic docs for instructions on how to log in.

Add the Service to the Cortex

From the Console tool within the Synapse UI add the service to the Cortex:

> service.add optic aha://optic...

What’s next?

See the Devops Guide for instructions on performing various maintenance tasks on your deployment!

Invite other users

The Synapse UI provides a convenient way to manage users, roles and more.

After logging in as an admin user, navigate to the Admin tool via the gear icon in the lower left corner of your screen.