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
andCortex
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 login to the Synapse UI and invite other users.
To add a new admin user to the 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_JSONSTOR=aha://jsonstor...
- 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!
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
The admin user created on the Cortex should now be able to login to the Synapse UI
at https://<yournetloc>
.
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!