Development

As shown in the README once you've picked up the boilerplate you can simpley install dependencies and run the start script, however you may not want to resolve install dependencies right into your host machine, there's an easy way to run the boilerplate dockerized in development mode.

Docker

For this to work you'll need docker and docker-composed installed in the host machine and a really basic understanding of docker-compose, we'll start by setting up our proxy:

Save the following to config/nginx.conf:

server {
  listen 80;
  listen [::]:80;

  server_name app.dev;

  location / {
    proxy_pass http://app:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}
#:set ft=nginx

For this a Dockerfile is not needed as we will mount our source code directory directly on top of the Docker container, however if you don't change dependecies often it can save you sometime when running multiple instances of the same service, feel free to include or skip the build step at your discretion.

Save the following to the root of your project as Dockerfile.development:

FROM node:alpine

WORKDIR /opt/src

COPY package.json .
COPY package-lock.json .

RUN npm install --ignore-engines

#:set ft=dockerfile

You can see that unlike the Dockerfile that ships with the boilerplate, this one makes not attemp to build your app, simply sets the working directory in the container and installs npm packages to speed up subsequent container spins, it also exposes no ports. To install or remove new dependencies witouth rebuilding your image you'll have to go through docker-compose we'll cover that in a moment.

Lastly we need to tell docker-compose how to run our proxy and app container, just save the following to your project's root as docker-compose.yml

version: "3"
services:
  proxy:
    image: "nginx:alpine"
    command: ["nginx-debug", "-g", "daemon off;"]
    ports:
      - 80:80
    environment:
      - NGINX_HOST=app.dev
      - NGINX_PORT=80
    volumes:
      - ./config/nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app

  app:
    build:
      context: .
      dockerfile: Dockerfile.development
    command: "npm start"
    image: "webapp:boiler"
    env_file: .env
    volumes:
      - .:/opt/src

A couple of things to note here:

• Your service name, must match the name of the host we're proxying in config/nginx.conf.
• We're not exposing any ports on the app container, meaning you'll go throught the proxy.
• We're mounting the whole project directory onto the app conainter, meaning that changes to components will be hot reloaded.
• The directory our source code is mountend onto must match the Dockerfile.development's WORKDIR.
• A .env file must exist for this to run, you can rename/copy the one we've provided.

To run simply:

docker-compose build  # builds a new image for the app container
docker-compose up     # starts both the app and proxy contianers
docker-compose down   # stops both containers

Your first compilation may take a few seconds but once you see webpack-dev-server feedback that compilation succeded you should be able to visit your app via http://localhost

Running multiple instances of the app

One of the cool things about docker-compose is that you can sping multiple instances of the same service, provided they don't conflict with each other (like trying to expose the same port on the host machine), docker instances are isolated into their own network/subnet and names are resolved based on the service name.

When spinning multiple instances you don't need to change anything in your configuration, docker will create a dns round robin so connecting to the same service name will reach different containers, to spin multiple instnaces of the app service you only need to do this:

docker-compose up --scale app=3

This will start 3 instances of the same app, be warned that you need to handle other parts of your app when load balancing, like sessions storage as each instance of the app is isolated from the other this mean they don't share the same session, this is out of the scope of docker and on the developer to figure out what best meets their needs.