Merge branch 'master' into 598_match_new_indiv_fix

README.md

@@ -41,7 +41,7 @@ You will want to work in a branch when doing any feature development you want to
 ` git pull upstream main`
 
 ### Set Up Development Environment with Docker
-For easiest development, you will need to set up your development environment to work with Docker. See `devops/development/README.md` for detailed instructions.
+For easiest development, you will need to set up your development environment to work with Docker. See [`devops/README.md`](devops/README.md) for detailed instructions.
 
 ### Deploy frontend
 To setup frontend, we need to deploy the React build to Wildbook, please follow the detailed instructions provided in the `frontend/README.md` file within the project directory.

devops/README.md

@@ -1,57 +1,68 @@
 # Wildbook Installation
 
-We provide two different containerized Wildbooks using Docker. Unless you are setting up a production instance of Wildbook, use the `development` image. Wildbook can also be set up as a local tomcat application.
+We provide two different containerized Wildbooks using Docker. Unless you are setting up a production instance of Wildbook, use the **Development Docker** option.
 
-## Development Docker Image
+## Development Docker
 
-This image and all support materials are found in the `development/` subdirectory. Run docker images necessary to launch _wildbook.war_ file developed via java/maven
+All support materials are found in the `devops/development/` subdirectory. This launches docker containers sufficient for you to deploy a `wildbook.war` file which you have developed
+via your own Java environment. 
 
-This will launch docker containers sufficient for you to deploy a `wildbook.war` file which you have developed
-via your own Java environment. <!-- TODO: link/explain java and maven instructions -->
+### Overview of docker containers deployed
 
-### WBIA / ML
-
-Presently, this deployment does not start a local WBIA (image analysis) docker container. This feature will be added in future development.
+- **db** - postgresql database for storing Wildbook data
+- **wildbook** -- the tomcat (java server) container which runs Wildbook
+- **opensearch** -- runs OpenSearch to support searching in Wildbook
+- **smtp** -- handles outgoing email (for password reset etc.) It is beyond the scope of this current document to address setting up email relays on the open internet.
+Environment variables for this are set in `.env` file - see below.
+- ~~**wbia**~~ - Presently, this _does not_ start a local WBIA (image analysis) docker container. The current roadmap is focused on removing WBIA as a requirement as we modernize our machine learning tech.
 
 ### Setup and running
 
-1. `sudo sysctl -w vm.max_map_count=262144` (this only needs to be run once on your system)
-1. In this folder, create a `.env` file and copy the contents of `_env.template` to it. By default, no changes should be needed, but you can edit this new file.
-1. In your terminal, create your base directory (value of `WILDBOOK_BASE_DIR`) and the required subdirectories. The default is `~/wildbook-dev/`):
+1. Run `sudo sysctl -w vm.max_map_count=262144` (A requirement for OpenSearch, it only needs to be run once on your system.)
+1. In `devops/development/` folder, create a `.env` file with a copy the contents of `_env.template`. By default, no changes should be needed, but you can edit this new file if needed.
+1. In your terminal, create your base directory (value of `WILDBOOK_BASE_DIR` from `.env` file above) and the required subdirectories. The default is `~/wildbook-dev/`). For example:
 	```
 	mkdir -p ~/wildbook-dev/webapps/wildbook
 	mkdir ~/wildbook-dev/logs
 	```
-1. deploy your `.war` file in the `wildbook/` directory, using `jar`:
+1. Deploy your `.war` file (see section below) in the above `wildbook/` directory, using `jar`:
 	```
 	cd ~/wildbook-dev/webapps/wildbook
 	jar -xvf /path/to/wildbook-xxx.war
 	```
-1. return to the `devops/development/` directory in the wildbook repo
-1. run `docker-compose up [-d]`, which will launch latest postgresql and tomcat9 docker images
-1. To verify successful launch, open in browser http://localhost:81/ when tomcat has started
+1. Return to the `devops/development/` directory in the wildbook repo
+1. Run `docker-compose up [-d]`, which launches all of the aforementioned docker images
+1. To verify successful launch, open in browser http://localhost:81/ when tomcat has started. Default login of username/password `tomcat`/`tomcat123` should work.
+
+### Development environment setup for compiling Wildbook
+
+To run Wildbook in the development docker environment, even to try out the software, you need a "war file" which is made by compiling the Wildbook java project.
+This requires some software to be set up on your development machine:
+
+- Java JDK (`openjdk`) and `build-essential` linux package, as well as `maven` <span style="background-color: yellow;">[probably a link to generic setup doc elsewhere?]</span>
+- node and npm for React build <span style="background-color: yellow;">[likewise, link to generic help?]</span>, more details in [frontend/README.md](../frontend/README.md).
 
-### When developing
+#### Compiling
 
-As you compile new war files, they can be deployed into the `wildbook` dir (as in step 3 above) and then tomcat restarted with:
+Once the above requirements are met, the war file can be created by running `mvn clean install`. This creates the war file to be used in `target/wildbook-X.Y.Z.war` (with current version number).
 
-```
-docker-compose restart wildbook
-```
+If you make code changes and compile new war files, they can be deployed into the `wildbook` dir (as in step 3 above) and then tomcat restarted with
+`docker-compose restart wildbook`.
 
-## Deploy Docker Image - DRAFT
+---
+
+## Deploy (e.g. Production) Docker Image - DRAFT
 
 This image and all support materials are found in the `deploy/` subdirectory. Run Wildbook and required docker images for production installations only.
 
 **THIS IS CURRENTLY UNDER DEVELOPMENT - DRAFT ONLY**
 
-This will launch an instance of Wildbook for the sake of testing or using in production.
+This launches an instance of Wildbook for the sake of testing or using in production.
 It can be used to deploy on a VM/host on the internet or locally.
 
 ### Docker images used
 
-The following docker containers should launch if started with `docker-compose [-d] up`. Some of these
-are "optional" as noted below.
+The following docker containers should launch if started with `docker-compose [-d] up`. Some of these are "optional" as noted below.
 
 - latest postegresql
 - tomcat9 / latest wildbook
@@ -69,13 +80,5 @@ Currently, nginx is not configured to support ssl/https certs. There are some no
 - copy `_env.template` to `.env` and edit this new file with your own values
 - `docker-compose up ....`
 
-## Local Tomcat 
-**TODO #503: draft local tomcat instructions**
-
-If you are running tomcat locally (not using docker), in order to access it as `http://localhost:8080/` (rather than with `/wildbook` trailing directory),
-you should modify the `<Host>...</Host>` block of tomcat's `conf/server.xml` to contain the following:
-
-```
-	<Context docBase="wildbook" path="" />
-	<Context docBase="wildbook_data_dir" path="/wildbook_data_dir" />
-```
+## Local tomcat 
+If you want to run Wildbook on non-dockerized tomcat, the system will likely build, but functionality will be restricted (i.e., search will not work) and additional functionality will likely break as we continue modernizing the stack. That being said, good luck!