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 on your server, Docker Compose or Vagrant are recommended.

If you are an individual deploying the app on your local machine, Docker (for individuals) 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 (playbook.yml)

To deploy the BRECcIA Network Mapper with Ansible:

Download and extract the deployment files from the latest release:

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

Copy your logo (192x192 pixels) to icon-192x192.png in the network-mapper folder.
Copy example.env to .env:
```
cp example.env .env
```
Edit this file as desired. Note that some variables are required, and that True and False values must have correct capitalisation.
Copy inventory.example.yml to inventory.yml:
```
cp inventory.example.yml inventory.yml
```
Edit this file to reflect your Ansible setup:
- Use your server’s hostname instead of example.com
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.

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:

Download and extract the deployment files from the latest release:

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

Copy your logo (192x192 pixels) to icon-192x192.png in the network-mapper folder.
Copy example.env to .env:
```
cp example.env .env
```
Edit this file as desired. Note that some variables are required, and that True and False values must have correct capitalisation.
Start the containers with the following command (you may need to use sudo):
```
docker compose up -d
```
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:

To deploy the BRECcIA Network Mapper with Vagrant:

Download and extract the deployment files from the latest release:

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

Copy your logo (192x192 pixels) to icon-192x192.png in the network-mapper folder.
Copy example.env to .env:
```
cp example.env .env
```
Edit this file as desired. Note that some variables are required, and that True and False values must have correct capitalisation.
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.
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.
Start the virtual machine:
```
vagrant up
```
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 (for individuals)

This is the recommended deployment method for individuals who are not planning on making the network mapper accessible to other users.

Warning

The network mapper will not run with Docker on Arm-based devices. This includes devices with Apple silicon - e.g. M1 and M2 Macs.

To run it on these devices you will need to build it yourself, which requires additional knowledge of Docker.

Prerequisites:

Docker Compose is installed and running. If you are not familiar with Docker, we recommend using Docker Desktop. Simply install and run it.

To deploy the BRECcIA Network Mapper with Docker:

Download deploy-docker.zip from the latest release.
Extract the zip file into an appropriate folder.
Copy your logo (192x192 pixels) to icon-192x192.png in the network-mapper folder.
Copy example.env to .env in this folder.
Edit this file as desired. Note that some variables are required, and that True and False values must have correct capitalisation.
- Variables are set with the following syntax, in this case setting the DEBUG variable to False:
```
DEBUG=False
```
Open a terminal window in this folder. On Windows, do this by holding Shift and right clicking inside the folder; then selecting either Open in Terminal or Open PowerShell window here.
Start the network mapper with the following command:
```
docker compose up -d
```
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"
```

Once the network mapper has been started for the first time with the above steps, it will appear in Docker Desktop (if installed). It can then be stopped/started again from here.

To stop it from the terminal, run

docker compose down