Ansible collection for deploying applications using Polaris Pipelines.
This collection provides roles for the deployment and configuration of application services on NRIDS servers.
This collection requires Ansible 2.12 or higher.
This collection was designed for Red Hat Enterprise Linux 9.
- common - Defines variables used by the rest of the collection
- create_project_directories - Creates the directory structure for a service
- jdk - Installs and configures Adoptium OpenJDK
- nodejs - Installs and configures Node.js
- nodejs_app - Installs a Node.js application
- patch_intention - Sends a patch request to NR Broker to update the catalog
- port_manager - Automates the assignment and management of service ports
- self_signed_cert - Creates a self-signed certificate for the service
- service_control - Automates starting, stopping, and restarting installed services
- tomcat - Automates the installation and configuration of Apache Tomcat
- webade_connection_jar - Creates and installs a WebADE connection JAR file
- webapp - Configures and deploys a WAR file to Tomcat
The collection uses no external plugins. There is an internal s6 module that the service_control role may use.
Start by reviewing common, as every role includes it. It defines many of the defaults that other roles use. If you want a value to be picked up globally, define one of the values from this role. If you want a value to be used only by a single role, define the role-specific variable.
Next, create_project_directories is used to create the directory structure for a service. Other roles require that this role be called first.
After this, playbooks call various roles to add binaries, application files, and configure the application as required.
All global variables defined in the common role are prefixed with polaris_. The collection's roles other than common generally prefix their variables with the name of the role. Roles will use the global "polaris" variables to derive their own variables. So, a developer can override the global variable to change a value across many roles.
Developers should prefix their own variables with their service or project name and treat the role names (and polaris) as reserved prefixes for the collection. Example: An developer should not define webapp_app_tmp_dir because webapp is used by the webapp role as its prefix.
The general advice is that developers should:
- Not define collection role variables unless required to
- Use polaris global variables to derive their own variables
Developing the roles requires having a machine available to target with Ansible. It is highly recommended to use Vagrant to create a local virtual machine using the provided Vagrantfile. The local VM can be provisioned from scratch in a couple of minutes.
In addition, application developers can use the Vagrant VM to test their playbooks. Most deployment issues can be resolved this way without needing to deploy to real servers.
- Vagrant
- VirtualBox (on macOS)
We do not provide a container image for use with Podman or Docker because applications are installed into a stateful server. Containers are set up to run a single executable with no system services (like SSH) available. They also have a simplified file system security model.
In the end, we want to mimic the server and not simply run the application. The VM created by Vagrant operates like a server in ways a container cannot replicate.
This will set up the development virtual machine. It will take some time to download the image and complete the setup.
vagrant up
This setups the vagrant user to be able to use systemd and sets the following env:
ANSIBLE_LIBRARY=/home/vagrant/polaris/deploy/plugins
You now have a running provisioned vm that you can connect to using vagrant ssh.
Precondition: Running provisioned vm
This first step in all of the following examples is to upload the polaris collection to the vagrant vm.
vagrant ssh -c 'rm -r polaris'
vagrant upload -c polaris
By default, the upload command merges the files in the path. It is recommended that you clear out the polaris folder and start from scratch whenever you want to upload a new playbook as the existing files in polaris/deploy may conflict.
Precondition: Upload collection
This will upload the test playbooks to the vm.
vagrant upload test polaris/deploy
Next, connect to the virtual machine and run the test playbooks. You can then check the state of the virtual machine, re-upload files, and re-run as needed. Some examples using the test playbooks are shown next.
Precondition: Upload collection and test playbooks
vagrant ssh
cd ~/polaris/deploy
ansible-playbook nodejs.yml
/apps_ux/sample/service/artifact/bin/nodejs/bin/node -v
# curl app -- port may be different if multiple apps installed
curl localhost:8080
Precondition: Upload collection, test playbooks and install app (example assumes test playbook's nodejs)
This shows how to stop an application.
vagrant ssh
cd ~/polaris/deploy
# Test service control stop (Change action/var as needed)
ansible-playbook -e service_control_var=nodejs \
-e service_control_action=stop \
servicectrl.yml
# curl app -- port may be different if multiple apps installed (fail expected)
curl localhost:8080
If you change the service_control_action to start then the app should come back.
Precondition: Copy collection
vagrant upload <application root>/playbooks polaris/deploy
vagrant upload overlay_nodejs polaris/deploy
vagrant ssh
mkdir -p polaris/app
cd polaris/app
oras pull ghcr.io/bcgov/nr-nodejs-sample/package:v3.2.0
cd ../deploy
ansible-playbook -e env_vars=vagrant playbook.yaml
Precondition: Copy collection
vagrant upload <application root>/playbooks polaris/deploy
vagrant upload overlay_java polaris/deploy
vagrant ssh
mkdir -p /ansible/downloads
cd /ansible/downloads
sudo curl -L -H "Authorization: token ${GH_TOKEN}" \
https://maven.pkg.github.com/bcgov/java-maven-pipeline-example/bcgov/example/java-maven-pipeline-example/1.0.1-main-SNAPSHOT/java-maven-pipeline-example-1.0.1-main-20250818.180118-27.war \
-o java-maven-pipeline-example.war
cd ~/polaris/deploy
ansible-playbook -e env_vars=vagrant playbook.yaml
See: LICENSE