expand README

README.md

@@ -6,20 +6,28 @@ In a Bash shell:
 ``` shell
 source <(curl https://bit.ly/run_embark)
 run_embark demo
+# ^ will create an embark_demo directory in the docker host's $PWD
 cd embark_demo
 run_embark
 ```
 
-With overrides:
+## Usage via `run.sh`
+
+[`run.sh`](https://github.com/embark-framework/embark-docker/blob/master/run.sh)
+is a Bash script that simplifies usage of the embark container: publishing
+ports, bind mounting a host volume, and so on.
+
+Many aspects of the script's behavior can be overridden with environment
+variables, and that approach can be (optionally) combined with `docker build`:
 
 ``` shell
 export EMBARK_DOCKER_EXTRA_RUN_OPTS='--rm'
 export EMBARK_DOCKER_IMAGE=statusim/embark
 export EMBARK_DOCKER_TAG=custom
-export EMBARK_DOCKERFILE='https://github.com/embark-framework/embark-docker.git#some/branch'
+export EMBARK_DOCKERFILE='https://github.com/embark-framework/embark-docker.git#develop'
 export EMBARK_VERSION='embark-framework/embark#features/branch'
 export NODE_TAG=10.7.0
-export RUNNER='https://raw.githubusercontent.com/embark-framework/embark-docker/some/branch/run.sh'
+export RUNNER='https://raw.githubusercontent.com/embark-framework/embark-docker/master/run.sh'
 
 docker build \
        --build-arg EMBARK_VERSION=$EMBARK_VERSION \
@@ -36,7 +44,7 @@ run_embark
 Review the
 [Dockerfile](https://github.com/embark-framework/embark-docker/blob/master/Dockerfile)
 and
-[run.sh](https://github.com/embark-framework/embark-docker/blob/master/run.sh#L66-L70)
+[run.sh](https://github.com/embark-framework/embark-docker/blob/master/run.sh)
 for all possible overrides.
 
 ### Shortcuts
@@ -68,7 +76,72 @@ The same is true for the rest of the `embark` commands. To see the full list:
 run_embark --help
 ```
 
-### Compound commands
+### Utilities
+
+The container comes equipped with
+[nodeenv](https://github.com/ekalinin/nodeenv) and
+[nvm](https://github.com/creationix/nvm). A `default` Node.js environment is
+installed via `nodeenv` during image build and placed in
+`~embark/.local/nodeenv/default`. Both `nodeenv` and `nvm` can be used in
+interactive and non-interactive scripts.
+
+#### `nodeenv`
+
+These are equivalent:
+
+``` shell
+nodeenv --prebuilt --node 10.7.0 ~/.local/nodeenv/my_node
+```
+``` shell
+simple_nodeenv 10.7.0 my_node
+```
+
+Activate and deactivate environments with `nac` and `denac`:
+
+``` shell
+nac my_node
+```
+``` shell
+denac
+```
+
+Note that `simple_nodeenv` automatically activates an environment after
+installation, while `nodeenv` does not.
+
+#### `nvm`
+
+If `nvm` is preferable, it needs to be loaded first:
+
+``` shell
+nvm_load
+nvm install --latest-npm 8.11.3
+```
+
+`nvm deactivate` and `nvm unload` will work as expected. It's also possible to
+move between `nodeenv` and `nvm` environments without first deactivating or
+unloading:
+
+``` shell
+nac default
+nvm_load && nvm use v10.7.0
+# ^ assuming 10.7.0 is already installed
+nac default
+```
+
+#### `install-extras.sh`
+
+Some nice-to-have utilities are not installed by default, but this can be done
+by running
+[`install-extras.sh`](https://github.com/embark-framework/embark-docker/blob/master/env/install-extras.sh)
+as the `root` user in an already running container:
+
+``` shell
+docker exec -it $container_id install-extras.sh
+```
+
+### Commands
+
+#### Simple
 
 A single command with options can be supplied directly:
 
@@ -76,66 +149,160 @@ A single command with options can be supplied directly:
 run_embark bash
 ```
 ``` shell
+run_embark node -i -e 'console.log(process.version)'
+# ^ press return again to get a blank REPL prompt
+```
+``` shell
 run_embark ps -ef
 ```
 
+#### Compound
+
 Compound commands should be passed to `bash -[i]c`:
 
+``` shell
+run_embark bash -c 'ps -ef && ls / ; which embark'
+```
+``` shell
+run_embark bash -c 'nvm_load && nvm install --latest-npm 8.11.3 && node --version && npm --version'
+```
+
+Bash
+[here-documents](https://www.gnu.org/software/bash/manual/html_node/Redirections.html#Here-Documents)
+can be used to compose scripts without employing an abundance of `&&`, `;`, and
+`\`:
+
 ``` shell
 run_embark bash -c 'exec bash << "SCRIPT"
 
 simple_nodeenv 10.7.0 my_node
-node --version
-echo $(which node)
 npm i -g http-server
-exec http-server -p 10000
+exec http-server -p 8000
 
 SCRIPT
 '
 ```
 
+Since `run.sh` mounts the docker host's `$PWD` into the container's `/dapp`, and
+since `/dapp` is the container's default working directory, it's also possible
+to do:
+
+``` shell
+run_embark ./my_script.sh
+# ^ assuming my_script.sh is in the docker host's $PWD
+```
+
+Just make sure the script has a `#!` line and that you did `chmod +x
+my_script.sh` on the docker host before invoking `run_embark`.
+
+##### `$EMBARK_DOCKER_RUN`
+
+For greater flexibility, you can specify a script with
+`$EMBARK_DOCKER_RUN`. Arguments passed to `run_embark` will be forwarded to the
+script, and extra flags can be provided to `docker run` to forward docker host
+environment variables.
+
+Keep in mind that such scripts will be run as the `embark` user owing to the
+container's entrypoint.
+
+``` shell
+#!/bin/bash
+
+# this script is located at /path/to/my_script.sh on the docker host, not necessarily in host's $PWD
+
+# dangling "
+
+c=container!
+echo $HOST_HOSTNAME
+echo $HOSTNAME
+echo $@
+echo $1
+# a comment
+echo $2
+echo $3
+eval echo \\\$\$3
+# another comment
+```
+Invoke with:
+``` shell
+EMBARK_DOCKER_EXTRA_RUN_OPTS="-e HOST_HOSTNAME=$HOSTNAME"
+EMBARK_DOCKER_RUN=/path/to/my_script.sh
+
+a=host!
+
+run_embark $a b c
+```
+
+Node.js variant:
+``` javascript
+#!/usr/bin/env node
+
+// this script is located at /path/to/my_node_script.js on the docker host, not necessarily in host's $PWD
+
+const o = {c: 'container!'};
+
+console.log(process.env.HOST_HOSTNAME);
+console.log(process.env.HOSTNAME);
+console.log(JSON.stringify(process.argv));
+console.log(process.argv[2]);
+console.log(process.argv[3]);
+console.log(process.argv[4]);
+console.log(o[process.argv[4]]);
+```
+Invoke the same way:
+``` shell
+EMBARK_DOCKER_EXTRA_RUN_OPTS="-e HOST_HOSTNAME=$HOSTNAME"
+EMBARK_DOCKER_RUN=/path/to/my_node_script.js
+
+a=host!
+
+run_embark $a b c
+```
+
+#### `docker exec`
+
 When executing compound commands via `docer exec` in a running embark
-container, `su-exec` and `bash -ic` can be used together:
+container, `su-exec` and `bash -[i]c` can be used together:
 
 ``` shell
-docker exec -it <container-id> su-exec embark \
+docker exec -it $container_id su-exec embark \
        bash -ic 'exec bash << "SCRIPT"
 
-nac my_node
+simple_nodeenv 10.7.0 my_node
-exec http-server -p 10001
+npm i -g http-server
+exec http-server -p 8000
 
 SCRIPT
 '
 ```
 
-Alternatively, to go non-interactive, manually source the embark user's
+To go non-interactive, manually source the embark user's `.bash_env`:
-`.bash_env`:
 
 ``` shell
-docker exec -it <container-id> su-exec embark \
+docker exec -it $container_id su-exec embark \
        bash -c 'exec bash << "SCRIPT"
 
 . ~/.bash_env
-nvm_load no-auto-lts
+simple_nodeenv 10.7.0 my_node
-nvm install v10.6.0
-echo $(which node)
 npm i -g http-server
-exec http-server -p 10002
+exec http-server -p 8000
 
 SCRIPT
 '
 ```
 
-## Updating versions
+## Container development
+
+### Updating versions
 
 * Open `Dockerfile`
 * On the `ARG` directives, update necessary versions.
 
-## Building
+### Building
 
 Building requires Docker to be installed on your local machine.
 
-### Scripted
+#### Scripted
 
 If you have Ruby installed in your system, run:
 
@@ -145,12 +312,12 @@ $ ruby script/build
 
 To release, add `--release` as a parameter of the build script.
 
-### Manually
+#### Manually
 
 Building and releasing manually isn't too hard either, but there are a couple
 steps.
 
-#### Tags
+##### Tags
 
 To facilitate the images being found, we tag them with the following rules (as
 an example, the `3.1.5` version will be used.)
@@ -161,7 +328,7 @@ an example, the `3.1.5` version will be used.)
 - Tag with `statusim/embark:3` if `3.1.5` is the highest minor and patch level
   on `3`
 
-#### Generating the image
+##### Generating the image
 
 To generate the image, run:
 
@@ -169,7 +336,7 @@ To generate the image, run:
 docker build . -t statusim/embark:<version> [...tags]
 ```
 
-## Releasing
+### Releasing
 
 Releasing requires that you're authenticated to Docker Hub. To do so, run:
 
@@ -177,7 +344,7 @@ Releasing requires that you're authenticated to Docker Hub. To do so, run:
 $ docker login
 ```
 
-### Scripted
+#### Scripted
 
 If you have Ruby installed in your system, run:
 
@@ -185,7 +352,7 @@ If you have Ruby installed in your system, run:
 $ ruby script/build --release
 ```
 
-### Manual
+#### Manual
 
 Pushing the tags manually implies that the image has been previously built. To
 push your local images, run: