-
Notifications
You must be signed in to change notification settings - Fork 24
2. Install Configuration Guide
This guide will go through the basic deployment instructions by using Ansible playbooks. Ansible is a Python-based configuration mangement framework. The quickstart repo contains Ansible playbooks which will configure all the reternal services on a local or remote machine.
The default (standalone) playbook will deploy all individual services on a single machine. There are multiple playbooks included for local development or remote deployment.
Navigate to the directory containing the ansible playbooks:
cd reternal-quickstart/ansible
The deployment configuration can be found inside the inventories/standalone//group_vars/reternal.yml file. Be sure to modify at least the following variables to match your environment:
reternal:
phase: <development||deployment>
install_dir: "{{ lookup('env','HOME') }}/opt/reternal"
domain: "reternal.local"
Running reternal in development mode will configure the services in debug state and mount the source code of the individual projects into the containers for easier development and live reload/debugging. Be sure to specify the correct build_path in the same configuration file. The ansible roles for development will build the images instead of pulling them from Docker hub. You should never use the development configuration on a remote machine.
Deployment mode will not require any additional changes. The ansible role will pull the images from Docker hub instead of building them locally. This also means that the build_path variable will not be used. Instead you can pin specific reternal images by modifying the tag variable for each listed service (latest/dev by default).
The Ansible vault is an encrypted file that stores your secrets for the Reternal infrastructure. A role is included to create a template for your Vault and generate random passwords for MongoDB and Reternal secrets and passphrases. Execute the below command inside the reternal-quickstart/ansible directory to initialise the Vault:
ansible-playbook secrets.yml
The standalone.yml file is a role definition file that states what components should be configured/installed on your infrastructure. The role uses the secrets in the previously created vault file to secure the Reternal components. To run the deployment role, execute the following command and specify your vault and your sudo/su password:
Running reternal locally for development does not require any changes to the existing config. If you have docker installed, simply run the below command to get the environment running:
ansible-playbook reternal.yml -i inventories/standalone/dev/hosts.ini --ask-vault-pass
Add the destination host's IP address to the ansible host config. This file can be found at inventories/standalone//host_vars/rtn-dev-01. Change the following line to match with your target destination IP/hostname
ansible_host: &mgt_addr 192.168.90.243
Run the ansiple playbook afterwards and include the prefered method for gaining extra privileges
ansible-playbook reternal.yml -i inventories/standalone/test/hosts.ini --ask-become-pass --become-method=sudo --ask-vault-pass --user <ssh username>
When completed, you can access reternal on https://<your_domain_or_ip>:8443
If your target system does not use SUDO you can change the --ask-become-method=sudo to --ask-become-method=su. Ansible will use pub/priv key authentication by default. If you want to use a password instead of a private key, add --ask-pass to the end of the command.
More information about the command parameters and specific access options can be found on the Ansible wiki @ https://docs.ansible.com/ansible/latest/user_guide/become.html.
If a reternal component update is available you can use the corresponding tags to only run a specific subrole. The tags available are listed inside the reternal.yml playbook/file. Simply add the --tags argument behind your ansible-playbook command to only deploy an individual subcomponent. For instance, to only update/deploy the API container execute:
ansible-playbook reternal.yml -i inventories/development/hosts.ini --ask-become-pass --ask-vault-pass --tags 'api'
Ansible works with the principles of roles that define what, when how applications should be deployed and inventories that define your infrastructure and host-based settings. The quickstart repo contains the following directory structure that requires some manual changes based on your own infrastructure:
inventories/
standalone/
dev/
hosts.ini (ini file that contains the host names and group definitions)
host_vars/
<hostname|rtn-dev-01>.yml (hosts file containing host-specific variables such as IP etc)
group_vars/
<group|reternal>.yml (variables that apply to hosts in the reternal group)