dev.index.md

@@ -59,7 +59,8 @@ The Imaging Development Environment provides a self-contained deployment of the
 * [Orthanc Sonador Plugin Architecture](dev.orthanc-plugin) looks at the Orthanc Sonador Cloud Plugin, how it builds on the [Orthanc Python Plugin](https://book.orthanc-server.com/plugins/python.html), extends the database schema using SQLAlchemy, and interfaces with the Sonador Web Application for [authentication, authorization, and user management](https://www.oak-tree.tech/blog/sonador-security-auth).
 
 
-### Container Images
+
+## Container Images
 Server deployed components within Sonador are packaged as [Docker container images](https://www.oak-tree.tech/blog/container-driven-development). Container images provide a clean and isolated runtime with a consistent, well-defined environment in a format that is portable and can be shared.
 
 Sonador images are stored in two locations:
@@ -114,7 +115,7 @@ docker build -t oaktreetech/sonador -f Dockerfile.local . --no-cache \
 	--build-arg CI_COMMIT_SHA=example/m3d
 ```
 
-##### Orthanc Sonador (Cloud) Plugin**
+##### Orthanc Sonador (Cloud) Plugin
 The command for building the Orthanc/Sonador container image is similar to that of the Sonador Web Application. _The build command should be run from the root of a [Orthanc Sonador Plugin](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador) clone._
 
 ```bash
@@ -142,14 +143,15 @@ docker build -t oaktreetech/orthanc-sonador -f Dockerfile.local . --no-cache \
 **The Orthanc Plugin and CLI share Python dependencies. For that reason, the version of the [Sonador IO Library](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client) for both should be the same.**
 
 
-### Making Changes to Sonador and Orthanc Source Code
+
+## Making Changes to Sonador and Orthanc Source Code
 It is recommended that Docker containers be used for Sonador web application and Orthanc Sonador Plugin development. The container images provide all dependencies and define and provide a consistent runtime.
 
 Using Docker to develop Sonador and Orthanc involves:
 
 1. Creating a clone of [Orthanc Sonador Plugin](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador) or [Sonador Web Application](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador) source code on the developer's local machine. _It is recommended that the sources be placed in a directory within the root of the imaging environment repository called `src`._
-2. Modifying the Docker Compose manifests so that the local source folder will be mounted to the correct location within the container.
-3. Creating a clone of supporting modules that might be needed within the source folder. _Because there is a great deal of code sharing and re-use among the components of the Sonador platform, it is convenient to have a clone of common dependencies that can be modified without having to rebuild packages between every code change._
+2. (Orthanc) Creating a clone of supporting modules that might be needed within the source folder. _Because there is a great deal of code sharing and re-use among the components of the Sonador platform, it is convenient to have a clone of common dependencies that can be modified without having to rebuild packages between every code change._
+3. Modifying the Docker Compose manifests so that the local source folder will be mounted to the correct location within the container.
 4. Reload source files from the local source folder by restarting the Docker containers (via the Compose manifest for the application group). _Alternatively, it is possible to update/restart services by using [Compose Watch](https://docs.docker.com/compose/file-watch/)._
 
 ##### Step 0: Create `src` folder in Imaging Environment
@@ -183,7 +185,7 @@ _Refer to [Interacting With the Imaging Development Environment](dev.env-managem
 The Sonador Web Application is a Django app written in Python. _Refer to [Sonador Web Application Architecture](dev.architecture-sonador) for architecture and additional detail._
 
 ##### Step 1: Create clone of Orthanc Sonador Plugin
-Check out [Sonador Web Application](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador) sources:
+Clone [Sonador Web Application](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador) sources:
 
 ```bash
 # Run commands from root of the Sonador Imaging environment
@@ -195,9 +197,13 @@ cd src
 git clone https://code.oak-tree.tech/oak-tree/medical-imaging/sonador.git
 ```
 
-Imaging Environment repository layout after clone:
+Imaging Environment repository layout after cloning the Sonador source code:
 
 ```text
+|- compose
+|  |- sonador.yaml: Sonador web application manifest
+|  ...
+|
 |- src
    |- sonador
       |- manage.py: Django management script
@@ -205,13 +211,143 @@ Imaging Environment repository layout after clone:
       |- apps: Sonador application logic
       |- lib: first-party "module" dependencies
       |- config: sample deployment manifests and resource files
+      |- ...
 ```
 
 ##### Step 2: Modify Sonador Compose Manifest
-TODO:Describe modifications needed to Sonador Compose manifest.
+After cloning the Sonador Web application sources to `src/sonador`, the `compose/sonador.yaml` manifest needs to be updated to mount the local source folder to the application folder inside of the container. _The example manifest below shows the required edits._
+
+```yaml
+imaging:
+  image: oaktreetech/sonador:latest
+  ports:
+  - 8070:8070
+  volumes:
+  - ../config/sonador:/srv/www/sonador/config
+  # Add a source folder mount to enable local development
+  - ../src/sonador:/srv/www/sonador/sonador
+```
+
+
+##### Step 3: Restart Application Group
+After adding the source mount, the Sonador application group needs to be restarted so that the web server will read from the local folder. _If the Sonador group is not running, you only need to run `docker-compose ... up` component of the command._
+
+```bash
+# Stop the Sonador application group. "down" is used rather than "restart"
+# because a volume was added to the manifest.
+docker-compose -f compose/sonador.yaml down
+
+# Start the Sonador application group
+docker-compose -f compose/sonador.yaml up -d
+```
+
+After making code changes, they can be reloaded by running `docker-compose ... restart`:
+
+```bash
+docker-compose -f compose/sonador.yaml restart
+```
 
 
 #### Orthanc Sonador Plugin
-The Orthanc Sonador Plugin integrates Orthanc with the Sonador web application and extends the medical imaging database with a number of useful API extensions. _Refer to [Orthanc Sonador Plugin Architecture](dev.orthanc-plugin) for architecture and additional detail._
+The Orthanc Sonador Plugin provides integration with the Sonador web application and extends the medical imaging database with a number of useful API extensions. _Refer to [Orthanc Sonador Plugin Architecture](dev.orthanc-plugin) for architecture and additional detail._
+
+##### Step 1: Create clone of Orthanc Sonador Plugin
+Clone [Orthanc Sonador Plugin](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador) sources:
+
+```bash
+git clone https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador.git
+```
+
+Imaging Environment repository layout after cloning the Orthanc Sonador Repository source code:
+
+```
+|- compose
+|  |- pacs-secure.yaml: Orthanc application manifest
+|  ...
+|
+|- src
+   |- orthanc-sonador: root of the Orthanc Sonador Plugin repository
+      |- sonador-plugin.py: Sonador plugin entry script
+      |- sonador_orthanc: plugin logic
+      |- alembic: database migrations folder
+      |- maintenance: CLI scripts for maintenance operations
+      |- lua: integration scripts required by plugin
+```
 
-TODO:Describe how to create a local (host) checkout of Orthanc dependencies which can be run from the container images via `volume` annotations.
+##### Step 2: Clone dependency modules (optional)
+The Orthanc Sonador Plugin uses a number of other Sonador libraries as dependencies including the [Guru Client](https://code.oak-tree.tech/guru-labs/guru-client), [Sonador IO Client](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client), and [Sonador/Orthanc Common Components](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador-common). When working with the Orthanc sources, it is convenient to have a local checkout of these libraries in the root of the plugin source folder in case changes need to be made. _Because Python will preferentially use a module that appears earlier in `sys.path` and that the runtime folder appears first, the local checkout will have priority over the packages installed in the container._
+
+```bash
+# Code should be run from the root of the Sonador Imaging environment
+
+# Change to the source folder
+cd src
+
+# Clone Guru Client
+git clone https://code.oak-tree.tech/guru-labs/guru-client.git guru
+
+# Clone Sonador IO Client
+git clone https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client.git sonador
+
+# Clone Sonador/Orthanc Common Components
+git clone https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador-common.git \
+	sonador_orthanc_common
+```
+
+Imaging Environment repository layout after cloning dependency modules:
+
+```
+|- compose
+|  |- pacs-secure.yaml: Orthanc application manifest
+|  ...
+|
+|- src
+   |- orthanc-sonador: root of the Orthanc Sonador Plugin repository
+      |- sonador-plugin.py: Sonador plugin entry script
+      |  ...
+      |- client: clone of Guru Client
+      |- sonador: clone of Sonador IO Client
+      |- sonador_orthanc_common: clone of common components
+      | ...
+```
+
+##### Step 3: Modify Orthanc Compose Manifest
+After cloning the Orthanc and dependency modules to `src/orthanc-sonador`, the `compose/pacs-secure.yaml` manifest needs to be updated to mount the local source folder to the application folder inside of the container. _The example manifest below shows the required edits._
+
+```yaml
+orthanc:
+  image: oaktreetech/orthanc-sonador:latest
+  ports:
+  - 4242:4242
+  - 8042:8042
+  volumes:
+  - ../config/orthanc/config.web-auth.json:/etc/orthanc/orthanc.json:ro
+  - ../config/orthanc/config.python.json:/etc/orthanc/orthanc-python.json:ro
+  # Add a source folder mount to enable local development
+  - ../src/orthanc-sonador:/opt/orthanc/orthanc-sonador
+  environment:
+    POSTGRESQL_PLUGIN_ENABLED: "true"
+    PYTHON_PLUGIN_ENABLED: "true"
+    DICOM_WEB_PLUGIN_ENABLED: "true"
+    AUTHORIZATION_PLUGIN_ENABLED: "true"
+    AWS_S3_STORAGE_PLUGIN_ENABLED: "false"
+    OHIF_PLUGIN_ENABLED: "true"
+```
+
+##### Step 4: Restart Application Group
+After adding the source mount, the Orthanc application group needs to be restarted so that the server will read from the local folder. _If the Orthanc group is not running, you only need to run the `docker-compose ... up` component of the command._
+
+```bash
+# Stop the Orthanc application group. "down" is used rather than "restart"
+# because a volume was added to the manifest.
+docker-compose -f compose/pacs-secure.yaml down
+
+# Start the Orthanc application group
+docker-compose -f compose/pacs-secure.yaml up -d
+```
+
+After making code changes, they can be reloaded by running `docker-compose ... restart`:
+
+```bash
+docker-compose -f compose/pacs-secure.yaml restart
+```