breccia-mapper/docs/source/deployment.md

1 Deployment

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.

Choosing How to Deploy

If you are an organisation deploying the app on a server, Ansible is recommended. If Ansible is not used with your server, Docker Compose or []Vagrant are recommended.

If you are an individual deploying the app on your local machine, Docker Desktop is recommended. However, if you are planning on making the app accessible to other people (outside your computer), we advise deploying the app on a server.

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 network-mapper
   

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/Southampton-RSG/releases/latest/download/deploy-docker.tar | tar xzv && cd network-mapper
   

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. Start the containers with the following command (you may need to use sudo):

   docker compose up -d
   

6. 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/Southampton-RSG/releases/latest/download/deploy-vagrant.tar | tar xzv && cd network-mapper
   

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.

7. Start the virtual machine:

   vagrant up
   

8. 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. :::

Docker Desktop

Coming soon.