Skip to content

Latest commit

 

History

History
412 lines (306 loc) · 11.1 KB

README.md

File metadata and controls

412 lines (306 loc) · 11.1 KB
Raw

Dev Setup and Installation

This is to document setup and tools for js-ui (Dockerian JsUi) project.


Contents


Dev Setup

For a developer with GitHub account, e.g. "jasonzhuyx", working on fork -

export WORKSPACE=$HOME/projects
mkdir -p "$WORKSPACE"; cd "$WORKSPACE"
git clone git@github.com:jasonzhuyx/js-ui.git
cd js-ui
git remote add upstream git@github.com:dockerian/js-ui.git
git fetch --all -v

Additionally, install prerequisite tools for this project:

  • awk, egrep, find, grep, sort, tee, xargs, zip
  • Node.js and npm - see Installing Node.js
  • JSON query tool: jq


Installing Java8

As of this moment the e2e test can only completely work with Java8. Please check the environment for the correct Java version:

which java  # Displays path of java binary
echo $JAVA_HOME  # Displays path of java home base
echo $PATH
java -version

If there is a different version of Java besides Java8, please do a Java installation (which allows different versions to coexist in the same system). Then ensure $JAVA_HOME is pointing to the correct version of Java (Java8) and the "$JAVA_HOME/bin" is in "$PATH" environment (also before any other Java installation).


Installing Node.js

Use download or package manager to setup node.js on, e.g. ubuntu

curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install -y build-essential

or macOS

curl "https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- https://nodejs.org/dist/latest/ | sed -nE 's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" > "$HOME/Downloads/node-latest.pkg" && sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"

# alternatively by Homebrew
brew install node

After the installation, check node and npm versions:

node -v  # node --version
npm -v   # npm --version

And update to the latest or the next version:

npm install -g npm@latest
npm install -g node@latest  # or `brew upgrade node` on Mac OS
npm install -g node@next

For checking npm packages

npm install -g npm-check-updates
ncu


Managing Node.js version

Upgrade Node.js

brew upgrade node  # Mac OS X

sudo npm cache clean -f
sudo npm install -g n
sudo n stable

Alternatively to use Node Version Manager, aka nvm.

FYI: update npm:

npm install -g npm@latest

Audit Fix

npm audit
npm audit fix
npm audit fix --force  # CAUTION: this could cause compatibility issues
npm update


Initializing a JavaScript project

Dockerian JsUi project starts prototyping web UI consoles with the following 3 major JavaScript library/frameworks.

See here for tech stack options.

Angular CLI

This project uses Angular CLI to initialize, develop, scaffold and maintain js-ui as an Angular/ng2 application.

npm install -g @angular/cli

export JSF=ng
ng new js-ui && mv js-ui $JSF  # or keep `js-ui` as a project folder
cd $JSF && npm start  # which runs `ng serve`

Note:

  • For chrome headless test, configure karma.conf.js.

  • The default serve port is 4200. Edit the cli configuration .angular-cli.json and add a serve.port under defaults key:

    "defaults": {
  "serve": {
    "host": "0.0.0.0",
    "port": 8080
  },
}

    Optionally, run the ng serve with --port:

    ng serve --host 0.0.0.0 --port 8080

See documentation.

React

This projects use create-react-app cli to initialize js-ui as a React.js application.

npm install -g create-react-app

export JSF=react
create-react-app js-ui && mv js-ui $JSF  # or keep `js-ui` as a project folder
cd $JSF && npm start

Note:

  • For non-interactive testing, set test in npm scripts to CI=true react-scripts test --env=jsdom.

  • The default serve port is 3000. Edit/Create configuration file .env and change/add a customized PORT setting:

    PORT=8080

See package and guide

Vue CLI

This project uses vue-cli to scaffold js-ui as a Vue.js project.

npm install -g vue-cli
vue --version  # or `vue -V`, and use `npm up -g vue-cli` to upgrade

export JSF=vue
vue create js-ui && mv js-ui $JSF  # or keep `js-ui` as a project folder
cd $JSF && npm start  # which runs `npm run dev` by default

Note:

  • The default serve host is localhost, and port is 8080.

  • Both host and port can be overwritten by environment variables HOST and PORT.

  • For headless e2e testing, add the following under test_settings.default or test_settings.chrome in test/e2e/nightwatch.conf.js

    chromeOptions: {
  args: ['headless', 'disable-gpu']
}

See source and guide.



Build, test, and run the project

This project provides both Makefile and npm scripts for building, testing, and serving the application, with options to switch between JavaScript library/framework, e.g. ng/react/vue.

# build the project
JSF=react make build  # or `(cd react; npm build)`

# run both e2e and unit tests
JSF=vue DONT_RUN_DOCKER=1 make test  # or `(cd vue; npm test)`

# start the server
JSF=ng make start     # or `(cd ng; npm start)`

Note:

  • Not all JavaScript library/frameworks are fully supported and maintained. See the latest commit on github.
  • Check out Makefile for default JSF setting.
  • Headless Chrome is not available in Dockerfile yet.



Dockerization

Docker context

  • Alpine

    • Url: https://alpinelinux.org/
    • Shorty: Its very small.
    • Packagemanger: apk
    • Shells: /bin/sh
    • Size: Few MBs - current tag needs 2.7MB

  • Jessie aka Debian 8

    • Url: https://wiki.debian.org/DebianJessie
    • Shorty: All what you need, but LTS is running out. Click me for details
    • Package manager: apt
    • Shells: /bin/bash and many more
    • Size: Round about 50MB

  • Stretch aka Debian 9

  • Buster aka Debian 10

  • Ubuntu based on debain

Install Docker

See Install Docker Platform or Docker Toolbox

Build Docker container

Makefile has provided a docker script to build docker container.

make docker

or

# current path is the source root where Dockerfile exists
docker build -t dockerian/js-ui .

Start Docker container

Recommend to run inside the docker container, simply by

make cmd  # which starts a bash shell in the container

or

docker run -it --rm --name js-ui \
  -v "$PWD":/src/js-ui dockerian/js-ui

Now all node runtime environment is available (in the container); otherwise, using the hybrid script run.sh to call any Makefile target, default is test :

tools/run.sh  # inside or outside of the container

For starting up the server:

make start

Command aliases

Here are some bash shell command aliases for docker cli

alias dclean='docker kill $(docker ps -aq); docker rm -f -v $(docker ps -aq); docker rmi -f $(docker images -aq)'
alias di="docker images|grep -v none"
alias dia="docker images -a"
alias didangling="docker images -a --filter dangling=true"
alias dlogs="docker logs -ft "
alias dps="docker ps -a"
alias drm="docker rm -f -v"
alias drma='docker rm -f -v $(docker ps -aq)'
alias drme='docker rm -f -v $(docker ps -aq --filter "status=exited")'
alias drmi="docker rmi -f "

and a function to extract config in a docker image

function dex() {
  docker history --no-trunc "$1" | \
  sed -n -e 's,.*/bin/sh -c #(nop) \(MAINTAINER .[^ ]\) 0 B,\1,p' | \
  head -1
  docker inspect --format='{{range $e := .Config.Env}}
  ENV {{$e}}
  {{end}}{{range $e,$v := .Config.ExposedPorts}}
  EXPOSE {{$e}}
  {{end}}{{range $e,$v := .Config.Volumes}}
  VOLUME {{$e}}
  {{end}}{{with .Config.User}}USER {{.}}{{end}}
  {{with .Config.WorkingDir}}WORKDIR {{.}}{{end}}
  {{with .Config.Entrypoint}}ENTRYPOINT {{json .}}{{end}}
  {{with .Config.Cmd}}CMD {{json .}}{{end}}
  {{with .Config.OnBuild}}ONBUILD {{json .}}{{end}}' "$1"
}

Clean up

docker rm -f $(docker ps -a | grep js-ui | awk '{print $1}')
docker rmi -f $(docker images -a | grep js-ui | awk '{print $1}')

or cleaning docker process and image in part of clean-all

make clean-all


dockerian

» Back to Contents | Home «