breccia-mapper/docs/source/deployment.md

The BRECcIA Network Mapper can be deployed in a variety of ways, most of which utilise Docker. Ansible deployment has been tested on RHEL7 and RHEL8.

Ansible

Prerequisites:

• Ansible

:::{note} Deployment with Ansible has been tested on RHEL7 and RHEL8, but is compatible with other Linux distributions with minor changes to the playbook (deploy/playbook.yml) :::

To deploy the BRECcIA Network Mapper with Ansible:

1. Download and extract the deployment files from the latest release:

   curl https://github.com/Southampton-RSG/breccia-mapper/releases/latest/download/deploy-ansible.tar | tar xzv && cd deploy-ansible
   

2. Copy your logo (192x192 pixels) to icon-192x192.png in this folder.

3. Copy example.env to .env:

   cp example.env .env
   

4. Edit this file as desired. Note that some variables are required.

5. Copy inventory.example.yml to inventory.yml:

   cp inventory.example.yml inventory.yml
   

6. Edit this file to reflect your Ansible setup:

• Use your server's hostname instead of example.com

7. If you would like a new superuser to be provisioned (e.g. during initial install), edit the provision_superuser variable in playbook.yml to true.

• Then change the superuser_* options below it as desired.

8. Run the Ansible playbook playbook.yml with this inventory file using:

   ansible-playbook playbook.yml -i inventory.yml -K -k -u <SSH username>
   

This will ask for your SSH and sudo passwords for the server before deploying. To redeploy updates, the same command can be run again - it's safe to redeploy on top of an existing deployment.

:::{warning} If you changed the provision_superuser variable in playbook.yml to true, remember to change it back to false. :::

Docker Compose

Prerequisites:

• Docker Compose (installed by default with most Docker installs)

:::{note} Deployment with Docker has been tested on RHEL7, RHEL8, and Ubuntu 22.04 LTS :::

To deploy the BRECcIA Network Mapper with Docker:

1. Download and extract the deployment files from the latest release:

   curl https://github.com/mgrove36/Southampton-RSG/releases/latest/download/deploy-docker.tar | tar xzv && cd deploy-docker
   

2. Copy your logo (192x192 pixels) to icon-192x192.png in this folder.

3. Copy example.env to .env:

   cp example.env .env
   

4. Edit this file as desired. Note that some variables are required.

5. Create the database using:

   touch db.sqlite3
   

6. Start the containers with the following command (you may need to use sudo):

   docker compose up -d
   

7. If desired (e.g. on initial deployment), create a superuser by running the following, and enter their details when prompted:

   docker compose exec -it server /bin/bash -c "/app/manage.py createsuperuser"
   

:::{important} If you don't create a superuser when you first deploy the app, you will be unable to log in. :::

Vagrant

Prerequisites:

• Vagrant
• Ansible

To deploy the BRECcIA Network Mapper with Vagrant:

1. Download and extract the deployment files from the latest release:

   curl https://github.com/mgrove36/Southampton-RSG/releases/latest/download/deploy-vagrant.tar | tar xzv && cd deploy-vagrant
   

2. Copy your logo (192x192 pixels) to icon-192x192.png in this folder.

3. Copy example.env to .env:

   cp example.env .env
   

4. Edit this file as desired. Note that some variables are required.

5. If you would like a new superuser to be provisioned (e.g. during initial install), edit the provision_superuser variable in playbook.yml to true.

• Then change the superuser_* options below it as desired.

6. To change where the app is accessible from, edit the config.vm.network line in Vagrantfile.

• By default, the app is accessible only from http://localhost:8080.
• To make it available from any IP address, replace host: 8080, host_ip: "127.0.0.1" with host: 8080.
• To change the port the app is available on, edit host: 8080.
• More details are available in the Vagrant docs.

6. Start the virtual machine:

   vagrant up
   

7. Deploy the Network Mapper on the virtual machine:

   vagrant provision
   

:::{note} To stop the virtual machine, run vagrant halt in this directory. More commands are explained in the Vagrant docs. :::