dev.index.md

 # Sonador Development
 Sonador is an open source platform composed of community developed components, libraries, and integration logic. It is deployed as a set of cloud native components (packaged as Docker containers) and libraries that allow for the exchange of data and integration with other systems.
 
-Development of the project's first-party libraries happens on [a GitLab instance](https://code.oak-tree.tech) provided by [Oak-Tree Technologies](https://www.oak-tree.tech), under the ["Oak-Tree/Medical Imaging" group](https://code.oak-tree.tech/oak-tree/medical-imaging). **Community contributions are welcomed and greatly appreciated.**
+Development of the project's first-party libraries happens on [a GitLab instance](https://code.oak-tree.tech) provided by [Oak-Tree Technologies](https://www.oak-tree.tech), under the [Medical Imaging](https://code.oak-tree.tech/oak-tree/medical-imaging) group. **Community contributions are welcomed and greatly appreciated.** _Refer to [How to Contribute](dev.contributing) for ideas on how to contribute._
 
 
 
@@ -10,9 +10,13 @@ Development of the project's first-party libraries happens on [a GitLab instance
 
 A container based environment is maintained by the Sonador project for development and testing purposes. It includes sample [configuration files](prod.config) and deployment manifests for [Docker Compose](https://docs.docker.com/compose/) and [Kubernetes](https://kubernetes.io/). It also includes a set of folder mounts that can be used by a JupyterLab instance to persist data. _Refer to [`compose/analytics-gpu.yaml`](https://code.oak-tree.tech/oak-tree/medical-imaging/imaging-development-env/-/blob/master/compose/analytics-gpu.yaml?ref_type=heads) for mount points and configuration._
 
+
+
+### Quickstart
 [Getting Started with Sonador](https://www.oak-tree.tech/blog/sonador-quickstart) provides a walk-through which describes how to clone the imaging environment repository, start the development containers, configure the host machine to access the [Sonador Viewer](https://code.oak-tree.tech/oak-tree/medical-imaging/ohif-viewers), initialize a JupyterLab instance, and instructions for accessing the [example Jupyter notebooks for the project](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-examples).
 
 
+#### Environment Application Groups
 The environment provides a core set of data storage and [streaming](https://www.oak-tree.tech/blog/big-data-kafka) systems (MinIO and Kafka/Zookeeper), an instance of the Sonador web application (with associated PostgreSQL database), and an instance of Orthanc (which relies upon MinIO, Kafka/Zookeeper, a second PostgreSQL database, and an NGINX proxy). _Refer to the figure for additional detail._ The systems are split into "application groups" that can be controlled via Docker Compose manifests:
 
 * `core.yaml`. Core data services: MinIO, Zookeeper, and Kafka.
@@ -23,7 +27,7 @@ _Refer to ["Sonador Imaging Platform `README`"](https://code.oak-tree.tech/oak-t
 
 **After a container environment has been started via a `docker-compose ... up` command, components can be controlled as a group using their respective manifests.** This is useful for following application group logs or restarting an application after code changes.
 
-**Example 1:** follow the log tail for the Orthanc application group (`pacs-secure.yaml`).
+**Example 1:** follow the logs for the Orthanc application group (`pacs-secure.yaml`).
 
 ```bash
 # Command should be run from the root of the imaging-env repository
@@ -57,10 +61,27 @@ The development environment manifests reference the images stored in Docker Hub
 * Zookeeper: `oaktreetech/sonador-zk`
 * JupyterLab: `oaktreetech/root.base`
 
+#### `Dockerfile` and `Dockerfile.local`
 Public container images are created as part of [GitLab-CI](https://docs.gitlab.com/ee/ci/) build pipelines triggered from GitLab for both Sonador and Orthanc. The pipelines for development images are triggered on each commit while testing/production images are triggered on commit to the `master` branches of the respective projects.
 
 In addition to the `Dockerfile` scripts that are used by the CI pipelines, both Orthanc and Sonador include `Dockerfile.local` files which can be used locally to create a new image. **New images are needed if either system (`apt`) or Python (`pip`) dependencies change.**
 
+#### `docker build` Arguments
+The Sonador and Orthanc Docker files (both `Dockerfile` and `Dockerfile.local`) allow for container builds to be targeted to a specific branch or commit. _The Sonador project uses build arguments that follow [GitLab Auto-DevOps conventions](https://docs.gitlab.com/ee/ci/variables/)._
+
+Build arguments used by both Sonador and Orthanc (common):
+
+* `CI_COMMIT_SHA`: commit (or tag/branch) that should be used for the container build. **Sonador projects do a live checkout of sources from GitLab as part of the build, and for that reason, the commit/branch must be available on the server of the build will fail.**
+
+Orthanc build arguments:
+
+* `CLI_CI_COMMIT_SHA`: commit (or tag/branch) of the [Sonador command line client (Sonador-CLI)](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-cli) that should be used during the container build for Orthanc. _Sonador-CLI is used for readiness/liveness probes in [production deployments](prod.deployment-guide)._
+
+#### Building Container Images for Development
+Both Sonador and Orthanc build files perform live-checkouts of sources from GitLab. This means that when creating images for development, changes to the source code must be committed 
+
+**Rebuild Sonador Web Application**. The following command can be used to re-build the Sonador web application after updating `requirements.txt` or adding a Ubuntu system dependency. _The `Dockerfile` used by Sonador retrieves source code from the Oak-Tree GitLab as part of the build. For that reason, changes must be staged to a development branch, pushed to the server, and the branch name must be provided via the `CI_COMMIT_SHA` build argument._
+
 
 ### Making Changes to Sonador and Orthanc
 TODO:Describe how to create a local (host) checkout of Sonador dependencies which can be run from the container images via `volume` annotations.