Add Dev Container configuration for easier and more reproducible setup.

.devcontainer/dev.Dockerfile

@@ -0,0 +1,8 @@
+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
+# 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

.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+// 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"
+		}
+	},
+	"forwardPorts": [
+		// This is automatically forwarded if using a local container, but not on Codespaces.
+		8000
+	],
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-azuretools.vscode-docker"
+			]
+		}
+	}
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,33 @@
+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
+    ports:
+      - "8080:80"
+      - "3307:3306"
+
+volumes:
+  original-repo:

.devcontainer/web.Dockerfile

@@ -0,0 +1,14 @@
+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
+# This changes the www-data UID to 1000 to match the default user on the host, so that when it
+# chowns everything to www-data, it doesn't make it so that the host user cannot write to the files
+# anymore.
+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

.gitignore

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

README.markdown

@@ -6,6 +6,27 @@ 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 in the `.devcontainer` directory 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". This may take several minutes to run.
+1. Your repository is mounted at `/opt/web2py/applications/OZtree` and the original production docker container application is mounted at `cp /opt/web2py/applications/OZtree_original`. In order to sync your repository with the production database state, 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 ci && grunt dev`. You will need to rerun `grunt dev` any time you make code changes.
+1. Visit http://localhost:8080 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 `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).
+1. (Optional) MySQL is available on port 3307 if you wish to debug using local tools outside the container.
+
+## 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.