stevenxie/express-starter repository overview

⁠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.

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.

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⁠.