supply env-default file, and gitignore .env;

add reference to .env file in compose file, to elicit a useful error message when the user has not created the .env file.
Update the README file.

Author: NikTJ777

.gitignore

@@ -1 +1,3 @@
 .vscode/settings.json
+
+nuodb/.env

README.md

@@ -1,29 +1,64 @@
-# nuodb-compose
+# nuodb-compose #
 Docker compose files for starting a nuodb database on the local host.
 
 These docker compose files will create:
 * a new docker network specifically for this database;
-* separate AP (admin), TE, and SM containers for each NuoDB process;
+* separate AP (admin), TE, and SM containers - one for each NuoDB process;
 * a separate CD (collector) container for each engine container - to enable NuoDB Insights;
-* an influxdb and grafana container to host the NuoDB Insights dashboards.
+* influxdb and grafana containers to host the NuoDB Insights dashboards.
 
 Note that the container names will have the `project` name embedded - which is the name of the directory (`nuodb`), or set with the `-p` option to `docker-compose`.
 
-# Instructions
-0. clone the repo;
-1. cd to the `nuodb` directory;
-2. edit the `.env` file
-   - if you want to use the a specific SQL engine, you will need an image that supports that engine;
-   - if you want to access the database from outside the `docker network` then set `EXTERNAL_ADDRESS`
-     -- either in the `.env` file, _or_ by setting `EXTERNAL_ADDRESS` on the `docker-compose up` command-line;
-   - if you want to import initial state from a backup into the new database, set `IMPORT_SOURCE` to a path
-     on the _local_ machine. The SM container will mount this file as a volume and extract (untar) it into the
+# Instructions #
+## Creating the database ##
+0. clone the repo.
+
+1. cd to the `nuodb` directory.
+
+2. copy the `env-default` file to `.env` (this step is _NOT_ optional).
+
+3. edit the `.env` file:
+   - if you want to use a specific SQL engine - for example `scalar` - you will need an image that supports that engine;
+   - if you want to access the database from outside the `docker network` - for example from an app running direcly on the local host - then set `EXTERNAL_ADDRESS`;
+     - either in the `.env` file, _or_ by setting `EXTERNAL_ADDRESS` on the `docker-compose up` command-line;
+   - if you want to import initial state from a database backup into the new database, set `IMPORT_SOURCE` to a path
+     on the _local_ machine. The SM container will mount this file as a volume and extract (`untar`) it into the
      archive dir prior to starting the SM process;
-     (only if the archive dir is empty - so the SM container can be stopped and restarted without being reinitialised.)
-     -- if you have set `IMPORT_SOURCE` _and_ it is a large file that takes multiple minutes to extract, you _may_ need to
-        set `STARTUP_TIMEOUT` to a larger value, to stop the starup from timeing our _before_ the IMPORT has completed.
-3. create and start the nuodb database with `docker-compose up -d`;
-4. stop and delete everything with `docker-compose down`;
-
-To specify env vars on the command-line, specify them _before_ the `docker-compose` command.
-Ex: `IMPORT_SOURCE=./mydb.bak.tgz STARTUP_TIMEOUT=300 docker-compose up -d`
+     - this is only done only when the archive dir is _empty_ - so the SM container can be stopped and restarted without being reinitialised.
+     - if you have set `IMPORT_SOURCE` _and_ it is a large file that takes multiple minutes to extract, you _will_ need to
+        set `STARTUP_TIMEOUT` to a larger value, to stop the startup from timing out before the IMPORT has completed.
+
+4. create and start the nuodb database with `docker-compose up -d`.
+
+## Stopping the database ##
+1. To stop all containers, but retain all stored state including the database contents:
+  - cd to the `nuodb` directory;
+  - execute `docker-compose down`
+
+2. To restart a stopped database - complete with the database contents:
+  - cd to the `nuodb` directory;
+  - execute `docker-compose start`.
+
+## Deleting the database and all its storage ##
+1. To stop all containers, and delete all resources - including the stored state and database contents:
+  - cd to the `nuodb` directory;
+  - execute `docker-compose down`.
+
+## Notes ##
+1. You can specify env vars on the command-line in linux or MacOS, by setting them _before_ the `docker-compose` command.
+- Ex: `$ IMPORT_SOURCE=./mydb.bak.tgz STARTUP_TIMEOUT=300 docker-compose up -d`
+
+## What could possibly go wrong?? ##
+
+1. If you get an error in the form:
+```
+    WARNING: The NUODB_IMAGE variable is not set. Defaulting to a blank string.
+    WARNING: The PEER_ADDRESS variable is not set. Defaulting to a blank string.
+    WARNING: The IMPORT_SOURCE variable is not set. Defaulting to a blank string.
+    ...
+    ERROR: Couldn't find env file: /a/b/c/nuodb/.env
+  ```
+- then you have most likely forgotten to copy the `env-default` file to `.env`;
+- or (less popular) create your own `.env` file from scratch.
+
+2. If an error causes only part of the database to be deployed, you can start the remaining containers - after fixing the error - by simply running `docker-compose up -d` again. The `up` command only starts those containers that are missing.

nuodb/docker-compose.yaml

@@ -2,6 +2,10 @@ version: '3'
 services:
   nuoadmin1:
     image: $NUODB_IMAGE
+
+    # Do NOT remove this env_file value!!
+    env_file: .env
+
     environment:
       NUODB_DOMAIN_ENTRYPOINT: $PEER_ADDRESS
     hostname: $PEER_ADDRESS
@@ -35,6 +39,7 @@ services:
       - "sh"
       - "-c"
       - |
+        echo "ARCHIVE_DIR=$$ARCHIVE_DIR"
         if [ -n "$IMPORT_SOURCE" -a -f "$IMPORT_PATH" -a ! -f $$ARCHIVE_DIR/1.atm ]; then
            echo "Importing from $IMPORT_PATH into $$ARCHIVE_DIR..."
            tar xf $IMPORT_PATH --strip-components ${IMPORT_LEVEL:-1} -C $$ARCHIVE_DIR || exit 98
@@ -138,7 +143,7 @@ services:
     depends_on:
       - influxdb
     environment:
-      - INFLUX_HOST=influxdb
+      INFLUX_HOST: influxdb
     volumes:
       - ./provisioning:/etc/grafana/provisioning
     ports:

nuodb/.env renamed to nuodb/env-default

@@ -23,6 +23,7 @@ ARCHIVE_PATH=
 # set IMPORT_SOURCE to the path of a LOCAL file on the host where docker-compose is being run.
 # It will be mounted from that location into the SM container, from where it will be extracted
 # and used as the initial state of the database.
+# The person supplying the backup TAR file can advise on any non-standard values required for IMPORT_LEVEL.
 IMPORT_SOURCE=
 IMPORT_LEVEL=1
 IMPORT_PATH=/var/opt/nuodb/import.tz