VERA is designed to run inside Docker containers. Use the following instructions to install Docker Engine Enterprise on the installation machine.
Note: This section can be skipped if Docker is already installed on the machine.
If the docker info
command is recognized, then Docker is correctly installed.
Docker Compose is used to setup orchestration between the VERA Server, the VERA Web Portal, and the VERA database. Use the following instructions to install Docker Compose on the installation machine.
Note: This section can be skipped if Docker Compose is already installed on the machine.
If the docker-compose --version
command is recognized, then Docker Compose is correctly installed.
VERA uses folder mapping (volume mounting) to create persistent storage outside of the Docker containers. The first step of installation is to create a folder location for each storage item listed below. Tx3's default recommendations are provided, but any storage location (drive and/or folder) may be selected.
Create Storage Locations: Use the following table as guidance to select storage locations for the VERA items listed. You can choose any location you like, or you can follow Tx3's default recommendation. NOTE: For Linux, paths are case sensitive.
Storage Item | Tx3 Recommended Location (Windows) | Tx3 Recommended Location (Linux) | Description |
---|---|---|---|
MongoDB Data Storage | C:\Data\DB | /var/lib/tx3_services/data/db | This location will become the internal storage drive for the MongoDB database. |
Tx3 VERA Server Data Directory | C:\ProgramData\Tx3 Services\ | /var/lib/tx3_services/ | The folder containing all inputs and outputs for the VERA Server. |
Tx3 VERA Web Portal Data Directory (optional) | C:\ProgramData\Tx3 Services\ | /var/lib/tx3_services/ | The folder containing all inputs and outputs for the VERA Web Portal. Usually this is the same as the VERA Server Data Directory. |
Create Folders: Create the following folders within the Tx3 VERA Data Directory selected above.
Required Folder Name | Description |
---|---|
Certificates | A folder for placing SSL certificates used to enable HTTPS on the VERA Server, VERA Web Portal and SSO communication. |
Configs | The folder containing the VERA Web Portal configuration file. |
Logs | The output directory for log files generated by VERA applications. |
Policies | The folder containing the VERA Server configuration files, such as the Records Management Policy, Approval Policy, and Synchronization Policy. |
UserImports | A folder for placing CSV files containing user profiles to import. The VERA Server will monitor this folder for new CSV files that are dropped in. |
Mongo-Setup | A temporary folder for placing setup scripts for the MongoDB database. |
Create folders (sample script)
sudo mkdir -p /var/lib/tx3_services/data/db sudo mkdir /var/lib/tx3_services/Policies sudo mkdir /var/lib/tx3_services/Logs sudo mkdir /var/lib/tx3_services/UserImports sudo mkdir /var/lib/tx3_services/Certificates sudo mkdir /var/lib/tx3_services/Mongo-Setup sudo mkdir /var/lib/tx3_services/Configs |
Stage VERA Policy Files: Copy your configured Tx3 Policy Files to the Policies directory created in Step 2.
Stage VERA Web Portal Configurations: Copy config.yaml to the Configs directory created in Step 2.
Stage MongoDB Setup Script: Copy mongo-users-setup.js to the Mongo-Setup directory created in Step 2.
You may want to change the default passwords in the script file. If you do, be sure to use the correct passwords in the docker-compose file below. |
Sample User import CSV file(userimport.csv)
User Name,Full Name,Email,Groups,IdP,IdP User Name vera_admin,Default VERA Administrator,vera_admin@tx3services.com,System Administrator,VERA,vera_admin:ChangeThis1Pwd |
Both the VERA Web Portal and the VERA Server (API) require the ability to receive inbound HTTP traffic. Each component can accept traffic via HTTP, HTTPS, or both.
Select Ports: Select an HTTP and/or HTTPS port for the VERA Web Portal and the VERA Server (API). Tx3's default recommendations are provided, but any ports may be selected.
Port | Tx3 Recommendation (HTTP / HTTPS) |
---|---|
VERA Web Portal | 80 / 443 |
VERA Server (API) | 8080 / 8443 |
VERA uses JSON Web Tokens (JWT) to securely transmit information between clients and the VERA Server API. These JWTs are digitally "signed" during creation so that their integrity can be verified on subsequent calls without requiring the user to provide login information. A certificate is required to "sign" the JWT. The certificate must be in the PKCS#12 format and can be from a trusted source or a self-signed certificate. The instructions below will create a self-signed certificate in the proper format and upload it to the appropriate location.
Create a Private Key for use in the certificate.
openssl genrsa -aes256 -out private.pass.pem 2048 openssl rsa -in private.pass.pem -out key.pem |
Create the Self-Signing Request. Enter the information requested during the certificate creation.
openssl req -new -key key.pem -out server.csr |
Generate the Self-Sign Certificate.
openssl x509 -req -sha256 -days 3650 -in server.csr -signkey key.pem -out jwt.crt |
The |
Generate a PFX file from the certificate and private key. Provide a password for the PFX file, and make note of the password for a later use in the installation.
openssl pkcs12 -export -out jwt.pfx -inkey key.pem -in jwt.crt |
You must provide a password when creating the PFX file. |
VERA acts as a SAML Service Provider for Single Sign-On. This requires VERA to have a certificate available for signing SAML Requests that are sent to the SAML Identity Provider. The certificates are required for the Web Portal to start up, even if you are not using the SSO feature. The certificate and key must be in the PEM format. The simpliest way to provide these is to use the certificate and key files created above when creating the JWT certificate. If needed, you can follow the instructions below to create a new certificate and key file for the Service Provider.
Create a Private Key for use in the certificate.
openssl genrsa -aes256 -out sp-private.pass.pem 2048 openssl rsa -in sp-private.pass.pem -out sp-privatekey.pem |
Create the Self-Signing Request. Enter the information requested during the certificate creation.
openssl req -new -key sp-privatekey.pem -out sp-server.csr |
Generate the Self-Sign Certificate.
openssl x509 -req -sha256 -in sp-server.csr -signkey sp-privatekey.pem -out sp-publiccert.crt |
Config.yaml Variable | Example Value |
---|---|
samlPrivateKeyFile | sp-privatekey.pem |
samlPublicCertFile | sp-publiccert.crt |
Configure Storage Volumes: The file is pre-configured with the Tx3 default recommendations for storage locations (as described above). If any non-default storage location was selected previously, then update the Docker Compose file as necessary:
Docker Service | Configuration Item | Default Configuration (Windows) | Default Configuration (Linux) |
---|---|---|---|
Vera.Mongo | MongoDB Data Storage Location | C:\Data\DB | /var/lib/tx3_services/data/db |
Vera.Server | Tx3 VERA Data Directory | C:\ProgramData\Tx3 Services | /var/lib/tx3_services |
Vera.Web.Portal | Tx3 VERA Web Portal Data Directory | C:\ProgramData\Tx3 Services | /var/lib/tx3_services |
Configure VERA Server Encryption Key: VERA Server encrypts stored user passwords. You must supply the encryption key for VERA to use to encrypt and decrypt user passwords. The encryption key is stored in the following environment variable of the docker compose file:
Docker Service | Configuration Item | Default Configuration |
---|---|---|
Vera.Server | VERA_SERVER_ENCRYPTION_KEY | <Enter an encryption key> |
Configure VERA Server JWT Certificate and Password: VERA Server uses JWTs to authenticate users. A certificate must be present on the server in order to validate incoming JWTs. The certificate is stored in the Certificates directory and must be in the PFX format. A password-protected PFX certificate file should have been created during an earlier step of these instructions. Provide the filename and password of the generated PFX file in the following environment variables of the docker compose file:
Docker Service | Configuration Item | Default Configuration |
---|---|---|
Vera.Server | VERA_SERVER_JWT_CERT_NAME | <JWT Certificate File Name, eg. jwt.pfx> |
Vera.Server | VERA_SERVER_JWT_CERT_PASSWORD | <JWT Certificate Password> |
If you use a $ character in your password, you will need to escape the character with another $. E.g. $ would be $$ in the docker-compose file. Quotes may also be needed if using other special characters. |
Configure Ports: The file is pre-configured with the Tx3 default recommendations for TCP/IP ports (as described above). If any non-default port was opened previously, then update the Docker Compose file as necessary:
Configuration Item | Default Configuration |
---|---|
VERA Server API Port (HTTP) | 8080 |
VERA Server API Port (HTTPS) | 8443 |
VERA Web Portal Port (HTTP) | 80 |
VERA Web Portal Port (HTTPS) | 443 |
(NOTE: For each modified configuration, be certain to only update the first number in each pair of mapped ports. The second port number in each configuration is the internal port number of Docker's internal container network.)
Choose whether to enable or disable support for HTTPS in the VERA Web Portal.
Edit the docker-compose.yml file as follows:
Docker Environment Variable | Value |
---|---|
VERA_WEB_HTTPS_FILE | <PFX file name> Example: My-server.pfx |
VERA_WEB_HTTPS_PASS | <PFX Password> example: crypticpassword |
Delete the web portal's SSL port mapping configuration from the docker-compose.yml file. (Unless previously edited, this configuration mapped port 443 to port 443 inside the vera.web.portal service.)
Choose whether to enable or disable support for HTTPS in the VERA Server (API).
Edit the docker-compose.yml file as follows:
Docker Environment Variable | Value |
---|---|
ASPNETCORE_Kestrel__Certificates__Default__Path | <PFX file name> example: My-server.pfx |
ASPNETCORE_Kestrel__Certificates__Default__Password | <PFX Password> example: crypticpassword |
Edit the docker-compose.yml file by changing the following configurations;
Server
property to point to the target server's REST API URL. (example: http://jira.example.com:8080/rest/api/latest)Service Account
property to contain the user ID of the network service account. Server Password
property of the Synchronization Policy to contain the encrypted password.Make sure the image tag selected for the MongoDB image in the setup-mongo.yaml file matches the image tag in the docker-compose.yml file above. |
docker-compose -f ./setup-mongo.yaml up
If you get the error: "Couldn't connect to Docker deamon - is it running?"
docker login veraserver20190209075900.azurecr.io -u fc12bdd5-6753-40b3-a4da-32bc5d451b39 -p bhfV1g0RhN1O~xS-R-Osv67~HO.zeKMbHp
docker-compose up -d
Table of Contents