Archive Notice

Since I no longer use Express for my backend services (I've no write my backends almost exclusively in Go), I'm archiving this repository—it will no longer be maintained. Feel free to fork it, though!

express-starter

An opinionated Typescript starter setup for Express + Pino. Deployable with Docker and PM2. Works really well with ng-starter!

Installation:

# If using Yarn:
yarn install

# If using NPM:
npm install

General usage

Starting the server:

# If using Yarn:
yarn dev    # starts a dev server with hot-reloading
            # and detailed debugging.
yarn prod   # starts a production server with minimal
            # debugging and no hot-reloading.  
yarn start  # selects 'yarn dev' or 'yarn prod' based
            # on your NODE_ENV

# If using NPM, replace 'yarn ...' with 'npm run ...'
#   However, 'yarn' is highly recommended for a more
#   deterministic package installation!

Default endpoints:

• / - Endpoint for static/index.html. Static assets are served from static/.

  Note that in production, usage of Express as a static asset server is discouraged, as it is much more efficient to use NGINX to serve static content, and to use Express only as an API server.

• /api - Main API endpoint; returns a text/plain message indicating that the API is working.

• /api/puppies - Sample API endpoint that counts page refreshes. Sends data as application/json.

Usage with Docker

Setup

Method 1: Building an image from scratch.

First, edit package.json's config section:

• Set docker-image-version to a pattern that matches #.#.# (typically using semver)). This affects the tag of the built Docker image (which will look something along the lines of #.#.#-prod or #.#.#-dev), and also sets the image version label.

Now, decide whether you want to build for production or development (this affects the installed dependencies, and whether express-starter runs in development / production mode), and run the associated command:

# dk = docker

## For a production build:
yarn dk-build-prod
## Or, a shorter alias for the above:
yarn dk-build 

## For a development build:
yarn dk-build-dev

Once you build a version, the .env file will be populated with the build configuration (i.e. BUILD_ENV and BUILD_TAG).

Method 2: Pulling a remote registry image.

Pull the latest image from Docker Hub:

docker pull stevenxie/express-starter

Then, start a container from Docker Compose (which is named express-starter, configured to expose port 3000, and mount a volume named express-vol). If no image has been built, it will also build an image before starting a container from it. Make sure you have Docker Compose installed, or look up how to manually configure a build with docker build!

# To see output in the console foreground (dk = docker)
yarn dk-foreground

# To run in the background
yarn dk-up

Normal usage

To instantiate a container, run yarn dk-up. If no image is built, it will also build the initial image.

For more information about Docker images and containers, please see Docker's documentation.

To stop the container, run yarn dk-stop, and to run it again, run yarn dk-start. The container can also be paused with yarn dk-pause.

To remove the container entirely, run yarn dk-down. To also remove images, run yarn dk-purge.

See the package.json for more useful Docker-related scripts! Each Docker script is prefixed with dk-.

If you have multiple environments / tags, you can have the yarn dk-... scripts target a different image by editing the .env file with the correct BUILD_ENV and BUILD_TAG.

Accessing Volumes on Mac OS X

If you're on a Mac, you won't be able to access the express-vol Docker volume directly through the filesystem; you'll have to access it through Docker's VM as follows:

screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty

# At this point, your screen will become blank.
#   Press enter, and wait for the prompt to show up.
#   When it does, you can access the volumes at the
#   following location:
cd /var/lib/docker/volumes

Usage with PM2

To launch on a server with PM2 installed globally, run with yarn pm2 or npm run pm2. This will allow you to monitor the status of the server, and auto-restart it if it crashes.

Using auto-deployment:

If you have your server settings correctly filled out in pm2.ecosystem.conf.js → deployment, and your server has your GitHub SSH keys / credentials, then you can set-up the server instantly as follows:

# Assuming using Yarn:
yarn pm2-setup
yarn pm2-deploy

After that, every time you want to update to the latest Git commit, just run yarn pm2-update. If you've at some point performed a git push --force, then it is necessary to run yarn pm2-update-force instead.

Configuration

package.json: config

• dev-log-level – logging level for when the server is started in development mode (default: debug).
• prod-log-level – logging level for when the server is started in production mode (default: error).
• jmespath-log-filter – the filter to be applied to the console output logs during development. Uses the JMESPath query language. To show all output, set to: *. (default: contains(name, `server`))
• browser-live-reload – whether or not you would like the browser to reload when you save your code. Useful if you're making visual changes. (The server itself will always live-reload to reflect new changes). (default: false)
• docker-image-version — a pattern that matches #.#.# (typically using semver). This affects the tag of the built docker image (which will look something along the lines of #.#.#-prod or #.#.#-dev), and also sets the image version label.

docker-compose.yml

The 'services → express → environment' section can be configured with environment variables like NODE_ENV, LOG_LEVEL, and LOG_FILTER, which will override related settings in the NPM package configuration.

pm2.ecosystem.config.js

Allows you to configure custom properties for PM2 monitoring and remote deployment. See the documentation for details.