zephinzer/alpine-node repository overview

⁠A minimal, tested, extensible and self-updating Node image

An open-sourced, minimal, tested, extensible, customisable and self-updating Node image.

This image is a base image with Alpine Linux, Node and Yarn that has been designed for open-source with options to migrate over to a closed-source internal environment.

See the README.md in the GitHub repository⁠ for more information.

⁠Relevant Links

The Docker Hub page can be found at: https://hub.docker.com/r/zephinzer/alpine-node/⁠

The Travis pipeline can be found at: https://travis-ci.org/zephinzer/docker-image-alpine-node⁠

The example project for internal usage can be found at: https://github.com/zephinzer/docker-image-alpine-node-internal-use-example⁠

The Travis pipeline for internal usage can be found at: https://travis-ci.org/zephinzer/docker-image-alpine-node-internal-use-example⁠

⁠Guiding Principles

Yet another alpine-node repository? Of course not. Here's what's different.

⁠Open Sourced

This image is designed to be open-sourced, for close-sourced usage in internal repositories.

⁠Minimal

This image is designed to be minimal, and this is accomplished through using Linux Alpine and building our own Node with custom parameters. Yarn is also installed because it reduces eventual container size.

Why minimal? Small sizes allow for easy logsitics during deployment and lean images reduce the risk of vulnerabilities.

⁠Tested

This image is tested and proven to work with documented builds. See the ./test directory to see the types of projects this base image can work with. Each sub-directory in ./test includes a .Dockerfile which you can use as a template to pull from the desired tag, and a .extra-apk-dependencies which indicate what additional packages need to be installed for the build. The package.json specifies packages which will be included in the build, so if your desired package is there, it will work when you use this base image!

⁠Extensible

Unlike other images, this image was designed so that you could run apk add [EXTRA_APK_DEPENDENCIES] from your own Dockerfile should things fail to build/run because of missing base dependencies. This image was also designed to be a base image for multiple other application images which we use internally, and will be updated and maintained to extend while maintaining backward compatibitlity.

⁠Customisable

Being designed for open-source for close-sourced usage, this image includes lots of templating which can be configured according to your needs. This is achieved through the ./conf.d folder where you can specify the following variables as filenames with their values being the file's content to use when building this image from it's Dockerfile:

• BASE_IMAGE_SOURCE: (defaults to iron/base)
• BASE_IMAGE_TAG: (defaults to 3.4)
• YARN_VERSION: (defaults to v1.0.2)
• ARGON_VERSION: (defaults to v4.8.4)
• BORON_VERSION: (defaults to v6.11.3)
• CARBON_VERSION: (defaults to v8.5.0)

See the Customising the Build section in Usage below for information on how to customise a build.

⁠Self-Updating

Other images require constant maintenance. We didn't want this repository to depend on us for updates, so we implemented methods to grab the latest versions of Node and Yarn to include in our daily build. See our build scripts in the ./scripts for details. We currently grab the latest:

• Node Argon (4.x)
• Node Boron (6.x)
• Node Carbon (8.x)
• Yarn

⁠Usage

⁠Choosing the Tag

Everytime we publish a new image tag, we include 3 versions:

• NODE_VERSION
• node-NODE_VERSION_yarn-YARN_VERSION
• latest-NODE_CODENAME

The highest available version is also published with latest.

The NODE_VERSION and latest-NODE_CODENAME tags will always contain the latest Yarn as it is overwritten as new Node/Yarn versions come out.

Should you need control over the Node and Yarn version, use the node-NODE_VERSION_yarn-YARN_VERSION tag type as that will ensure the version of both Node and Yarn.

⁠As a Base Image via Dockerfile

FROM zephinzer/alpine-node:__TAG_ID__
# install system dependencies required for build and remove cached stuff
RUN mkdir -p /var/cache/apk && \
    apk update && \
    apk upgrade && \
    apk add --no-cache ${EXTRA_APK_DEPENDENCIES} && \
    yarn install && \
    yarn cache clean && \
    apk del ${EXTRA_APK_DEPENDENCIES} && \
    rm -rf /var/cache/apk/*
COPY . /app
ENTRYPOINT ["./docker-entrypoint.sh"]

The __TAG_ID__ can be found from the Tags section in Docker Hub⁠.

You can find documented EXTRA_APK_DEPENDENCIES within our tests which will indicate what other APK dependencies you will need in order to build your NPM dependencies.

⁠As a Container Image via Docker-Compose

version: "3"
services:
  app:
    image: zephinzer/alpine-node:latest
    working_dir: /app
    entrypoint: "/app/docker-entrypoint.sh"
    volumes:
      - ./:/app
    ...
  ...

⁠From Repository Release

Every successful build/test run by Travis results in a release by tagging the commit with a semver version. You may choose to download the project from the releases page but should you do that, you will need to run the following command to generate the correct Dockerfile before you can build it. Run the following commands:

# ./scripts/use argon
# ./scripts/use boron
# ./scripts/use carbon

These will create Dockerfiles for argon (Node 4.x LTS), boron (Node 6.x LTS) and carbon (Node 8.x) respectively. You can then build it via:

# docker build .

⁠Customising the Build

For example, if you wanted to use centos/centos:7 as your base image to build Node Carbon v8.4.0 and include Yarn v1.0.0,

• Clone this repository or download a release from the Releases Section⁠
  • git clone [email protected]:zephinzer/docker-image-alpine-node.git
• Add the relevant files to ./conf.d to configure the build
  • printf "centos/centos" > ./conf.d/BASE_IMAGE_SOURCE
  • printf "7" > ./conf.d/BASE_IMAGE_TAG
  • printf "v8.4.0" > ./conf.d/CARBON_VERSION
  • printf "v1.0.0" > ./conf.d/YARN_VERSION
• Create the build files:
  • ./scripts/build/setup
• Build the image:
  • docker build -f carbon.Dockerfile -t my_carbon .
• Remove the build files:
  • ./scripts/build/teardown
• Find your image:
  • docker images | grep my_carbon

This may be unnecessarily complicated, but we use this process so that we can open-source our logic, but use internally scanned and tested base images within our own products.

See Internal Use Example project⁠ for an example of maintaining an internal repository.