Warning

THIS REPOSITORY HAS BEEN SUPERCEDED
please see https://github.com/Kurrawong/anufnp-infra for future work

Australian National University Ansible Prez Stack

An Ansible playbook and roles to manage Debian cloud VMs running the Prez Stack.

Note: This playbook has been tested on Debian 12.

The Prez Stack consists of the following:

• Apache Jena Fuseki (database)
• Prez (backend web API)
• Prez UI (web server serving static web assets for the Prez UI)
• Nginx (web server - ingress proxy to the stack)

The different components of the Prez Stack run inside containers managed by Podman. The containers themselves are not managed directly with Podman but instead are managed via systemctl. Example, to restart the Fuseki container, run sudo systemctl restart container-fuseki. However, manual actions such as these shouldn't be required and instead, they should be actioned through a role within the prez.yml playbook.

Fuseki, Prez and Prez UI all run inside their own containers and they are accessed through an nginx server running on the target machine.

Before starting

This playbook assumes a cloud VM with SSH access has been set up. If you are using AWS, it would be an EC2 instance.

Ensure a DNS record has been set to point to the IP of the VM and update the domain name information in the hosts file and in group_vars/letsencrypt.yml and group_vars/nginx.yml. These values are used to target the VM machine, setup nginx configuration and also SSL certificate registration with Let's Encrypt.

Ansible environment

Ansible version 2.14 and Python 3.9 - 3.11 is required.

Create a Python virtual environment and use it.

python -m venv venv
source venv/bin/activate

Install the Python dependencies.

pip install -r requirements.txt

The Ansible hosts file with a section named webservers manages the target machines these plays apply to.

Ansible playbooks

Viewing/editing Ansible Vault file

The file vault.yml is encrypted using Ansible Vault. To view or edit the file, run the following.

Note: obtain the password from the system system administrator and create a file ./ansiblepass before proceeding.

To edit the vault file, run the following.

ansible-vault edit group_vars/vault.yml --vault-password-file ./ansiblepass

These are the variables in the vault.

vault:
  server:
    # remote server's user, e.g., ec2-user, ubuntu, admin
    user:

  letsencrypt:
    # contact email
    email:

  # Fuseki basic auth credentials
  fuseki:
    username:
    password:

  # Google Maps API key used by Prez UI
  prez_ui:
    google_maps_api_key:

Running Ansible Roles

Run the roles in sequence for a fresh installation. The plays target the servers defined in hosts with the remote_server_user defined in group_vars/vault.yml.

Install nginx, certbot and setup letsencrypt

Variables:

• group_vars/nginx.yml
• group_vars/letsencrypt.yml

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t nginx.install

Install podman

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t podman.install

Enable swap file

Variables:

• group_vars/swapfile.yml

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t swapfile.enable

Install Apache Jena Fuseki

Variables:

• group_vars/nginx.yml
• group_vars/fuseki.yml

Fuseki's exposure to the public internet via nginx is controlled by the nginx.expose_fuseki boolean variable.

Fuseki's basic authentication details such as username and password can be changed by editing group_vars/vault.yml.

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t fuseki.install

Setup the Fuseki data loader container

This container will provide an environment with the required dependencies to create and load Fuseki dataset data.

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t fuseki.data.setup

Create Fuseki dataset

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t fuseki.data.create

Configure Fuseki dataset

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t fuseki.data.configure

Install Prez

Variables:

• group_vars/container_image.yml

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t prez.install

Install Prez UI

Variables:

• group_vars/prez_ui.yml
• group_vars/container_image.yml

ansible-playbook -i hosts --vault-password-file ./ansiblepass prez.yml -t prez-ui.install