embarklabs
/
embark-docker
mirror of https://github.com/embarklabs/embark-docker.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

expand README

This commit is contained in:
Michael Bradley, Jr 2018-08-01 21:34:27 -05:00
parent 377eef2e98
commit 822ce63a46
1 changed files with 195 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

223
README.md
View File

@ -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
exec http-server -p 10001
simple_nodeenv 10.7.0 my_node
npm i -g http-server
exec http-server -p 8000
SCRIPT
'
```
Alternatively, to go non-interactive, manually source the embark user's
`.bash_env`:
To go non-interactive, manually source the embark user's `.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
nvm install v10.6.0
echo $(which node)
simple_nodeenv 10.7.0 my_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: