me/breccia-mapper
1
0
Fork 0
mirror of https://github.com/Southampton-RSG/breccia-mapper.git synced 2026-03-03 03:17:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Rename files for section ordering

Browse Source
This commit is contained in:
Matthew Grove
2023-03-24 19:58:05 +00:00
parent 79bb6cc415
commit f6bfcceb6c
2 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
docs/source/1-deployment.md Normal file
View File

@@ -0,0 +1,194 @@
# 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](#ansible) is recommended. If Ansible is not used with your server, [Docker Compose](#docker-compose) or [][Vagrant](#vagrant) are recommended.
If you are an individual deploying the app on your local machine, [Docker (for individuals)](#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](https://www.ansible.com/)
:::{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](https://github.com/Southampton-RSG/breccia-mapper/releases/latest):
```bash
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 the `network-mapper` folder.
3. Copy `example.env` to `.env`:
```bash
cp example.env .env
```
4. Edit this file as desired. Note that some variables are required.
5. Copy `inventory.example.yml` to `inventory.yml`:
```bash
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:
```bash
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](https://docs.docker.com/compose) (installed by default with most [Docker](https://docker.com/) 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](https://github.com/Southampton-RSG/breccia-mapper/releases/latest):
```bash
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 the `network-mapper` folder.
3. Copy `example.env` to `.env`:
```bash
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`):
```bash
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:
```bash
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](https://www.vagrantup.com/)
- [Ansible](https://www.ansible.com/)
To deploy the BRECcIA Network Mapper with Vagrant:
1. Download and extract the deployment files from [the latest release](https://github.com/Southampton-RSG/breccia-mapper/releases/latest):
```bash
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 the `network-mapper` folder.
3. Copy `example.env` to `.env`:
```bash
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](https://developer.hashicorp.com/vagrant/docs/networking).
6. Start the virtual machine:
```bash
vagrant up
```
7. Deploy the Network Mapper on the virtual machine:
```bash
vagrant provision
```
:::{note}
To stop the virtual machine, run `vagrant halt` in this directory. More commands are explained in the [Vagrant docs](https://developer.hashicorp.com/vagrant/docs/cli).
:::
## 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](https://docs.docker.com/compose) is installed and running. If you are not familiar with Docker, we recommend using [Docker Desktop](https://docs.docker.com/desktop/). Simply install and run it.
To deploy the BRECcIA Network Mapper with Docker Desktop:
1. Download `deploy-docker.zip` [from the latest release](https://github.com/Southampton-RSG/breccia-mapper/releases/latest).
2. Extract the zip file into an appropriate folder.
3. Copy your logo (192x192 pixels) to `icon-192x192.png` in the `network-mapper` folder.
4. Copy `example.env` to `.env` in this folder.
5. Edit this file as desired. Note that some variables are required.
- Variables are set with the following syntax, in this case setting the `DEBUG` variable to `False`:
```Dotenv
DEBUG=False
```
6. 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`.
6. Start the network mapper with the following command:
```bash
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:
```bash
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.