This page describes both running and developing virtualtabletop in a Docker container.

The repository now ships its own Docker tooling — you usually don't need the hand-written instructions below:

• An official pre-built image is published to Docker Hub as arnoldsmith86/virtualtabletop and rebuilt for every commit on main. See README-DOCKER.md for run examples, all environment variables (EXTERNALURL, URLPREFIX, …), an nginx reverse-proxy config, and how to host a custom public library.
• The repo's own Dockerfile is what builds that image, if you'd rather docker build from a checkout.
• For development, the repo includes a .devcontainer/ config, so you can open the project in GitHub Codespaces or VS Code Dev Containers and get a ready-to-run environment with no manual setup (see Developing virtualtabletop in a container below).

The self-contained instructions below still work and are kept for reference / customization.

Running virtualtabletop in a Docker container

The quickest way to run the server is the official image — no build step needed:

docker run -p 8272:8272 arnoldsmith86/virtualtabletop

See README-DOCKER.md for the full list of options (external URL, reverse proxy, custom library, environment variables). The rest of this section explains how to build and run your own image from scratch instead of using the published one.

Save this as Dockerfile in an empty directory (I use /path/to/vtt as an example) — note the repository already contains a Dockerfile you can build directly if you have a checkout:

FROM node:18-alpine
RUN apk add curl unzip \
    && curl -LO https://github.com/ArnoldSmith86/virtualtabletop/archive/refs/heads/main.zip \
    && unzip main.zip \
    && rm main.zip \
    && apk del curl unzip \
    && cd virtualtabletop-main \
    && npm install --prod
EXPOSE 8272
VOLUME /virtualtabletop-main/save
WORKDIR /virtualtabletop-main
CMD ["npm", "start"]

Now run docker build to create an image (named virtualtabletop in this example):

sudo docker build -t virtualtabletop /path/to/vtt

Afterwards you can run it in a new container (also named virtualtabletop) like this:

sudo docker run --name virtualtabletop -v vtt:/virtualtabletop-main/save -p 0.0.0.0:80:8272 -e "NODE_ENV=production" virtualtabletop

• --name names the resulting container. This can be anything you want.
• -e sets an environment variable.
• -v creates a persistent volume in /var/lib/docker/volumes/vtt to store save data.
• -p makes the internal port 8272 available from the outside of the machine as port 80.

Developing virtualtabletop in a container

Easiest option: the repository ships a .devcontainer/ configuration (devcontainer.json + setup.sh). Open the repo in GitHub Codespaces (Code → Codespaces → Create codespace) or locally in VS Code with the Dev Containers extension (Reopen in Container), and it automatically installs dependencies, generates a config.json, forwards port 8272 (and the 9229 Node debugger), and starts the server. The manual docker-compose setup below is an alternative if you'd rather not use dev containers.

This is an example setup to isolate node environment just for developing virtualtabletop.

First, prepare directories, repo, and config.json:

#!/usr/bin/env bash

mkdir -p virtualtabletop
cd virtualtabletop
# put git repo in a directory called code
git clone https://github.com/ArnoldSmith86/virtualtabletop.git code
# create config.json, and edit it as needed. This will be mounted later.
cp code/config.template.json config.json

# home directory for docker-compose to mount as node home
# so we can keep global node tools persistent (see docker-compose.yaml)
mkdir -p nodehome/app

Then create virtualtabletop/docker-compose.yaml:

version: "3.7"
services:
  virtualtabletop:
    image: node:19.3.0-alpine3.16
    user: "node"
    working_dir: /home/node/app
    environment:
      #- NODE_ENV=production
      - PORT=8272
    volumes:
      - ${PWD}/nodehome:/home/node
      - ${PWD}/code:/home/node/app
      - ${PWD}/config.json:/home/node/app/config.json
    ports:
      - "8272:8272"
    # development
    command: sh -c "npm i; NOCOMPRESS=1 npx nodemon -e js,mjs,css,html,json --ignore save/ --ignore coverage/ --ignore tests/ --inspect server.mjs"
    # uncomment this if you don't want the app to automatically start
    #command: tail -F /dev/null

Then you can use docker-compose up to bring up the container. You can edit the files directly in virtualtabletop/code from the host system.

Shell access

If you need to run specific commands in the container, access its shell by:

$ docker-compose exec virtualtabletop sh

(use exit to leave)

To enter the root shell:

$ docker-compose exec -u root virtualtabletop sh

No testcafe support yet

Note that this setup does not support testcafe, which requires a graphic setup in the container. While there there various techniques (e.g. mount X sockets, vnc, ssh -X, etc.), it is beyond the scope here. If you have a simple setup that can achieve this, please share with us.

Adding games to the library on a local server

If you want to put your own games files on your local server, you must set the allowPublicLibraryEdits property in the config.json file to true. For more info, see https://github.com/ArnoldSmith86/virtualtabletop/wiki/config.json#allowpubliclibraryedits