Redhat Enterprise Linux 7

These instructions were created using RHEL 7.2 HVM on Amazon Web Services EC2 with (ami-775e4f16)

Python 3

We’ll be needing python 3.4 or greater to run several of the services. You can download and build python from source if you’d prefer, but I’m happy enough to use the RPMs from IUS.

sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-7
sudo yum -y install https://rhel7.iuscommunity.org/ius-release.rpm
sudo rpm --import /etc/pki/rpm-gpg/IUS-COMMUNITY-GPG-KEY

Now you should be able to install python35 with

sudo yum -y install python35u

You can check this worked with

python3.5 --version

You should see an output like:

[ec2-user@ip-10-0-0-19 ~]$ python3.5 --version
Python 3.5.3

We’ll need a link setting python3` to the python 3.5 install we just made

sudo ln -s /usr/bin/python3.5 /usr/bin/python3

This makes it possible for us to reference python3 and get whatever the system install version is in our code and configurations

Pip

We use pip to install our software. We’ll need pip next

sudo yum -y install python35u-pip

Same as before, we’ll need a link to pip

sudo ln -s /usr/bin/pip3.5 /usr/bin/pip3

And we can test the installation and link with:

[ec2-user@ip-10-0-0-19 ~]$ pip3 --version
pip 9.0.1 from /usr/lib/python3.5/site-packages (python 3.5)

Next we need to configure authentication for pip so that we can pull down the pip packages that our installation is allowed to have. You’ll need to write a configuration file at /etc/pip.conf with your favorite editor of the form:

[global]
extra-index-url=https://some-pip-user:my-pip-password@pip.authentise.com/pip/

The username and password should have been provided to you as part of your installation kit

Deployment

We need to install the deployment package which will take care of the rest of the installation steps

sudo pip3 install deployment

That should give you output like:

[eli@usc1-test-redhat1 ~]$ sudo pip3 install deployment
Collecting deployment
  Downloading https://pip.authentise.com/pip/deployment/deployment-2.3.tar.gz (68kB)
    100% |████████████████████████████████| 71kB 1.3MB/s
Collecting requests (from deployment)
  Downloading requests-2.13.0-py2.py3-none-any.whl (584kB)
    100% |████████████████████████████████| 593kB 1.8MB/s
Installing collected packages: requests, deployment
  Running setup.py install for deployment ... done
Successfully installed deployment-2.3 requests-2.13.0

This indicates that the pip configuration is working and you now have the main package for bootstrapping 3DIAX. You should have a directory structure that looks like this:

(ve) [root@ip-10-0-0-19 ~]# ls /usr/deployment/salt/states
alembic       configurations  jenkins      numpy         rsync.sls    unzip.sls
apt.sls       cron            jspm.sls     opencv        slicers      uwsgi
blender.sls   geolus          letsencrypt  pip           sources      virtualenv.sls
boto          github.sls      _modules     postgres      _states
certificates  git.sls         mysql        python        supervisord
cmd.sls       gulp.sls        nginx        rabbitmq.sls  swap.sls
common        jboss           npm.sls      rackspace     top.sls

The above is approximate based on a snapshot of our deployment scripts - there may be minor differences over time as this documentation gets old and out-of-date

Salt

We use salt to configure the server(s) in your local install so that the various services can talk to each other and to ensure their dependencies are correctly installed. Next we’ll need to install and configure salt

sudo yum install -y salt-minion

That should install the salt minion package. You can check the installation worked correctly with:

[root@ip-10-0-0-19 srv]# salt-minion --version
salt-minion 2015.5.10 (Lithium)

Your package manager likely installed a large, well-commented version of the salt minion file at /etc/salt/minion. You can safely remove the contents and replace them with these few lines:

file_client: local
id: all-services
file_roots:
    prod:
        - /usr/deployment/salt/states
pillar_roots:
    prod:
        - /etc/salt/prod
ca.cert_base_path: '/etc/pki'

The primary purpose of this config file is to

  1. Tell the server that it is going to get its salt configuration locally, not from a salt master
  2. Identify the node as an all-services node which means all of 3Diax is installed on a single node
  3. Point to the salt instructions and pillar configuration on disk

When you installed the deployment package using pip it downloaded and saved the state instructions for salt at /usr/deployment/salt/states. It also created a pillar top.sls file at /usr/deployment/salt/pillars/top.sls. Now you just need to take the all.sls file that Authentise provided you with and copy it to /usr/deployment/salt/pillars/all.sls.

sudo mkdir -p /etc/salt/prod
sudo cp /usr/deployment/salt/pillars/top.sls /etc/salt/prod/top.sls
sudo cp ~/all.sls /etc/salt/prod/all.sls

Once you’ve done that you can use salt to configure your server. You do that by running highstate:

sudo salt-call state.highstate -l debug 2>&1 | tee /tmp/3diax-install.log

This may take a long time to run as it installs several OS packages, downloads services from Authentise and configures them. The -l debug tells the command to show debug-level log messages so that you can more easily see what the system is doing and watch for progress

The final output of the highstate call should look something like this:

Summary
--------------
Succeeded: 203
Failed:      0
--------------

If there are any failures listed you should contact Authentise support and provide the output of the highstate command with debug enabled so we can have the maximum available data to help you. The command above will create a log of the data at /tmp/3diax-install.log which you can send to Authentise

SSL

Many organizations provide their own internal SSL certificates for 3Diax services. If your organization runs a Certificate Authority internally we recommend that you create either an SNI-enabled certificate with each of 3DIAX services listed or a single wildcard certificate for all of 3Diax’s services. You then configure all of the services to use the same certificate. This is usually easier than handling a certificate for each service.

Authentise currently installs services with the following names:

app
callback
data
erp
events
geometricsearch
gigan
integrations
installers
logs
models
packing
payment
print
rabbitmq
quoting
quickslice
sirenia
syphon
stream
swarm
streamus
tetra
users
vision
woodhouse

The full name for the service will depend on your installation specifics. For example, if your organization runs a TLD such as acme.com the service names could be something like app.authentise.acme.com and callback.authentise.acme.com and so on.

The certificate should be installed to /etc/pki/tls/certs/sites.authentise.pem and the key should be installed to /etc/pki/tls/certs/sites.authentise.key. These should be in X.509 format

Upgrades

Most contracts with Authentise include ongoing upgrades to Authentise services and software. In most cases upgrades can be handled automatically by salt. Just run highstate:

sudo salt-call state.highstate

This will perform a 3-part upgrade of the code

  1. Download new deployment instructions, if necessary, by updating the deployment module itself
  2. Download updates to the pip packages for each service and install them
  3. Tell the services to gracefully restart and pick up the new installation

In the case of web frontends the restart should chain through various uwsgi processes that handle requests so that new code is rolled out without any interruption in service. For backend processes any ongoing work my be abruptly aborted. Aborted work will be retried after a timeout period and will be handled by the new code. This may mean a slight delay in backend processes making progress. For example, snapshot rendering that normally takes a couple of seconds may take 10-20 seconds during the upgrade.