cleaned up documentation

README.md

@@ -1,3 +1,5 @@
+[![Docker Repository on quay.io](https://quay.io/repository/eschen42/galaxy-tardis/status "Docker Repository on quay.io")](https://quay.io/repository/eschen42/galaxy-tardis)
+
 # TARDIS - Temporal Archive Remote Distribution and Installation System
 
 ## Motivation: Administering a Local Galaxy with Minimal Stress
@@ -12,40 +14,71 @@ Basically, you want to be able to travel (back) in time.
 The Galaxy ["Temporal Archive Remote Distribution and Installation System", https://github.com/HegemanLab/galaxy-tardis](https://github.com/HegemanLab/galaxy-tardis) may be right for you.
 - Any resemblance of the Galaxy TARDIS to [the TARDIS from *Doctor Who*](https://en.wikipedia.org/wiki/TARDIS) is purely (albeit intentionally) coincidental.
 
-Notably, the intent is **not** to replace other automation systems (e.g., ansible):
-- Rather, it is focused on restoring an existing Galaxy instance to a known state.
-- However, the TARDIS facilitates migrating an instance to another host.
-
-## Documentation
+The intent of Galaxy TARDIS is:
+- to facilitate restoration of an existing ([`docker-galaxy-stable`](https://github.com/bgruening/docker-galaxy-stable/)-based) Galaxy instance to a known state.
+- to facilitates migrating an instance to another host.
 
-Documentation for using the Galaxy TARDIS may be found at [https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html](https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html).
+Notably, the intent is **not** to replace other automation systems (e.g., ansible); conversely, Galaxy TARDIS facilitate the job of automating backup and restoration of a `docker-galaxy-stable`-based Galaxy instance.
 
 ## Overview
 
-- The purpose of the Galaxy `tardis` Docker image is to back up and restore Galaxy instances that are based on [galaxy-docker-stable](https://github.com/bgruening/docker-galaxy-stable/).
+- The purpose of the Galaxy `tardis` Docker image is to back up and restore Galaxy instances that are based on [docker-galaxy-stable](https://github.com/bgruening/docker-galaxy-stable/).
 - The only storage back-end for backup implemented thus far is S3-compatible storage such as Ceph.
     - Because the implementation is modular, it should not be particularly challenging to support other back-ends.
-- You can build the image from this repository with:
+- You can [pull the image](#how-to-pull-the-docker-image-by-tag) or [build it yourself](#how-to-build-the-docker-image).
+- A practical example of application of the Galaxy TARDIS is given in the `restore example` directory.
+
+### Documentation
+
+Documentation and instructions for using the Galaxy TARDIS may be found at [https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html](https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html).
+This also describes the illustrative example available in the `restore_example` directory.
+
+### How to pull the Docker image by tag:
+
+Identify a tag with a "Passed" security tag from [https://quay.io/repository/eschen42/galaxy-tardis?tab=tags](https://quay.io/repository/eschen42/galaxy-tardis?tab=tags).
+> For example, when this was written, the "v0.0.1-pre" had passed the "security scan" for known vulnerabilities.
+  As time goes on, new vulnerabilites may be discovered and the "security scan" status of a tag may change.
+
+Use the tag that you chose to pull the image.
+```bash
+docker pull quay.io/eschen42/galaxy-tardis:v0.0.1-pre
+```
+
+### How to build the Docker image:
+
+You can build the image with:
 ```bash
+git clone https://github.com/HegemanLab/galaxy-tardis.git
+cd galaxy-tardis
 bash build_notar.sh
 ```
-- A practical example of application of the Galaxy TARDIS is given in the `restore example` directory.
 
-## TL;DR
+### Quick Start
 
-For a quick DEMO with minimal reading, look at the first lines of the comment at the head of the [`restore_example/DEMO` script](https://github.com/HegemanLab/galaxy-tardis/blob/master/restore_example/DEMO), which assumes, at a minimum, significant familiarity with:
+Suppose that you have significant familiarity with the following (links are not provided to avoid the impression that following a few links is a substitute for significant experience):
 - bash
 - docker
 - docker-compose
 - S3
 - s3cmd
 - docker-galaxy-stable
 
-I have not yet linked these because I do not want to give the impression that reading a few links is a substitute for significant experience.
+If so, then try looking at the first lines of the comment at the head of the [`restore_example/DEMO` script](https://github.com/HegemanLab/galaxy-tardis/blob/master/restore_example/DEMO).
+Otherwise, please [see Documentation](#documentation).
 
 ## Usage 
 
-Usage for the `tardis` Docker image:
+Please [see Documentation](#documentation) to understand how the parts of Galaxy TARDIS work.
+
+If you were to:
+- create `tags-for-tardis_envar-to-source.sh` by copying `tags-for-tardis_envar-to-source.sh.example`
+- adjust it for your Galaxy instance (based on `docker-galaxy-stable` or one of its derivitives)
+- and run:
+```bash
+source tardis_envar.sh
+$TARDIS help
+```
+you would see the following help text:
 
 ```
 tardis - Temporal Archive Remote Distribution and Installation System for Galaxy-in-Docker
@@ -71,14 +104,13 @@ where:
                   copied the miniconda installer to your export directory)
   md5sum      - MD5 digest for url_or_path, e.g., from https://repo.continuum.io/miniconda/
 
-Optional environment variables:
-  EXPORT_DIR (default "/export") - path to directory containing "galaxy-central"
-    - Optional, used by most tasks
-  PGDATA (default "/var/lib/postgresql/data") - internal path to database in "galaxy-postgres"
-    - Optional, used by "backup" and "seed_database"
+Optional environment variable:
   PGDATA_SUBDIR (default "main") - name of subdirectory of PGDATA_PARENT where PostgreSQL database lives
+    - Used by "seed database"
 Required environment Variables (set using the "-e" option of the "docker run")
   These are the environment variables and the tasks that require them:
+    EXPORT_DIR (usually "/export") - path to directory containing "galaxy-central"
+      - Used by most tasks
     HOST_EXPORT_DIR - host path to the EXPORT_DIR as bind-mounted in docker
       - Used by "seed database"
     HOST_PGDATA_PARENT - host directory whose PGDATA_SUBDIR subdirectory is
@@ -90,6 +122,12 @@ Required environment Variables (set using the "-e" option of the "docker run")
       - Used by "seed database"
     TAG_POSTGRES - tag for docker image for PostgreSQL, e.g., "9.6.5_for_19.01"
       - Used by "seed database"
+    IMAGE_GALAXY_INIT - docker image for initializing Galaxy, e.g., "quay.io/bgruening/galaxy-init"
+      - Used by "apply_config" and "upgrade_conda"
+    TAG_GALAXY - tag for docker image for PostgreSQL, e.g., "19.01"
+      - Used by "apply_config" and "upgrade_conda"
+    CONTAINER_GALAXY - name of instantiated PostgreSQL container, e.g., "galaxy-init"
+      - Used by "apply_config" and "upgrade_conda"
 Required bind-mounts:
   "/export"       - required by all but "bash" and "help"
   "/var/run/docker.sock"  - required by "seed_database", "backup"
@@ -98,10 +136,6 @@ Required bind-mounts:
 
 ```
 
-### How to build the Docker image:
-
-See [https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html#build-and-fly-the-tardis](https://hegemanlab.github.io/galaxy-tardis/tardis-intro.html#build-and-fly-the-tardis)
-
 ## Supporting Software
 
 ### CVS

restore_example/setup_env

@@ -76,8 +76,6 @@ PGDATA_SUBDIR=${PGDATA_SUBDIR:-main}
 IMAGE_POSTGRES=${IMAGE_POSTGRES:-'quay.io/bgruening/galaxy-postgres'}
 # Specify the tag for the docker image for PostgreSQL executables
 TAG_POSTGRES=${TAG_POSTGRES:-9.6.5_for_19.01}
-# Name of PostgreSQL container
-CONTAINER_POSTGRES=${CONTAINER_POSTGRES:-'galaxy-postgres'}
 
 # Docker image name for Galaxy initialization executables
 # N.B. that initialization of the Galaxy '/export' may change in the future,

restore_example/setup_env.in

@@ -47,7 +47,6 @@ INTERNAL_EXPORT_DIR='${INTERNAL_EXPORT_DIR:?}'
 PGDATA_PARENT=${PGDATA_PARENT:?}
 IMAGE_POSTGRES='${IMAGE_POSTGRES:?}'
 TAG_POSTGRES=${TAG_POSTGRES:?}
-CONTAINER_POSTGRES='${CONTAINER_POSTGRES:?}'
 
 IMAGE_GALAXY_INIT='${IMAGE_GALAXY_INIT:?}'
 CONTAINER_GALAXY_INIT='${CONTAINER_GALAXY_INIT:?}'

support/tardis

@@ -43,14 +43,13 @@ where:
                   copied the miniconda installer to your export directory)
   md5sum      - MD5 digest for url_or_path, e.g., from https://repo.continuum.io/miniconda/
 
-Optional environment variables:
-  EXPORT_DIR (default "/export") - path to directory containing "galaxy-central"
-    - Optional, used by most tasks
-  PGDATA (default "/var/lib/postgresql/data") - internal path to database in "galaxy-postgres"
-    - Optional, used by "backup" and "seed_database"
+Optional environment variable:
   PGDATA_SUBDIR (default "main") - name of subdirectory of PGDATA_PARENT where PostgreSQL database lives
+    - Used by "seed database"
 Required environment Variables (set using the "-e" option of the "docker run")
   These are the environment variables and the tasks that require them:
+    EXPORT_DIR (usually "/export") - path to directory containing "galaxy-central"
+      - Used by most tasks
     HOST_EXPORT_DIR - host path to the EXPORT_DIR as bind-mounted in docker
       - Used by "seed database"
     HOST_PGDATA_PARENT - host directory whose PGDATA_SUBDIR subdirectory is
@@ -62,6 +61,12 @@ Required environment Variables (set using the "-e" option of the "docker run")
       - Used by "seed database"
     TAG_POSTGRES - tag for docker image for PostgreSQL, e.g., "9.6.5_for_19.01"
       - Used by "seed database"
+    IMAGE_GALAXY_INIT - docker image for initializing Galaxy, e.g., "quay.io/bgruening/galaxy-init"
+      - Used by "apply_config" and "upgrade_conda"
+    TAG_GALAXY - tag for docker image for PostgreSQL, e.g., "19.01"
+      - Used by "apply_config" and "upgrade_conda"
+    CONTAINER_GALAXY - name of instantiated PostgreSQL container, e.g., "galaxy-init"
+      - Used by "apply_config" and "upgrade_conda"
 Required bind-mounts:
   "'${EXPORT_DIR}'"       - required by all but "bash" and "help"
   "/var/run/docker.sock"  - required by "seed_database", "backup"

tags-for-tardis_envar-to-source.sh.example

@@ -1,4 +1,3 @@
-# When you source 'tardis_envar.sh', it sources 'tags-for-tardis_envar-to-source.sh
 # which defines these environment variables to be imported and used by tardis_envar.sh
 
 # Test that the directory containing tardis_envar.sh also contains a
@@ -33,7 +32,6 @@ if [ -e s3/dest.config -a -e s3/dest.s3cfg ]; then
   #   docker pull quay.io/bgruening/galaxy-postgres:9.6.5_for_19.01
   IMAGE_POSTGRES=${IMAGE_POSTGRES:-'quay.io/bgruening/galaxy-postgres'}
   TAG_POSTGRES=${TAG_POSTGRES:-9.6.5_for_19.01}
-  CONTAINER_POSTGRES=${CONTAINER_POSTGRES:-'galaxy-postgres'}
 
   # These variables specify the postgres image.
   #   In this case it is the image that you would get with

tardis_envar.sh

@@ -10,15 +10,15 @@ done
 DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
 
 source $DIR/tags-for-tardis_envar-to-source.sh
-# e.g.:
-# EXPORT_DIR='/mnt/ace/piscesv/export'
+# tags-for-tardis_envar-to-source.sh may contain, e.g.:
+# TAG_GALAXY='19.01'
+# EXPORT_DIR=/home/demo/export
 # INTERNAL_EXPORT_DIR='/export'
-# PGDATA_PARENT='/mnt/ace/piscesv/postgres'
+# PGDATA_PARENT=/home/demo/postgres
 # IMAGE_POSTGRES='quay.io/bgruening/galaxy-postgres'
-# CONTAINER_POSTGRES='galaxy-postgres'
-# TAG_POSTGRES='9.6.5_for_19.01'
-# CONTAINER_GALAXY_INIT='quay.io/bgruening/galaxy-init'
+# TAG_POSTGRES=9.6.5_for_19.01
 # IMAGE_GALAXY_INIT='quay.io/bgruening/galaxy-init'
+# CONTAINER_GALAXY_INIT='galaxy-init'
 # TAG_GALAXY='19.01'
 
 if [ ! -d ${EXPORT_DIR:?} ]; then
@@ -50,7 +50,6 @@ else
     -e PGDATA_SUBDIR=${PGDATA_SUBDIR:-main} \
     -e TAG_POSTGRES=${TAG_POSTGRES:?} \
     -e IMAGE_POSTGRES=${IMAGE_POSTGRES:?} \
-    -e CONTAINER_POSTGRES=${CONTAINER_POSTGRES:?} \
     -e TAG_GALAXY=${TAG_GALAXY:?} \
     -e IMAGE_GALAXY_INIT=${IMAGE_GALAXY_INIT:?} \
     -e CONTAINER_GALAXY_INIT=${CONTAINER_GALAXY_INIT:?} \