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] Clearer deployment instructions

Browse Source
This commit is contained in:
Matthew Grove
2023-02-10 15:24:27 +00:00
parent 9967c081c9
commit 809894a04c
1 changed files with 145 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
docs/source/deployment.md
View File

@@ -1,74 +1,9 @@
# Deployment
The BRECcIA Network Mapper can be deployed in a variety of ways, most of which utilise Docker. 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 deployment has been tested on RHEL7 and RHEL8.
## Development Deployment
Prerequisites: # Ansible
- [Vagrant](https://www.vagrantup.com/)
- [Ansible](https://www.ansible.com/)
Using Vagrant, we can create a virtual machine and deploy BRECcIA Mapper using the same provisioning scripts as a production deployment.
To deploy a local development version of BRECcIA Mapper inside a virtual machine, first navigate to the `deploy` folder:
```bash
cd deploy
```
And then set your config options for the deployment, by copying `settings.example.ini` to `settings.ini` and changing the options contained within as required.
And then start the virtual machine using:
```bash
vagrant up
```
If you would like a new superuser to be provisioned when deploying the network mapper, change the following line in `playbook.yml`:
```yaml
provision_superuser: false
```
to
```yaml
provision_superuser: true
```
And change the `superuser_*` options below it as desired.
Then provision the virtual machine (deploying the network mapper) using:
```bash
vagrant provision
```
This installs the network mapper and makes it available on the local machine at `http://localhost:8080`.
If you wish to make this accessible from other devices on your local network, replace the following line in `deploy/Vagrantfile`:
```ruby
config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1"
```
with:
```ruby
config.vm.network "forwarded_port", guest: 80, host: 8080
```
To stop the virtual machine run the following, in the `deploy` directory:
```
vagrant halt
```
For further commands see the [Vagrant documentation](https://www.vagrantup.com/docs/cli).
## Production Deployment
### Ansible (Recommended)
Prerequisites: Prerequisites:
@@ -80,36 +15,58 @@ Deployment with Ansible has been tested on RHEL7 and RHEL8, but is compatible wi
To deploy the BRECcIA Network Mapper with Ansible: To deploy the BRECcIA Network Mapper with Ansible:
1. Copy `settings.example.ini` to `settings.ini` <!-- -------------------------------------------------------
2. Edit this file as desired. Note there is no requirement to change any of these variables, but it is recommended. NOTES
3. Copy `inventory.example.yml` to `inventory.yml` pull deploy folder only
4. Edit this file to reflect your Ansible setup: navigate to folder
copy icon to icon-192x192.png in folder
copy example.env to .env and edit
copy inventory.example.yml to inventory.yml and edit
edit playbook if superuser desired
run playbook
set provision_superuser to false if was changed
------------------------------------------------------- -->
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 deploy-ansible
```
2. Copy your logo (192x192 pixels) to `icon-192x192.png` in this 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` - Use your server's hostname instead of `example.com`
- Replace the secret key with some text known only to you 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`.
5. If you would like a new superuser to be provisioned for the network mapper (e.g. during initial install), edit the following line of `playbook.yml`: - Then change the `superuser_*` options below it as desired.
8. Run the Ansible playbook `playbook.yml` with this inventory file using:
```yaml ```bash
provision_superuser: false ansible-playbook playbook.yml -i inventory.yml -K -k -u <SSH username>
``` ```
to
```yaml
provision_superuser: true
```
And change the `superuser_*` options below it as desired.
6. 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. 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. To redeploy updates, the same command can be run again - it's safe to redeploy on top of an existing deployment.
### Docker Compose :::{warning}
If you changed the `provision_superuser` variable in `playbook.yml` to `true`, remember to change it back to `false`.
:::
# Docker Compose
Prerequisites: Prerequisites:
@@ -119,29 +76,111 @@ Prerequisites:
Deployment with Docker has been tested on RHEL7, RHEL8, and Ubuntu 22.04 LTS Deployment with Docker has been tested on RHEL7, RHEL8, and Ubuntu 22.04 LTS
::: :::
<!-- -------------------------------------------------------
NOTES
create folder
pull docker compose file and example.env only
copy icon to icon-192x192.png in folder
copy example.env to .env and edit
touch db file? (is this needed?)
run docker compose up -d
create superuser if desired
------------------------------------------------------- -->
To deploy the BRECcIA Network Mapper with Docker: To deploy the BRECcIA Network Mapper with Docker:
1. Copy `deploy/settings.example.ini` to `breccia_mapper/settings.ini` 1. Download and extract the deployment files from [the latest release](https://github.com/Southampton-RSG/breccia-mapper/releases/latest):
2. Edit this file as desired. Note there is no requirement to change any of these variables, but it is recommended.
```bash
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`:
```bash
cp example.env .env
```
4. Edit this file as desired. Note that some variables are required.
3. Create the database using: 3. Create the database using:
```bash ```bash
touch db.sqlite3 touch db.sqlite3
``` ```
4. Set the `DEBUG` and `SECRET_KEY` values in `docker-compose.yml`.
- The secret key should be a long, random string that only you know. Replace `${DJANGO_SECRET_KEY}` with this key.
- Debug can be `True` or `False`. Replace `${DJANGO_DEBUG}` with this value.
- You can also set these via environment variables on the host machine. The appropriate environment variables are `DJANGO_SECRET_KEY` and `DJANGO_DEBUG`.
5. Start the containers with the following command (you may need to use `sudo`): 5. Start the containers with the following command (you may need to use `sudo`):
```bash ```bash
docker compose up -d docker compose up -d
``` ```
6. Create a superuser by running the following, and enter their details when prompted: 6. If desired (e.g. on initial deployment), create a superuser by running the following, and enter their details when prompted:
```bash ```bash
docker compose exec -it server /bin/bash -c "/app/manage.py createsuperuser" 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/)
<!-- -------------------------------------------------------
NOTES
pull deploy folder only
navigate to folder
copy icon to icon-192x192.png in folder
copy example.env to .env and edit
edit playbook if superuser desired
run vagrant up and/or vagrant provision
set provision_superuser to false if was changed
------------------------------------------------------- -->
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/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`:
```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://www.vagrantup.com/docs/cli).
:::
<!-- # Build From Source -->