Add Dev Container configuration for easier and more reproducible setup.

.devcontainer/devcontainer.json

@@ -0,0 +1,26 @@
+// For format details, see https://aka.ms/devcontainer.json.
+{
+	"name": "OZTree Dev",
+	"dockerComposeFile": "../docker-compose.yml",
+	"service": "dev",
+	"workspaceFolder": "/opt/web2py/applications/OZtree",
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	"features": {
+		"ghcr.io/devcontainers/features/python:1": {
+			"version": "3.10"
+		}
+	},
+	// Need newer pymysql version or MySQL connection will fail.
+	"postCreateCommand": "pip install cryptography pymysql",
+	"forwardPorts": [
+		// This is automatically forwarded if using a local container, but not on Codespaces.
+		8000
+	],
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-azuretools.vscode-docker"
+			]
+		}
+	}
+}

.gitignore

@@ -15,3 +15,4 @@ OZprivate/rawJS/OZTreeModule/dist/*
 OZprivate/rawJS/OZTreeModule/docs/_compiled.markdown
 node_modules
 OZprivate/ServerScripts/Tests/BlatSearch.code_cache
+.env

README.markdown

@@ -4,6 +4,26 @@ If you simply want to run a local copy of OneZoom, but not modify the code yours
 
 # OneZoom setup
 
+## Installing in a Docker Dev Container
+
+If you are using Visual Studio Code or another editor that supports [Dev Containers](https://containers.dev/), the easiest way to set up a full development environment is to use the included Dev Container configuration. This will automatically create two containers: one for development (_dev_), and another (_web_) with the MySQL database and production web server (nginx + uwsgi), derived from the Docker image mentioned above. Your source code will be mounted simultaneously into both containers: dev will let you run build commands and web will serve it as a web server you can access via port forwarding. You can also run your own server from the dev container by [running web2py.py directly](#starting-and-shutting-down-web2py) -- this is particularly useful for debugging.
+
+If you are using Visual Studio Code, perform the following steps (you will need to modify these for another editor):
+
+1. Follow the instructions at either https://hub.docker.com/r/onezoom/oztree or https://hub.docker.com/r/onezoom/oztree-complete to save a docker image with IUCN data.
+1. Follow the [VSCode instructions for installing Dev Container support](https://code.visualstudio.com/docs/devcontainers/containers#_installation).
+1. `git clone https://github.com/OneZoom/OZtree` into the directory of your choice. If using Windows, it is highly recommended to [clone on the WSL2 filesystem](https://code.visualstudio.com/remote/advancedcontainers/improve-performance#_store-your-source-code-in-the-wsl-2-filesystem-on-windows) both for performance reasons and to avoid permissions issues. If you wish to fork the repository and clone your fork, you will need to copy the tags from upstream, otherwise you will see build issues later. You can do this with `git fetch --tags upstream` followed by `git push --tags`.
+1. Open the cloned directory in VSCode.
+1. Create a `.env` file at the root of the project and add `WEB_IMAGE_NAME=onezoom/oztree-with-iucn`, changing the value to whatever image name you choose in step 1.
+1. Open the command palette and choose "Dev Containers: Reopen in Container".
+1. Open an integrated terminal and run the following: `cp /opt/web2py/applications/OZtree_original/private/appconfig.ini /opt/web2py/applications/OZtree/private/ && cp /opt/web2py/applications/OZtree_original/databases/*.table /opt/web2py/applications/OZtree/databases/`
+1. Run `npm install && grunt dev`. You will need to rerun `grunt dev` any time you make code changes.
+1. Visit http://localhost and the website should load! You can also run your own server from the dev container by [running web2py.py directly](#starting-and-shutting-down-web2py).
+1. (Optional) Once tables are created, and everything is working, you can set `is_testing = False` in `models/db.py` and `migrate = 0` in `private/appconfig.ini`. This will mean that web2py will not make any changes to table structures in the DB, and also that changes to appconfig.ini will require a web2py restart.
+1. (Optional) [Create a manager account](#creating-auth-users--groups) in the auth table, e.g. so you can [view docs](#documentation).
+
+## Installing locally
+
 There are two ways in which you can install OneZoom on a personal computer: full installation and partial installation. 
 
 * *Partial installation* does not create a standalone OneZoom site, but simply creates a local web file containing the javascript tree viewer. Instead of your tree viewer getting information from your own computer, it must do so by constantly requesting data from the OneZoom website (via the OneZoom APIs). This restricts your OneZoom viewer in various ways:  you cannot make your own bespoke tree, you cannot change languages in the viewer, and you are dependent upon a permanent, fast internet connection. Also note that this installation method is also relatively untested, and there are unfixed problems with e.g. displaying lists of popular species. However, partial installation may be suitable for developers who simply want to re-program features of the tree viewer, such as colours, branch geometry, etc.

dev.Dockerfile

@@ -0,0 +1,9 @@
+FROM mcr.microsoft.com/devcontainers/javascript-node:18
+WORKDIR /opt
+# Should align with https://github.com/OneZoom/OZtree-docker/blob/main/Dockerfile
+RUN git clone --recursive https://github.com/web2py/web2py.git --depth 1 --branch v2.27.1 --single-branch web2py \
+    && chown -R node:node web2py
+COPY --chown=node:node _COPY_CONTENTS_TO_WEB2PY_DIR/routes.py web2py/
+# Required to avoid build issue when running grunt
+ENV NODE_OPTIONS=--openssl-legacy-provider=0
+ENV PATH=${PATH}:/opt/web2py/applications/OZtree/node_modules/.bin

docker-compose.yml

@@ -0,0 +1,30 @@
+version: '3.8'
+services:
+  dev:
+    build:
+      context: .
+      dockerfile: dev.Dockerfile
+    volumes:
+      - type: bind
+        source: .
+        target: /opt/web2py/applications/OZtree
+        consistency: cached
+      - original-repo:/opt/web2py/applications/OZtree_original:ro
+    # Overrides default command so things don't shut down after the process ends.
+    command: /bin/sh -c "while sleep 1000; do :; done"
+    network_mode: service:web
+  web:
+    build:
+      context: .
+      dockerfile: web.Dockerfile
+      args:
+        IMAGE_NAME: ${WEB_IMAGE_NAME}
+    volumes: 
+      - type: bind
+        source: .
+        target: /opt/web2py/applications/OZtree
+        consistency: cached
+      - original-repo:/opt/web2py/applications/OZtree_original
+
+volumes:
+  original-repo:

web.Dockerfile

@@ -0,0 +1,12 @@
+ARG IMAGE_NAME
+FROM ${IMAGE_NAME}
+# Based on https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user#_change-the-uidgid-of-an-existing-container-user
+# Without this, it will chown everything to www-data on the host and break permissions.
+RUN groupmod --gid 1000 www-data \
+    && usermod --uid 1000 --gid 1000 www-data \
+    && chown -R 1000:1000 /opt/web2py/applications
+# Move the original source code into a shared volume, clearing out anything from past runs.
+RUN if [ -d /opt/web2py/applications/OZtree_original ]; then \
+        rm -rf /opt/web2py/applications/OZtree_original; \
+    fi \
+    && mv /opt/web2py/applications/OZtree /opt/web2py/applications/OZtree_original