Forem: Henry Wu

Easier way to run SSR websites (Node.js) on Windows IIS

Henry Wu — Sat, 09 Mar 2024 14:20:50 +0000

Sometimes you have no choice, but to use less-than-ideal tech stack the team familiar with, or perhaps the only tech stack the team knows.

It begins as...

Here, I have a website. While it is a simple website, but does require server-side rendering (SSR) functionality. It may not pose an issue to any modern web developer, but it becomes one when handing off to old-school Windows engineer.

Before it sounds like a complaint, it's worth noting that modern tech stacks and practices are generally cross-platform. There's no reason why I can't run my website under Windows IIS, regardless of how cumbersome it might be to hook up with the JavaScript runtime.

After conducting research and experimenting with FastCGI and URL Rewrite, I discovered another convenient module that seems to be under-discussed.

I'm not an expert in Windows IIS, so I can't speak to the differences under the hood, but from my experience, I find that httpPlatformHandler is easier to setup.

Before I share the walkthrough of IIS setup, we'll need the website running properly under JavaScript runtime (Node.js in this case).

Setup httpPlatformHandler

Download and install httpPlatformHandler from Microsoft.
Open the site under IIS, and navigate to: Handler Mapping > Add Module Mapping...
Enter the follow:

Key Value

Request path *

Module httpPlatformHandler
Uncheck the "Request Restrictions..."
Navigate to: Configuration Editor > system.webService/httpPlatform
Enter the follow:

Key Value

arguments .\.output\server\index.mjs

processPath C:\Program Files\nodejs\node.exe

starupTimeLimit 20
Under the environmentVariables, enter the following:

Key Value

PORT %HTTP_PLATFORM_PORT%

NODE_ENV Production

Key	Value
Request path	*
Module	httpPlatformHandler

Key	Value
arguments	.\.output\server\index.mjs
processPath	C:\Program Files\nodejs\node.exe
starupTimeLimit	20

Key	Value
PORT	%HTTP_PLATFORM_PORT%
NODE_ENV	Production

🎉 Let's it. As of my understanding, all http request will now be handled by Node instead.

The final web.config should looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add 
                name="httpPlatformHandler" 
                path="*" 
                verb="*" 
                modules="httpPlatformHandler" 
                resourceType="Unspecified" 
                requireAccess="Script" 
            />
        </handlers>
        <httpPlatform 
            processPath="C:\Program Files\nodejs\node.exe" 
            arguments=".\.output\server\index.mjs" 
            startupTimeLimit="20" 
            stdoutLogEnabled="true" 
            stdoutLogFile=".\node.log"
        >
            <environmentVariables>
                <environmentVariable 
                    name="PORT" 
                    value="%HTTP_PLATFORM_PORT%" 
                />
                <environmentVariable 
                    name="NODE_ENV" 
                    value="Production" 
                />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>

Complains
The project would progress much more smoothly if the old-school engineers provided insightful assistance, given that it falls within their area of expertise. However, they seem to push away responsibility instead of offering support. My intuition tells me that they may not even have a deep understanding of how IIS works under the hood, as they are accustomed to simply clicking buttons on the screen.

Auto-route multiple web projects using Traefik

Henry Wu — Fri, 08 Mar 2024 17:26:08 +0000

When I first joined a company, they had a method to deploy web projects onto dev and stage servers. However, I spotted critical flaws and inefficiency immediately.

Problem: The scenario was...

To manually build Docker image on personal machine, then upload to public Docker Hub! (Yes, you read it right, cooperate secrets leaked.)
To manually edit DNS records each time when setting up new projects. It's not a problem for "production" deployment, but it is not the case here. Those are short-lived projects for reviews, and there are many legacy records cluttered up.
There are multiple over-specced VMs just to serve static websites, and they had to choose which one to swap with new project each time.
Connections are not HTTPS. Although it is technically not a problem, but annoying.
They have also complained significant times wasted to push and pull from Docker Hub, and to manually SSH to VMs to spin up projects. (Though, I didn't experience it since this practice was killed by me immediately.)

Solution:

I set a wild-card in DNS record to point to a single VM.
That VM serves as Docker host.
I configured Traefix proxy (a container) to handle routing between projects (containers) and to handle HTTPS connections.
I wrote custom GitHub Actions workflow to handle deployment automatically.
Repeat above steps for dev and stage VMs.

The Main Topic:

I'll talk about how I setup Docker host and Traefix container in this article, and I have separate article about my custom workflow.

System Architecture

I don't know how to post the graph in hi-res, but expand this for mermaid code

flowchart
  subgraph Local Dev Env
  LD1 --> LD2 --> LD3
  LD1[Developing]
  LD2[Testing]
  LD3[Commit]
  end

  LD3 --> GH1

  subgraph GitHub
  GH1 --> GA1
  GH1[main branch]
    subgraph GitHub Actions
    GA1 --> GA2 --> GA3 --> GA4 --> GA5 --> GA6 --> GA7 --> GA8
    GA1[Activate gcloud service account]
    GA2[Config docker to use Artifacts Registry]
    GA3[Generate static webpages]
    GA4[Build custom nginx docker image]
    GA5[Push to Artifacts Registry]
    GA6[Stop existing docker container on remote host]
    GA7[Copy docker-compose to remote host]
    GA8[Docker-compose up on remote host]
    end
  end

  IA1 -. credential .-> GA1
  GA5 -.-> AR1

  subgraph Google Cloud IAM
  IA1[Actifacts Registry Service Account]
  IA2[Cloud DNS Service Account]
  end

  CD1 -.-> TR1

  subgraph Google Cloud DNS
  CD1 --> CD2
  CD1[some-domain-name.com]
  CD2[Manually add records for *.some-domain-name.com]
  end

  subgraph "Docker Host (on Google Cloud)"
  GA8 --> VM1
  VM1 --> VM2 --> VM3 --> AP1
  VM1[docker-compose up]
  VM2[pull new image from repository]
  VM3[docker run]

    subgraph Traefik
    IA2 -. credential .-> TR2
    TR1 -.-> TR2 -.-> TR3 -.-> TR4 --> TR5
    TR1[Setup reverse proxy]
    TR2["Signing TLS (Let's Encrypt)"]
    TR3[Listen on docker.sock]
    TR4[Dynamic config routing]
    TR5[Dynamic config middlewares]
    end

    subgraph App1
    AP1 --> TR4
    AP1[Nginx web server]
    end

  end

  AR1 -.-> VM2
  subgraph Google Cloud Actifacts Registry
  AR1[Repository]
  end

As aforementioned, we will have:

An Ubuntu VM to run Docker engine.
Configure Traefik proxy (container) to handle routing between other containers, and to handle HTTPS connections.
Google Artifact Registry to store private Docker images.
Configure GitHub Actions workflow to glue all parts together.
Additionally, we will need a SSH key pair to connect to VM, and IAM credentials to access gcloud services.

Configure Traefik Proxy

Assuming we have Ubuntu VM with Docker and Docker Compose installed, and both Cloud Artifacts Registry and IAM setup properly. (Let me know in the comment if anyone wish for extra walkthrough)

Within the docker-compose.yml for the Traefik container, we will add:

version: "3.8"

services:
  traefik:
    # You may want to specify a version.
    image: "traefik:latest"

    # Name to your own liking.
    container_name: "traefik-proxy"

    command:
      - "--entrypoints.web.address=:80"
      - "--providers.docker"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--api"

    ports:
      - "80:80"

    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

    labels:
      - "traefik.enable=true"
      - "traefik.port=80"
      - "traefik.http.routers.traefik.rule=Host(`traefik.some-domain-name.com`)"
      - "traefik.http.routers.traefik.service=api@internal"
      - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)"
      - "traefik.http.routers.http-catchall.entrypoints=web"

    networks:
      - "proxy"

networks:
  proxy:
    driver: "bridge"
    name: "proxy"

Before you start the container, you should do the following once:

Create a bridge network: sh docker network create proxy

This configuration allows Traefik to setup new url whenever new docker container spins up, over HTTP for now.

For example, your VM is some-domain-name.com and a new container configured with hostname of aaa.some-domain-name.com. Traefik will configure the route of aaa.some-domain-name.com to the container automatically.

Configure Traefik to redirect to HTTPS

We will configure Traefik to renew certificate with Let's Encrypt by using DNS challenge. Merge following lines into docker-compose.yml:

services:
  traefik:
    # For simplicity, let's ignore aforementioned lines.

    command:
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.leresolver.acme.dnschallenge=true"
      - "--certificatesresolvers.leresolver.acme.dnschallenge.provider=gcloud"
      - "--certificatesresolvers.leresolver.acme.email=your-registered@email.com"
      - "--certificatesresolvers.leresolver.acme.storage=/acme.json"

    environment:
      - "GCE_PROJECT=your_GCP_project_id"
      - "GCE_SERVICE_ACCOUNT_FILE=lets-encrypt.json"

    ports:
      - "443:443"

    volumes:
      - "./acme.json:/acme.json"
      - "./lets-encrypt.json:/lets-encrypt.json"

    labels:
      - "traefik.http.routers.traefik.tls.certresolver=leresolver"
      - "traefik.http.routers.traefik.tls.domains[0].main=*.some-domain-name.com"
      - "traefik.http.routers.traefik.tls.domains[0].sans=some-domain-name.com"
      - "traefik.http.routers.traefik.entrypoints=websecure"
      - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)"
      - "traefik.http.routers.http-catchall.entrypoints=web"
      - "traefik.http.routers.http-catchall.middlewares=redirect-to-https"
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"

Please notes that the example shown is using Google Cloud DNS, you may have to set to a different challenger and different environment variables. Follow this doc for gcloud challenger, or follow this index for specific instruction of your DNS providers.

Before you start the container, you should do the following once:

Create empty ACME file for Traefik to store Let's Encrypt info:
```
touch acme.json
chmod 600 acme.json
```
Download the Google Cloud Artifacts Registry service account credentials (json file), and rename it to lets-encrypt.json. (or do the reverse in docker-compose.yml.)

Kindly note that both acme.json and lets-encrypt.json should be within the same folder of docker-compose.yml.

🎉 Walla! You should have working Traefik proxy running and should have valid certificate to serve HTTPS. (Actually it's not that easy, please refer to official docs for troubleshooting; or, leave comments below, if I happened to pickup, no guaranty.

I hope this article is inspiring for you, and maybe, assist you to learn, or setup, your own Traefik proxy. I found it quite a deep learn curve initially, as there aren't much example configs that suites my scenario.

Configure other projects to use this Traefik proxy:

As it is quite lengthly, please follow my second article for custom GitHub Actions workflow and docker-compose.yml.

Feedbacks: from colleague,

"They said" it was a hour of "labour" work to deploy a version of project before, but I made it done under 3 minutes, and automatically.
I cut cloud expenses by half.

My Github Actions workflow for deploying web projects

Henry Wu — Fri, 08 Mar 2024 11:02:15 +0000

This is a follow up article of my setup to use Docker and Traefik proxy to host multiple web projects.

In this article, I'll share my Github Actions workflow to builds and deploy docker images automatically.

The steps are simple:

Configure web project's docker-compose.yml.
Push code to Github and trigger Actions workflow.
Specify runner and Node version.
Run necessary setups.
Build web project within runner.
Build docker image.
Push docker image to private repository.
SSH remote commands to spin down existing docker container on remote server.
SCP docker-compose.yml to remote server.
SSH remote command to spin up the image on remote server.

Assumptions

Say, we have a Nuxt SSG project and we use Bun runtime. We have configured Dockerfile to host built files using Nginx. (Assumptions are chosen for simplicity).

FROM nginx
COPY .output/public /usr/share/nginx/html

We have a server running Docker and Traefik container, and both some-domain-name.com and *.some-domain-name.com are pointing to the server.

We will use a private SSH key to send remote commands and SCP files within workflow script.

Lastly, we have a private container registry to store our docker images. Example here is using Google Cloud Artifact Registry.

All keys are saved as private variables in GitHub.

Setup `docker-compose.yml`

We will use our private container registry, and add Traefik configurations to docker-compose.yml:

version: '3.8'

services:
  your-container-name:
    image: 'XXX-location.pkg.dev/XXX-project/XXX-repo/XXX-image'
    ports:
      - '80'
    labels:
      - 'traefik.enable=true'
      - 'traefik.port=80'
      - 'traefik.http.routers.xxx.rule=Host(`xxx.your-domain-name.com`)'

We will pull image from private registry, so refer to Google's documentation on Artifact Registry for the actual tag.

Both ports and traefik.port should match Nginx container's port. (Default 80 in this case).

Lastly, set the url for Traefik to route traffics to your website (container).

We want to trigger deployment workflow on push:

We will setup our workflow as:

on:
  push:
    branches:
      - main

First, we will perform all necessary setups

env:
  REGISTRY_URL: XXX-location.pkg.dev
  PROJECT_ID: XXX-project
  REPO_NAME: XXX-repo
  IMAGE: XXX-image

jobs:
  name-of-your-liking:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20]
    environment: production

    steps:
      - use: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.XXXX }}
          # you may want to use workload_identity_provider instead,
          # but this project was setup years ago using credentials json.
      - uses: google-github-actions/setup-gcloud@v2
      - run: |-
          gcloud --quiet auth configure-docker $REGISTRY_URL

      # To be continue on next section...

We specify to use Ubuntu runner.
Use Node version 20 (LTS as of current writing).
Set env variable to production.
Perform checkout, setup, auth...

Second, generate the website:

      - uses: oven-sh/setup-bun@v1
      - run: |-
          bun install
          bun run generate

To run generate or build depends on your scripts in package.json.

Third, build Docker image.:

      - run: |-
          docker build \
            --tag "$REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE" \
            .

Then, push to private registry:

      - run: |-
          docker push $REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE

Configure SSH

Here comes the interesting part. We are going to setup ssh config, remotely stop containers, scp new compose file, then spin up the new image.

We will add our key to ssh config like this:

      - run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/some_key
          chmod 600 ~/.ssh/some_key
          cat >>~/.ssh/config <<END
          Host remote_server
            HostName $SSH_HOST
            User $SSH_USER
            IdentityFile ~/.ssh/some_key
            StrictHostKeyChecking no
          END
        env:
          SSH_USER: your_user_name_on_server
          SSH_KEY: ${{ secrets.XXX }}
          SSH_HOST: your-domain-name.com

We will stop and remove old image if exist:

      - run: ssh remote_server sudo docker compose -f $IMAGE/docker-compose.yml down
        continue-on-error: true

      - run: ssh remote_server sudo docker image rm  $REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE
        continue-on-error: true

We then copy docker-compose.yml to the server (assume it doesn't exist, or modified):

      - run: ssh remote_server mkdir $IMAGE
      - run: scp docker-compose.yml remote_server:$IMAGE/docker-compose.yml

Finally, we spin up the newly build image:

      - run: ssh remote_server sudo docker compose -f $IMAGE/docker-compose.yml up -d

Final words

There are some improvements can be made.

I should tag the image instead of all using 'latest', but in doing so, it introduces complexity in the script to pull correct version, and to remove old versions (so it will not occupy server storage).
I'm not sure if the method of setting ssh key in ssh config is a secure option. I assume the runner (system) and workflow scripts are "clean" in this case.
There is minor work to manually delete old Docker images both in private registry and remote server.

Final yaml

Here is the full yaml for your reference:

main.yaml

name: Build and Deploy to GCP

on:
  push:
    branches:
      - main

env:
  REGISTRY_URL: XXX-location.pkg.dev
  PROJECT_ID: XXX-project
  REPO_NAME: XXX-repo
  IMAGE: XXX-image

jobs:
  setup-build-publish-deploy:
    name: Setup, Build, Publish, and Deploy
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20]
    environment: production

    steps:
      - use: actions/checkout@v4

      # Setup gCloud CLI
      - uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.XXXX }}
          # you may want to use workload_identity_provider instead,
          # but this project was setup years ago using credentials json.
      - uses: google-github-actions/setup-gcloud@v2

      # Configure Docker to use the gCloud CLI as credential helper for authentication.
      - run: |-
          gcloud --quiet auth configure-docker $REGISTRY_URL

      # Setup Bun runtime (I mean CLI)
      - uses: oven-sh/setup-bun@v1

      # Generate static files
      - name: Generate
        run: |-
          bun install
          bun run generate

      # Build Docker image
      - name: Build
        run: |-
          docker build \
            --tag "$REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE" \
            .

      # Push it to Google Container Registry
      - name: Publish
        run: |-
          docker push $REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE

      # Setup SSH config for remote Docker host
      - name: Configure SSH
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/some_key
          chmod 600 ~/.ssh/some_key
          cat >>~/.ssh/config <<END
          Host remote_server
            HostName $SSH_HOST
            User $SSH_USER
            IdentityFile ~/.ssh/some_key
            StrictHostKeyChecking no
          END
        env:
          SSH_USER: your_user_name_on_server
          SSH_KEY: ${{ secrets.XXX }}

      # SSH remote execute to stop existing Docker container 
      - name: Stop old container
        continue-on-error: true
        run: ssh remote_server sudo docker compose -f $IMAGE/docker-compose.yml down

      # SSH remote execute to remove old image
      # because we are using same 'latest' tag for all image versions.
      - name: Remove old image
        continue-on-error: true
        run: ssh remote_server sudo docker image rm  $REGISTRY_URL/$PROJECT_ID/$REPO_NAME/$IMAGE

      # SSH remote execute to create new folder
      - name: Mkdir
        run: ssh remote_server mkdir -p $IMAGE

      # SCP docker-compose.yml
      # because it may not exist on server, or outdated.
      - name: SCP
        run: scp docker-compose.yml remote_server:$IMAGE/docker-compose.yml

      # SSH remote execute to start new container
      - name: Run
        run: ssh remote_server sudo docker compose -f $IMAGE/docker-compose.yml up -d

Avoid `sudo n`

Henry Wu — Sun, 25 Feb 2024 17:04:48 +0000

Note: It's acutally written in README.md, but if you are lazy like me who skips it, let me point it out for you.

If you found it troublesome to have to sudo every time to switch Node.js versions, then you are configuring n incorrectly (or, you are not configuring it at all).

I assume you have just got your new Mac and simply copy-and-paste installation commands from docs, so I assume you are using zsh and Homebrew.

Instead of using chown for /usr/local/n (and associated folders; which is safe to do), I choose to set N_PREFIX in .zshrc based on my preference to keep configs in one place (and with comments to remind me).

Make .n folder under $HOME (your home directory) to store n installations:
```
mkdir -p ~/.n/bin
```

Add N_PREFIX to .zshrc:

echo 'export N_PREFIX="$HOME/.n"' >> ~/.zshrc

Add it to $PATH too:

echo 'export PATH="$HOME/.n/bin:$PATH"' >> ~/.zshrc

Load zsh config to current shell:
```
source ~/.zshrc
```
Install n using Homebrew:
```
brew install n
```
Install Node.js (LTS):
```
n lts
```

🎉 Walla! Now you can n ~~without sudo~~. No thank you, no thank you.

By the way, if you have an existing system that you would like to configure, you may run sudo n uninstall to remove /usr/local/n (and associated files). But do it first before setting N_PREFIX.

Cover image by Dim Gunger on Unsplash.

Add Powerline glyphs to IBM Plex fonts

Henry Wu — Fri, 01 Apr 2022 07:25:28 +0000

IBM Plex is an interesting font that I'm looking forward to, and I would like to try it out. However, you may be in similar setup as I am, which relays on Powerline glyphs in order to display vim/statusline/prompt correctly.

This walkthrough was performed on macOS and has patched IBM Plex OpenType fonts, but you should be able to patch your own fonts (any fonts) on any OS, as long as you have Python installed.

Download IBM Plex:
https://github.com/IBM/plex/releases
Install fontforge:
brew install fontforge
Clone the font patch script from sgolovine on GitHub:
git clone https://github.com/sgolovine/nerdfont-patcher
Navigate to the directory:
cd nerdfont-patcher
Add Powerline glyphs to IBM Plex font:
fontforge -script font-patcher --powerline ../OpenType/IBM-Plex-Mono/IBMPlexMono-Regular.otf
(You may need to change the path-to-file, more info please refer to the README of nerdfont-patcher)