397 lines
9.3 KiB
Markdown
397 lines
9.3 KiB
Markdown
# Embark for Docker
|
|
|
|
## Quick start
|
|
|
|
In a Bash shell:
|
|
``` shell
|
|
source <(curl -L https://bit.ly/run_embark)
|
|
run_embark demo
|
|
cd embark_demo
|
|
run_embark
|
|
```
|
|
|
|
Note that the `run_embark demo` command will create an `embark_demo` directory in
|
|
the docker host's `$PWD`.
|
|
|
|
Note if you're a macOS user and see `ERROR: this script requires Bash version >= 4.0`, please follow our [Bash upgrade instructions](./macOS-bash4-upgragde.md).
|
|
|
|
## 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.
|
|
|
|
When sourced, `run.sh` makes available a shell function named
|
|
`run_embark`. When executed, `run.sh` forwards its arguments to the
|
|
`run_embark` shell function.
|
|
|
|
Many aspects of `run_embark`'s behavior can be overridden with environment
|
|
variables, and that approach can be (optionally) combined with `docker build`.
|
|
|
|
``` shell
|
|
EMBARK_DOCKER_IMAGE=statusim/embark
|
|
EMBARK_DOCKER_TAG=develop
|
|
EMBARK_DOCKERFILE='https://github.com/embark-framework/embark-docker.git#master'
|
|
EMBARK_VERSION='embark-framework/embark#develop'
|
|
NODE_VERSION=10.7.0
|
|
RUNNER='https://raw.githubusercontent.com/embark-framework/embark-docker/master/run.sh'
|
|
|
|
docker build \
|
|
--build-arg EMBARK_VERSION=$EMBARK_VERSION \
|
|
--build-arg NODE_VERSION=$NODE_VERSION \
|
|
-t $EMBARK_DOCKER_IMAGE:$EMBARK_DOCKER_TAG \
|
|
$EMBARK_DOCKERFILE
|
|
|
|
source <(curl $RUNNER)
|
|
run_embark demo
|
|
cd embark_demo
|
|
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)
|
|
for all possible overrides.
|
|
|
|
It's possible to pass additional options to `docker run` by specifying them
|
|
before `--`.
|
|
|
|
``` shell
|
|
run_embark [docker-run-opts] -- [command]
|
|
```
|
|
|
|
To completely replace the default `docker run` options:
|
|
|
|
``` shell
|
|
EMBARK_DOCKER_RUN_OPTS_REPLACE=true
|
|
run_embark [docker-run-opts] -- [command]
|
|
```
|
|
|
|
By default `run_embark` invokes `docker run` with the
|
|
[`--rm`](https://docs.docker.com/engine/reference/run/#clean-up---rm) option,
|
|
making the embark container ephemeral, i.e. it will not persist on the docker
|
|
host's file system after the container exits. To override this behavior:
|
|
|
|
``` shell
|
|
EMBARK_DOCKER_RUN_RM=false
|
|
run_embark [docker-run-opts] -- [command]
|
|
```
|
|
|
|
Note that if you have `EMBARK_DOCKER_RUN_OPTS_REPLACE=true`, then `--rm` would
|
|
need to be provided in `[docker-run-opts]`, i.e. `EMBARK_DOCKER_RUN_RM` will be
|
|
effectively ignored.
|
|
|
|
### Shortcuts
|
|
|
|
These are equivalent:
|
|
|
|
``` shell
|
|
run_embark
|
|
```
|
|
``` shell
|
|
run_embark run
|
|
```
|
|
``` shell
|
|
run_embark embark run
|
|
```
|
|
|
|
The following are also equivalent:
|
|
|
|
``` shell
|
|
run_embark demo
|
|
```
|
|
``` shell
|
|
run_embark embark demo
|
|
```
|
|
|
|
The same is true for the rest of the `embark` commands. To see the full list:
|
|
|
|
``` shell
|
|
run_embark --help
|
|
```
|
|
|
|
### 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`. The `default` environment is automatically
|
|
activated by the container's entrypoint.
|
|
|
|
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
|
|
```
|
|
|
|
#### `micro`
|
|
|
|
The [`micro`](https://github.com/zyedidia/micro) editor is installed during image
|
|
build, should you need to edit files within a running container.
|
|
|
|
#### `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.
|
|
|
|
``` shell
|
|
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
|
|
`\`. Just be mindful of umatched quotes and quotes-escaping when building
|
|
meta-scripts; in such scenarios, use of
|
|
[`envsubst`](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html)
|
|
is probably called for.
|
|
|
|
``` shell
|
|
run_embark bash -c 'exec bash << "SCRIPT"
|
|
|
|
simple_nodeenv 10.7.0 my_node
|
|
npm i -g http-server
|
|
exec http-server -p 8000
|
|
|
|
SCRIPT
|
|
'
|
|
```
|
|
|
|
Since `run_embark` 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 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_RUN=/path/to/my_script.sh
|
|
a=host!
|
|
run_embark -e HOST_HOSTNAME=$HOSTNAME -- $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_RUN=/path/to/my_node_script.js
|
|
a=host!
|
|
run_embark -e HOST_HOSTNAME=$HOSTNAME -- $a b c
|
|
```
|
|
|
|
#### `docker exec`
|
|
|
|
When executing compound commands via `docer exec` in a running embark
|
|
container, `su-exec` and `bash -[i]c` can be used together.
|
|
|
|
``` shell
|
|
docker exec -it $container_id su-exec embark \
|
|
bash -ic 'exec bash << "SCRIPT"
|
|
|
|
simple_nodeenv 10.7.0 my_node || nac my_node
|
|
npm i -g http-server
|
|
exec http-server -p 8000
|
|
|
|
SCRIPT
|
|
'
|
|
```
|
|
|
|
To go non-interactive, manually source the embark user's `.bash_env`.
|
|
|
|
``` shell
|
|
docker exec -it $container_id su-exec embark \
|
|
bash -c 'exec bash << "SCRIPT"
|
|
|
|
. ~/.bash_env
|
|
simple_nodeenv 10.7.0 my_node || nac my_node
|
|
npm i -g http-server
|
|
exec http-server -p 8000
|
|
|
|
SCRIPT
|
|
'
|
|
```
|
|
|
|
## Container development
|
|
|
|
### Updating versions
|
|
|
|
* Open `Dockerfile`
|
|
* On the `ARG` directives, update necessary versions.
|
|
|
|
### Building
|
|
|
|
Building requires Docker to be installed on your local machine.
|
|
|
|
#### Scripted
|
|
|
|
If you have Ruby installed in your system, run:
|
|
|
|
```
|
|
$ ruby script/build
|
|
```
|
|
|
|
To release, add `--release` as a parameter of the build script.
|
|
|
|
#### Manually
|
|
|
|
Building and releasing manually isn't too hard either, but there are a couple
|
|
steps.
|
|
|
|
##### 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.)
|
|
|
|
- Tag with `statusim/embark:latest` if `3.1.5` is the latest version.
|
|
- Tag with `statusim/embark:3.1.5`
|
|
- Tag with `statusim/embark:3.1` if `3.1.5` is the highest patch level on `3.1`
|
|
- Tag with `statusim/embark:3` if `3.1.5` is the highest minor and patch level
|
|
on `3`
|
|
|
|
##### Generating the image
|
|
|
|
To generate the image, run:
|
|
|
|
```
|
|
docker build . -t statusim/embark:<version> [...tags]
|
|
```
|
|
|
|
### Releasing
|
|
|
|
Releasing requires that you're authenticated to Docker Hub. To do so, run:
|
|
|
|
```
|
|
$ docker login
|
|
```
|
|
|
|
#### Scripted
|
|
|
|
If you have Ruby installed in your system, run:
|
|
|
|
```
|
|
$ ruby script/build --release
|
|
```
|
|
|
|
#### Manual
|
|
|
|
Pushing the tags manually implies that the image has been previously built. To
|
|
push your local images, run:
|
|
|
|
```
|
|
docker push statusim/embark:version
|
|
```
|