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
- Tell the server that it is going to get its salt configuration locally, not from a salt master
- Identify the node as an all-services node which means all of 3Diax is installed on a single node
- 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
- Download new deployment instructions, if necessary, by updating the
deployment
module itself - Download updates to the pip packages for each service and install them
- 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.