Deploying a static site built with node

This guide is specifically for deploying sites that are built using node, but in production use only static files (html, css, js, etc.) without a server component.

For example Worldwide Routing.

Make sure you have completed dokku user setup first.

Configure your build step

Dokku will run npm run build to build your application, so check that the build script in your package.json is "vite build".

Commit your package-lock.json

Dokku will use npm ci, this only works if you have a package-lock.json

If you don't have a package-lock file already you can generate one with npm install --package-lock-only.

Make sure this file is committed.

Check that all build products are ignored by git

You should have a .gitignore in the root of your project, this should include the node_modules folder and the dist folder where your assets will be built to

/node_modules
/dist

If you have accidentally committed either of these folder, git rm -r them and commit the change.

Creating your dokku app

Choose a name that is likely to be unique, e.g. you can put your name and cohort at the start gerard-kahu24-worldwide-routing

Note that the name should only be hyphens and lowercase letters, and cannot include any underscores ('_').

Run the apps:create command like this, replacing $APP_NAME with the name you've chosen.

dokku apps:create $APP_NAME

This will create an app on the Dokku serve and automatically add it as a remote in your local git repo.

Check that this remote has been added with git remote -v

Keep in mind your origin remote will typically be the github repo, and pushing to the origin will not update your deployed website, and pushing to the dokku remote will not update your github repo.

Add your Nginx configuration

Nginx is the http server that serves our static assets, we need to configure it to work the way we want

Create a file in the root of your project called nginx.conf

events {
  worker_connections 768;
}

http {
  types_hash_max_size 2048;
  include mime.types;
  charset UTF-8;
  server {
    listen 80;
    server_name  _;
    root /app/www;
    index index.html;
    port_in_redirect off;

    location / {
        try_files $uri $uri/ /index.html;
    }
  }
}

Add a Dockerfile to build and run your app

Dokku can use docker to set up a virtual machine to run your application. To configure this create a file in the root of your repo called Dockerfile with these contents.

FROM node:20-alpine as BUILDER
WORKDIR /app

COPY ["package.json", "package-lock.json*", "./"]
RUN npm ci

COPY . .

ENV NODE_ENV=production
RUN npm run build

FROM nginx:stable-alpine
WORKDIR /app

COPY --from=BUILDER /app/dist /app/www
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80

Deploying your app

NOTE: Dokku only has a main branch. so if you're deploying a local branch other than main, you must specify which branch you're deploying with:

Before you push, make sure that you've committed all the new files and changes you've made.

If you run git status, it should look like this (you might not be on the main branch)

On branch main
nothing to commit, working tree clean

Run this command, replacing $LOCAL_BRANCH with the name of the branch you want to deploy

git push dokku $LOCAL_BRANCH:main