Forem: Nathan Cook

Typescript Monorepo Development using Docker Compose Watch, Turborepo and PNPM

Nathan Cook — Thu, 07 May 2026 00:13:51 +0000

This tutorial will show how to use Turborepo and the PNPM package manager with the Docker Compose Watch feature to create a smooth development experience, and how to resolve some of the difficulties that arise when trying to deal with shared packages that require a build or code-generation step in a monorepo setup.

(Tutorial repo)

Introduction

While developing web applications using Docker Compose has many positives, like portability and making it easy to add databases and other services like Redis to your environment, it's important to remember that Docker and containers generally were not originally meant to facilitate the sort of immediate-feedback development workflows which web developers expect.

The method of bind-mounting code into a Node image container and creating an anonymous volume for node_modules was always something of a hack, and brings with it little annoyances that can add up to a frustrating experience, like dependency de-sync between host and container, and packages that require building or code generation creating folders locally on the host with root permissions because of the bind mount.

In 2023, Docker announced the GA release of the Docker Compose Watch feature (Spec, Manual entry). From the announcement,

With containerized application development, there are more steps than Alt+Tab and hitting reload in your browser. Even with caching, rebuilding the image and re-creating the container — especially after waiting on stop and start time — can disrupt focus. We built Docker Compose Watch to smooth away these workflow papercuts. We have learned from many people using our open source Docker Compose project for local development. Now we are natively addressing common workflow friction we observe, like the use case of hot reload for frontend development.

Sounds great! However, using the base functionality Compose Watch offers to wrangle complex monorepo setups can get quite cumbersome and frustrating to implement, especially when you have dependencies between apps and shared packages that require build or codegen steps.

The whole conceit here is to try and make local dev with Docker Compose easier and reduce friction, and as cool as the Compose Watch functionality is it is still a general tool and not capable, on its own, to handle some scenarios elegantly.

That's where Turborepo and PNPM workspaces come in.

Required Packages for Tutorial repo

You should have at least Node version > 20 installed (I recommend just using the LTS version)
The PNPM package manager
It's not required, but I would recommend installing Turborepo globally (pnpm add turbo --global)

Tutorial repo description and goals

Here is the Tutorial Repository. To get this project up and running, first run bash scripts/init.sh in the repo directory. Then, you can start the project with docker compose up --wait or tmuxinator start.

This simple project runs a Next.js app which has the Prisma ORM client as a shared package. Prisma was chosen specifically because the client requires code-generation that must be run locally as well as in the container, and setting it up also demonstrates how to configure the environment so Prisma can talk to the Postgresql database from the host as well as when run in the container.

As far as goals, we want to be able to

Work locally on source code and have those changes synced with the running container
If we make changes to the Prisma schema and rebuild the client, have the client code generation also happen in the container (without needing to rebuild the whole project)
Require rebuilding services ONLY when their dependencies change.

Development Dockerfile

First, let's go over the Development Dockerfile. I say "development" Dockerfile because it makes use of Turborepo features that wouldn't make sense when building an image for production.

You can view the full Dockerfile here.

Let's go over what each layer does:

####### Base #######
FROM node:lts-alpine AS base

ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0

ENV TURBO_TELEMETRY_DISABLED=1
ENV NEXT_TELEMETRY_DISABLED=1

RUN apk add --no-cache bash openssl \
  && corepack enable \
  && corepack prepare pnpm@10.33.0 --activate \
  && pnpm add turbo --global

This is our 'base' Node layer. First, it sets some environment variables that are needed so Corepack and PNPM work. Then, it adds some packages to the container (Prisma complains if OpenSSL is not installed) and installs PNPM. Finally, it adds Turborepo globally.

####### Prune #######
FROM base AS prune
WORKDIR /usr/src/app
ARG APP

COPY . .

RUN turbo prune --scope=$APP --docker

This layer copies in the project files and then runs the turborepo prune command with the --docker flag for a specific package in the monorepo, as determined by the $APP argument. $APP will be defined for the service in docker-compose.yml. This setup is useful, since if additional Apps are ever added to the project we can just reuse this Dockerfile and pass the right $APP value for the service in docker-compose.yml.

The directories/files turborepo creates here will be used in subsequent layers. From the Turborepo docs, the prune command will "Generate a partial monorepo for a target package.", and passing the --docker flag will create

A folder named json with the pruned workspace's package.json files.
A folder named full with the pruned workspace's full source code for the internal packages needed to build the target.
A pruned lockfile containing the subset of the original lockfile needed to build the target.

####### Install and Build #######
FROM base AS builder
WORKDIR /usr/src/app
ARG APP

COPY --from=prune /usr/src/app/out/json/ .

RUN \
  --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm install --frozen-lockfile

COPY --from=prune /usr/src/app/out/full/ .

RUN turbo run build --no-cache --filter=${APP}^...

First, this layer copies the workspace's package.json files to the container before running pnpm install --frozen-lockfile. A cache mount is used for the RUN command here. Since only the package.json files are copied, this means that the RUN command will only re-execute on build if workspace dependencies have changed (vs re-running it if ANY source files have changed). Next, the workspace's source files are copied in and packages are built, if necessary.

The syntax of the filter flag (--filter=${APP}^...) here is significant: What this does is cause only the packages that $APP depends on to be built, but not $APP itself. This is what we want, because we don't need to build the Next.js app for local development purposes (we have the dev server), however we DO need Prisma to do its code generation business, which the Next.js app depends on.

The turbo.json file

Before looking at docker-compose.yml and the Docker Compose Watch setup, let's look at the turbo.json file.

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalEnv": ["PORT", "DATABASE_URL"],
  "tasks": {
    "build": {
      "dependsOn": ["^build", "^db:generate"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**", "generated/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "dependsOn": ["^db:generate"],
      "cache": false
    },
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false
    },
    "db:seed": {
      "cache": false
    },
    "db:reset": {
      "cache": false
    }
  }
}

The important configuration here is dependsOn for the build and dev tasks.

Here's the build task:

"build": {
      "dependsOn": ["^build", "^db:generate"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**", "generated/**"]
    },

Here, the dependsOn config means that when you build a specific workspace app with turbo run build --filter=AN_APP, turbo repo will run the build script(s) for any packages that "AN_APP" depends on (as defined in their package.json file), as well as running db:generate in any packages with that script (Prisma, in our example), before executing the build script for the specified App.

In other words, this means that when turbo run build --no-cache --filter=${APP}^... is run in the Dockerfile, the Prisma client will also be generated.

And now the dev task:

 "dev": {
      "dependsOn": ["^db:generate"],
      "cache": false
    },

This makes it so Prisma generates its client whenever turbo run dev is called for apps that depend on the shared Prisma package. The reason for doing this for the dev command (in addition to build) will make more sense when we get to setting up Docker Compose Watch for the Next.js service.

The docker-compose.yml file

I'm only going to talk about the develop watch config for the "web" Next.js service here. You can view the full docker-compose.yml file here.

services:
  ...other services
  web:
    command: turbo run dev --filter=web
    develop:
      watch:
        - action: sync
          path: ./apps/web
          target: /usr/src/app/apps/web
          initial_sync: true

        - action: sync
          path: ./packages/database/prisma
          target: /usr/src/app/packages/database/prisma
          initial_sync: true

        - action: restart
          path: ./packages/database/generated

        - action: rebuild
          path: ./apps/web/package.json

        - action: rebuild
          path: ./packages/database/package.json

  ...rest

Let's go over each Watch action:

- action: sync
  path: ./apps/web
  target: /usr/src/app/apps/web
  initial_sync: true

This synchronizes the Nextjs app's source files with those in the container when the compose project starts up and whenever they change. Files/directories we DON'T want to sync are listed in a .dockerignore file.

- action: sync
  path: ./packages/database/prisma
  target: /usr/src/app/packages/database/prisma
  initial_sync: true

This synchronizes the prisma schema file to the container on startup and whenever it changes, which is important for the next action...

- action: restart
  path: ./packages/database/generated

This restarts the 'web' container when the prisma client is generated locally (when the generated client's code changes). In other words, if you make changes to the Prisma schema and then generate the client locally, this will cause the "web" service to restart.

Here's the clever part: Recall that in the turbo.json file, the dev task was configured to also run db:generate whenever it's called (per the app's dependencies). Consequently, when the 'web' service restarts and calls its command (turbo run dev --filter=web), this will re-generate the Prisma client in the container based on the updated schema.prisma file, which was synchronized in the container by the previous watch action.

- action: rebuild
  path: ./apps/web/package.json

- action: rebuild
  path: ./packages/database/package.json

These actions simply cause the service to rebuild if the package.json files change. This is unavoidable, but fortunately the multi-layer development Dockerfile has been optimized for local development to try and make this as painless as possible.

An example workflow

To follow this example, you'll need to have cloned the tutorial repo, run bash scripts/init.sh, and have the project running in watch mode with docker compose up --wait. To make the changes to code listed below, you will of course also need the project open in your code editor.

With the project running, if you open http://localhost:3000 in your browser you should see:

Let's update the Prisma schema as well as the seed script to see those changes reflected in the running service.

First, open /packages/database/prisma/schema.prisma and add a nullable Int column named "age" to the User model. After doing that, the schema file should look like so:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

enum Role {
  USER
  ADMIN
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  age Int?
}

Next, open up /packages/database/prisma/seed.ts and add ages for the two Users in the seed data. After making those changes, the file should look like this:

import { PrismaClient, Prisma } from "../generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
import { Pool } from "pg";
import "dotenv/config";

const connectionString = `${process.env.DATABASE_URL}`;

const pool = new Pool({ connectionString });

const adapter = new PrismaPg(pool);

const prisma = new PrismaClient({ adapter });

const userData: Prisma.UserCreateInput[] = [
  {
    name: "Alice",
    email: "alice@prisma.io",
    age: 29,
  },
  {
    name: "Bob",
    email: "bob@prisma.io",
    age: 32,
  },
];

async function main() {
  for (const u of userData) {
    await prisma.user.create({ data: u });
  }
}

main()
  .then(async () => {
    await prisma.$disconnect();
    await pool.end();
  })
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    await pool.end();
    process.exit(1);
  });

Finally, we're going re-generate the client locally, update the Postgresql database to match the prisma schema, and then re-seed the database, all without having to stop docker compose or rebuild the service. I created a script entry for the Prisma package which does all that named db:reset, which just runs the following: prisma generate && prisma db push --force-reset && prisma db seed.

To call this, run turbo run db:reset in the project root.

After running that command, you should see the following when you refresh http://localhost:3000 in the browser:

Using TMUX and tmuxinator for a better docker compose experience

Nathan Cook — Sat, 02 May 2026 04:54:00 +0000

This tutorial provides a practical introduction to TMUX and how you can use tmuxinator to easily set up terminal dashboards with logs and shell sessions for your docker compose projects.

After a (very) brief overview of basic TMUX commands, we'll look at using tmuxinator to more easily configure TMUX with YAML configuration files, and at the end we'll go over how to install and use TMUX plugins.

This tutorial was written for Linux or WSL users (I'm running Ubuntu).

(Example repo)

Article Index

The Pitch
Install Packages
Basic TMUX Commands
Configuring TMUX (~/.tmux.config)
Tmuxinator (.tmuxinator.yml)
TMUX plugins
Resources and Links
Extra: Issues with Docker Compose 'Watch'

The Pitch

Instead of looking at a concantenated dump of service logs when you start a docker compose project, and needing to open separate terminals to run commands like docker compose logs and docker compose exec

Wouldn't it be nicer to see a dashboard with panes for each service's logs, with the ability to configure additional windows with separate panes for service SHELL sessions and whatever else:

Fortunately, it's fairly easy to set up such dashboards with TMUX and tmuxinator.

Install necessary packages

TMUX
- sudo apt update && sudo apt install tmux
tmuxinator
- To install the latest version of tmuxinator:
  - Use Homebrew: brew install tmuxinator
  - Or use RubyGems: gem install tmuxinator
- To install a usually slightly-out-of-date version of tmuxinator (which is probably just fine for this tutorial):
  - sudo apt update && sudo apt install tmuxinator

TMUX command basics

As the end-goal here is to show how to use tmuxinator .yaml configs to create bespoke dashboards for docker compose projects, I'm only going to go over the following:

The TMUX prefix combo + keybinding system
How to show the list of TMUX keybindings within TMUX
How to detach from a TMUX session (leaving the session running)
How to kill a TMUX session

The first thing to know about TMUX is that the standard commands all follow a "prefix" key combination.

The default prefix is Ctrl + b, but when we get to configuring TMUX with the ~/.tmux.config file, we'll be changing this to the more convenient combo 'Ctrl + a'.

If you want to follow along for the rest of this section, run tmux in your terminal to start a session.

How to show the list of TMUX keybindings

Enter the prefix Ctrl + b, and then press ? (shift key is necessary) to see the list of keybindings.

Press ESC to close the list.

How to detach from a TMUX session

Enter the prefix Ctrl + b, and then enter d. This will detach the current TMUX session and return you to the command line.

To see a list of running TMUX sessions (from the command line), enter tmux ls.

To stop the currently running TMUX session, type tmux kill-session

How to open the 'command prompt' in TMUX and kill the current session and exit TMUX

Back in TMUX, enter the prefix Ctrl + b and then : (shift key necessary).

This opens a command prompt at the bottom of the screen, where you can run TMUX cli commands (like 'kill-session', for example).

Pressing 'ESC" will close the command prompt.

Configuring TMUX with the ~/.tmux.config file

Assuming you don't already have a tmux config file, create a file named .tmux.config in your home directory and paste the following into it:

# Turn on mouse input
set -g mouse on

# Increase the scrollback limit from 2000 to 10000
set -g history-limit 10000

# Change TMUX prefix key combo from 'Ctrl + b' to 'Ctrl + a'
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Add keybinding to change the currently focused pane with Alt + direction key
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Add keybinding to select windows with 'Alt + Shift + Right' (next window) or 'Alt + Shift + Left' (previous window).
bind -n S-M-Right select-window -n
bind -n S-M-Left select-window -p

# Add Keybinding to kill the current tmux session and exit tmux with 'Ctrl + Shift + x'
bind -n C-S-x kill-session

# Add keybinding to clear focused pane (that is, the whole scrollback history) with 'Ctrl + Shift + k'
bind -n C-S-k send-keys -R \; clear-history

# Minor futzing around with the layout
set -g status-position bottom
set -g status-justify left

# Set what appears in the lower left
set -g status-left ''
set -g status-left-length 15

# Set what appears in the lower right
set -g status-right '%Y-%m-%d %H:%M '
set -g status-right-length 50

# Give windows reasonable titles
setw -g window-status-current-format ' #I #W #F '

# Give panes reasonable titles
set -g pane-border-status top
set -g pane-border-format '#[bold]#{pane_title}#[default]'

Summary

Mouse mode* is turned on
Scrollback (history) limit is increased
The TMUX prefix is changed from Ctrl + b to Ctrl + a

(you do not need to enter prefix before the following shortcuts):

Alt + Direction Key -- changes panes
Alt + Shift + Left/Right Key -- changes windows
Ctrl + Shift + x -- kills the current session, exiting TMUX
Ctrl + Shift + k -- Clears the currently active pane (as well as scrollback history)

* Mouse mode gives you

Mouse-wheel vertical scrolling
Select Panes by clicking on them
Resize Panes by click-dragging their borders
Select Windows by clicking their name in the bottom left of the status bar
A right-click menu with some common pane actions.
You can also copy text to the clipboard by click-dragging to select, but it's a little janky. (I would recommend looking up "Copy Mode")

Configuring TMUX in .yaml with tmuxinator

For the remainder of this article I will be referring to this example repo: docker-tmux-tutorial

If you clone the repo and CD into the directory like so

$ git clone https://github.com/moofoo/docker-tmux-tutorial.git && cd docker-tmux-tutorial

You should see the following files/directories:

|- apps
|  |- web
|  |- api
|- db
|  |- 01_schema.sql
|  |- 02_data.sql
|- .tmuxinator.watch.yml
|- .tmuxinator.yml
|- docker-compose.watch.yml
|- docker-compose.yml
|- Dockerfile
|- README.md
|- tmux.config.example
|- tmux.sh

If you then run (in the repo directory)

$ tmuxinator start

the docker compose project will build (if it needs to) and TMUX will open showing windows and panes per the ./tmuxinator.yml config file, like so (your colors/fonts/font size will differ):

Let's look at ./tmuxinator.yml now:

# ./.tmuxinator.yml

name: tmuxinator_tut
root: ./

on_project_start: docker compose up --wait -d

on_project_exit: docker compose stop

windows:
  - logs:
      panes:
        - web: clear && docker compose logs --since=1s -f web

        - api: clear && docker compose logs --since=1s -f api

        - db: clear && docker compose logs --since=15s -f db

        - redis: clear && docker compose logs --since=15s -f redis

  - shell:
      panes:
        - web: clear && docker compose exec -w /usr/src/app web sh

        - api: clear && docker compose exec -w /usr/src/app api sh

        - psql: clear && docker compose exec db psql -U postgres -d tutorial_db

        - nestjs_repl: clear && docker compose exec -w /usr/src/app api npm run repl

  - home:
      layout: main-vertical
      panes:
        - home: clear

Going over each section of this config file from the top:

name: tmuxinator_tut
root: ./

The fields above set the tmux session name and tells tmuxinator to run commands in the current directory.

on_project_start: docker compose up --wait -d

on_project_exit: docker compose stop

The "on_project_start" config tells tmuxinator to run docker compose up in detached mode when it starts.

The "on project_exit" config tells it to run docker compose stop when the session ends. (In other words, if you enter the "Ctrl + Shift + x" shortcut combo we previously configured in ~/.tmux.config, it will end the TMUX session and stop the docker compose project).

windows:
...rest

The windows: option starts the block where you define the windows and panes you want in the TMUX session.

Here's the first window from the example:

- logs:
    panes:
      - web: clear && docker compose logs --since=1s -f web

      - api: clear && docker compose logs --since=1s -f api

      - db: clear && docker compose logs --since=15s -f db

      - redis: clear && docker compose logs --since=15s -f redis

This window definition creates a window named "logs", which has four panes showing the result of running docker compose logs for the web, api, db, and redis services.

- shell:
    panes:
      - web: clear && docker compose exec -w /usr/src/app web sh

      - api: clear && docker compose exec -w /usr/src/app api sh

      - psql: clear && docker compose exec db psql -U postgres -d tutorial_db

      - nestjs_repl: clear && docker compose exec -w /usr/src/app api npm run repl

This window definition creates a window named "shell", with the following panes making use of docker compose exec:

"web": Opens a shell to the working_dir of the "web" service.
"api": Opens a shell to the working_dir of the "api" service.
"psql": Starts a PSQL terminal session in the "db" service.
"nestjs_repl": Starts the NestJS REPL for the NestJS server running in the "api" service.

- home:
    layout: main-vertical
    panes:
      - home: clear

Just for convenience, this window definition opens your command line on the current (actual) directory.

If you want to see how this dashboard would be created with TMUX commands, check out the tmux.sh script

Extending TMUX with the Tmux Plugin Manager

The TMUX Plugin Manager provides a (relatively) painless way to extend TMUX functionality.

The following instructions will walk you through setting up TPM and installing/configuring the tmux-prefix-highlight plugin, which simply lets you display an indicator after you press the TMUX prefix combo.

1. Install the Tmux Plugin Manager

Run git clone as below to create the necessary files in your $HOME directory:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

2. Edit your ~/.tmux.config file to use the plugin

At the top of the ~/.tmux.config before anything else, add the line:

set -g @plugin 'tmux-plugins/tmux-prefix-highlight'

(follow the above pattern for all plugins)

Then, at the very bottom of ~/.tmux.config (after everything else), add the line:

run '~/.tmux/plugins/tpm/tpm'

2. Configure/use the plugin

This plugin gives TMUX a new template string, #{prefix_highlight}. Assuming you've been following this tutorial, change the following line in ~/.tmux.config (35 for me) from

set -g status-left ''

set -g status-left '#{prefix_highlight}'

You can also add the following lines anywhere before the first and last lines in the file to also show an indicator when you're in "Copy mode":

# Tmux prefix highlight settings
set -g @prefix_highlight_show_copy_mode 'on'

After making all the changes listed above, your ~/.tmux.config file should look something like this:

# Install Plugins
set -g @plugin 'tmux-plugins/tmux-prefix-highlight'

# Tmux prefix highlight settings
set -g @prefix_highlight_show_copy_mode 'on'

# Turn on mouse input
set -g mouse on

# Change TMUX prefix key combo from Ctrl-b to Ctrl-a
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Add keybinding to change the focused pane with Alt + direction key
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Add keybinding to select windows with Alt+Shift+Right (next window) or Alt+Shift+Left (previous window).
bind -n S-M-Right select-window -n
bind -n S-M-Left select-window -p

# Add Keybinding to kill the current tmux session and exit tmux with Ctrl+Shift+x
bind -n C-S-x kill-session

# Add keybinding to clear the focused pane with Ctrl+Shift+k
bind -n C-S-k send-keys -R \; clear-history

# Minor futzing around with the layout
set -g status-position bottom
set -g status-justify left

# Set what appears in the lower left
set -g status-left '#{prefix_highlight}'
set -g status-left-length 15

# Set what appears in the lower right
set -g status-right '#[bold]%Y-%m-%d %H:%M#[default] '
set -g status-right-length 50

# Give windows reasonable titles
setw -g window-status-current-format ' #[bold]#I #W #F#[default] '

# Give panes reasonable titles
set -g pane-border-status top
set -g pane-border-format '#[bold]#{pane_title}#[default]'

# Run TMUX with the installed plugins
run '~/.tmux/plugins/tpm/tpm'

Resources and Links

Extra: Considerations when using docker compose develop 'watch' functionality

If you're making use of "Compose Watch" functionality in your docker-compose.yml file, you'll need to change your .tmuxinator.yml configuration. This is because docker compose up cannot run detached while in 'watch' mode.

See docker-compose.watch.yml and .tmuxinator.watch.yml in the example repo.

You can try out the 'watch' docker compose/tmuxinator config by running

docker compose -f docker-compose.watch.yml build

and then

tmuxinator start -p .tmuxinator.watch.yml

The following YAML shows how the example repo's .tmuxinator.yml file would be updated to work with Compose Watch:

# ./.tmuxinator.watch.yml

name: tmuxinator_watch_tut
root: ./

# Don't run docker compose up on_project_start
# on_project_start: docker compose up --wait -d

on_project_exit: docker compose stop

windows:
  - logs:
      panes:
        # Need to sleep before running docker compose commands, so they run after `docker compose up --watch`
        - web:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml logs --since=1s -f watch_web
        - api:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml logs --since=1s -f watch_api
        - db:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml logs --since=15s -f watch_db
        - redis:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml logs --since=15s -f watch_redis
  - shell:
      panes:
        - web:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml exec -w /usr/src/app watch_web sh
        - api:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml exec -w /usr/src/app watch_api sh
        - psql:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml exec watch_db psql -U postgres -d tutorial_db
        - nestjs_repl:
            - sleep 1
            - clear && docker compose -f docker-compose.watch.yml exec -w /usr/src/app watch_api npm run repl

  - home:
      layout: main-vertical
      panes:
        - home: clear

    # Run docker compose up --watch in its own window
  - watch:
      layout: main-vertical
      panes:
        - watch: docker compose up --watch

To Summarize:

Instead of running docker compose up in detached mode on_project_start, it's run in watch mode in its own window.
Because of the above change, docker compose logs/exec commands need to be delayed so that they run after the docker compose up --watch command.

It is of course possible to wait on services to be running before log/exec commands using a script, rather than sleep commands. This is desirable, because otherwise you need to run docker compose build before starting the TMUX dashboard. But, the docker CLI metadata commands required for this take container names, not docker compose service names, so it's a little wonky:

#!/bin/bash

sleep 1

SERVICE=$1

COMPOSE_PROJECT="$(docker compose ls -a --format json | jq -r '.[0].Name')"

echo "Waiting for $SERVICE to be running..."
while [ "$(docker inspect -f '{{.State.Status}}' $COMPOSE_PROJECT-$SERVICE-1 2>/dev/null)" != "running" ]; do
  echo -n '.'
  sleep 2;
done

This script takes advantage of the fact that, if you haven't given your services explicit container_names, the container names that get generated when you start compose will be {COMPOSE_PROJECT_NAME}-{SERVICE_NAME}-1. (That final integer can be greater for a service if you're using the --scale parameter or if you've set replicas > 1 in the service's deploy config. Regardless, for the purposes of this script we only care about the first container of a service).

If you have given your services explicit container names, the script is simpler:

#!/bin/bash

sleep 1

CONTAINER=$1

echo "Waiting for $CONTAINER to be running..."
while [ "$(docker inspect -f '{{.State.Status}}' $CONTAINER 2>/dev/null)" != "running" ]; do
  echo -n '.'
  sleep 2;
done

In either case, you could then rewrite the panes above like

      - web:
        - bash the_wait_script.sh watch_web
        - clear && docker compose -f docker-compose.watch.yml logs --since=1s -f watch_web

Using mkcert and Caddy with Docker Compose to host web services over HTTPS for local development

Nathan Cook — Tue, 21 Apr 2026 07:16:47 +0000

This tutorial walks you through setting up a simple Docker Compose project that serves two Node web servers over HTTPS using Caddy as a reverse proxy. You will learn how to use mkcert to generate wildcard certificates and the minimal configuration needed in the Caddyfile and docker-compose.yml to get it all working.

This tutorial was written for Linux or WSL users (I'm running Ubuntu).

Github repo

Introduction

When running web services locally with Docker Compose, it’s easy to default to plain HTTP for simplicity. But doing so creates a gap between your development setup and production, where HTTPS is almost always used. This gap matters because of development/production parity: the closer your environments match, the fewer surprises you’ll hit when deploying.

Using HTTPS locally helps you catch issues early, like secure cookies not being set, browser features being blocked in non-secure contexts, or mixed-content errors. By adding a reverse proxy and self-signed certificates to your Compose setup, you mirror real-world conditions more closely and avoid the classic “well, it worked on my machine...” problem.

First Steps

- Make sure you have the following required packages installed

Git
Docker and Docker Compose (naturally). (Install Docker Engine)
- It's worthwhile to check if docker and docker compose are up to date. As I'm writing this tutorial, Docker is currently at version v29.4.1, and docker compose at v5.1.2.
- Run docker -v and docker compose --version to check your versions
- If you're out of date by a major version for either, consider following the intructions for uninstalling old versions at https://docs.docker.com/engine/install/ubuntu/#uninstall-old-versions and re-installing docker.
mkcert
- Follow the instructions at https://github.com/FiloSottile/mkcert#installation to install mkcert for your environment
- After mkcert is installed, run "mkcert -install". This is a one-time setup step that enables your computer to trust the locally generated SSL certificates created by mkcert. The docker compose project described in this tutorial will not work otherwise.

- Run the following commands in whatever directory you keep your coding projects to clone the tutorial repo and cd into the directory:

git clone https://github.com/moofoo/compose-caddy-tutorial.git

cd compose-caddy-tutorial

You should see the following directory structure:

├── Caddyfile
├── Dockerfile
├── README.md
├── docker-compose.yml
├── apps
│   ├── admin.js
│   └── www.js
└── scripts
    ├── caddyfile.sh
    └── certs.sh

Update /etc/hosts

Did you run mkcert -install after installing mkcert? If you haven't, do that now.

For this tutorial, our docker compose project will be serving two extremely simple node web servers at https://www.caddy-test.local and https://admin.caddy-test.local. We will be generating wildcard certificates to manage the two subdomains (www and admin).

Before we get to the Caddy/Compose configuration, the first thing we're going to do is update the /etc/hosts file to map those domains to a local loopback ip address

The available loopback address range you have for local usage is 127.0.0.1 to 127.255.255.255, but I've found that below 127.0.0.10 can sometimes be hit or miss on availability, so we're going to use 127.0.0.11 for this tutorial.

At any rate,

- Open your the hosts file at `/etc/hosts` and add these lines at the bottom:

127.0.0.11 www.caddy-test.local
127.0.0.11 admin.caddy-test.local

Creating certificates for Caddy

As mentioned, for this project we're going to create "wildcard" certificates. Wildcard SSL/TLS certificates are certificates that secure an entire domain and all of its first-level subdomains with a single certificate. For example, *.example.com covers api.example.com, www.example.com, and admin.example.com.

Running "mkcert --help" tells us the syntax to create wildcard certificates is:

$ mkcert "*.example.it"
    Generate "_wildcard.example.it.pem" and "_wildcard.example.it-key.pem".

Knowing that,

- Run the following individual commands (or use the helper ./scripts/certs.sh script mentioned afterwards) to generate wildcard certificates for "*.caddy-test.local" in the ./certs directory

mkcert "*.caddy-test.local"

mkdir -p ./certs

mv ./_wildcard.caddy-test.local.pem ./certs

mv ./_wildcard.caddy-test.local-key.pem ./certs

The tutorial repo has a helper bash script scripts/certs.sh, which takes a domain as an argument and performs the above commands. To create certificates in ./certs like the commands would do above, call it like bash scripts/certs.sh caddy-test.local from the project's root directory.

The Caddy configuration file

Here is the Caddyfile the caddy service will use:

(tls) {
    tls /etc/caddy/certs/_wildcard.caddy-test.local.pem /etc/caddy/certs/_wildcard.caddy-test.local-key.pem
}

www.caddy-test.local{
    import tls
    reverse_proxy www:3000
}

admin.caddy-test.local{
    import tls
    reverse_proxy admin:3001
}

Let's go over each block

(tls) {
    tls /etc/caddy/certs/_wildcard.caddy-test.local.pem /etc/caddy/certs/_wildcard.caddy-test.local-key.pem
}

This snippet configures tls to use the wildcard certificates we created earlier. The caddy docker compose service config, which we'll get to in a bit, will use a bind mount volume to make our local ./certs directory available in the container at path /etc/caddy/certs.

www.caddy-test.local {
    import tls
    reverse_proxy www:3000
}

This site block configures the reverse proxy for https://www.caddy-test.local.

The import tls line copies the previously defined tls snippet into the block.
reverse_proxy www:3000 creates a reverse proxy for host www and port 3000.
- www:3000 is the service/host name and port of the node service within the docker compose bridge network.
In other words, this site block makes it so requests to www.caddy-test.local will get routed to address www:3000, which within the internal docker bridge network belongs to a service running a Node web server that accepts requests on port 3000.

The site block for admin.caddy-test.local follows the same pattern, but with admin:3001 for the service/host name and port.

Now, let's take a look at how the services are set up in docker-compose.yml:

Service setup in docker-compose.yml

name: caddy-tutorial

networks:
  caddy_tutorial_network:

volumes:
  caddy_data:
  caddy_config:

services:
  www:
    networks:
      - caddy_tutorial_network
    expose:
      - 3000
    environment:
      - PORT=3000
    working_dir: /app
    command: node www.js
    build:
      args:
        NAME: www
      context: .
      dockerfile: ./Dockerfile

  admin:
    networks:
      - caddy_tutorial_network
    expose:
      - 3001
    environment:
      - PORT=3001
    command: node admin.js
    working_dir: /app
    build:
      args:
        NAME: admin
      context: .
      dockerfile: ./Dockerfile

  caddy:
    image: caddy:2.11.2-alpine
    networks:
      - caddy_tutorial_network
    ports:
      - "127.0.0.11:80:80"
      - "127.0.0.11:443:443"
    depends_on:
      - www
      - admin
    volumes:
      - ./certs:/etc/caddy/certs
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    cap_add:
      - NET_ADMIN

Let's go over each section, starting from the top:

networks:
  caddy_tutorial_network:

This creates a "user defined bridge network", which allows services to communicate with each other by name or alias (versus by ip address). Like admin:3001 for the admin Node service, for example.

volumes:
  caddy_data:
  caddy_config:

This defines two named volumes which are used by the Caddy service for persisting whatever data/config in its container (the official caddy examples say they're needed).

Now the node services:

  www:
    networks:
      - caddy_tutorial_network
    expose:
      - 3000
    environment:
      - PORT=3000
    working_dir: /app
    command: node www.js
    build:
      args:
        NAME: www
      context: .
      dockerfile: ./Dockerfile

admin:
  networks:
    - caddy_tutorial_network
  expose:
    - 3001
  environment:
    - PORT=3001
  command: node admin.js
  working_dir: /app
  build:
    args:
      NAME: admin
    context: .
    dockerfile: ./Dockerfile

Looking at the config for service www:

    networks:
      - caddy_tutorial_network
    expose:
      - 3000

This config connects the service to the user defined bridge network, and exposes it to the other services on the network. The service is therefore visible at address www:3000 to other services running on that internal docker network. Because ports has not been defined, the service cannot be accessed directly by the host (which is because it doesn't need to be).

    environment:
      - PORT=3000
    command: node www.js
    working_dir: /app

This config sets the environment variable PORT to 3000 in the running container, and specifies that the command node www.js on path /app should run when the service starts up.

Let's look at ./apps/www.js now:

import http from "http";

const host = "0.0.0.0";
const port = process.env.PORT; // 3000 for service `www`, 3001 for service `admin`, per the service environment config

const requestListener = function (req, res) {
  res.writeHead(200);
  res.end("User Site");
};

const server = http.createServer(requestListener);

server.listen(port, host, () => {
  console.log(`Server is running on http://${host}:${port}`);
});

This very simple server runs at address 0.0.0.0 on the port determined by the environment variable from the service config. 0.0.0.0 isn't a real address, but basically translates to "all IPv4 addresses". The server simply responds to requests with the text 'User Site'.

./apps/admin.js is the exact same code, except it responds with the text 'Admin Site'.

Moving on with the Docker Compose service config,

build:
  args:
    NAME: www
  context: .
  dockerfile: ./Dockerfile

This part of the config determines how the container image for the service will be built. The NAME arg with value www is available for the Dockerfile on build, which allows the use of a single Dockerfile for this simple project. Let's look at that Dockerfile now:

FROM node:lts-alpine
WORKDIR /app
ARG NAME

COPY ./apps/$NAME.js /app/$NAME.js

CMD ["node", "$NAME.js"]

So, the container image for the www service would basically be this, with $NAME resolving to www upon build:

FROM node:lts-alpine
WORKDIR /app

COPY ./apps/www.js /app/www.js

CMD ["node", "www.js"]

And likewise for the admin service's image.

Finally, let's go over the the caddy service configuration, which is using the caddy:2.11.2-alpine image:

caddy:
  image: caddy:2.11.2-alpine
  networks:
    - caddy_tutorial_network
  ports:
    - "127.0.0.11:80:80"
    - "127.0.0.11:443:443"
  depends_on:
    - www
    - admin
  volumes:
    - ./certs:/etc/caddy/certs
    - ./Caddyfile:/etc/caddy/Caddyfile
    - caddy_data:/data
    - caddy_config:/config
  cap_add:
    - NET_ADMIN

Starting from the top:

  networks:
    - caddy_tutorial_network
  ports:
    - "127.0.0.11:80:80"
    - "127.0.0.11:443:443"
  depends_on:
    - www
    - admin

Like the node services, the Caddy service runs on the caddy_tutorial_network bridge network. But unlike the Node services, it exposes itself to the host at address 127.0.0.11 on ports 80 and 443.

The depends_on config tells the Caddy service to wait until the www and admin services are running before it gets going, since Caddy will freak if the Node servers aren't responsive when it starts up.

volumes:
  - ./certs:/etc/caddy/certs
  - ./Caddyfile:/etc/caddy/Caddyfile
  - caddy_data:/data
  - caddy_config:/config

The first two volumes bind mount our ./certs directory and the Caddyfile to the appropriate paths in the container. The second two volumes are the named volumes defined at the top of the docker-compose.yml, which Caddy needs for storing whatever.

cap_add:
  - NET_ADMIN

This config permits the Caddy service to override buffer limits as needed without requiring manual changes to your linux configuration. Caddy running as a compose service is oddly temperamental about whether it has buffers of the size it thinks it needs. In any case, adding this config will fix that problem when/if caddy complains about buffer sizes.

Alright! Let's run this thing!

Run that thang!

From the project root directory, run

 sudo docker compose up --build

(I'm assuming docker must be run by the root user, which can be changed by following the instructions here)

After everything builds and starts up, you should see the text 'User Site' when you open https://www.caddy-test.local in your browser and 'Admin Site' when you open https://admin.caddy-test.local. Huzzah!

Tips

After you've made changes to the caddy service definition, the Caddyfile, and/or your /etc/hosts file, you may find that your project's web services aren't available as expected at the domain(s) you've specified.

Assuming your configuration is actually correct, you can (usually) resolve such docker networking issues / caddy confusion by running:

docker compose down -v --remove-orphans && docker network prune

and then do docker compose up --build when you start the compose project

Optimize Yarn 1.2 Monorepo Docker Development with Turborepo: Tips for Prisma and Dockerfile build filtering

Nathan Cook — Fri, 02 Jun 2023 09:44:52 +0000

Github Repository for this article

This yarn 1.2 monorepo demonstrates

Why putting Prisma in its own workspace is a good idea
Docker container build time difference between turbo run build --filter=service and turbo run build --filter=service^...

Setup

bash setup.sh

#!/bin/bash

docker pull node:20.2.0-alpine3.17
docker pull postgres:15.3-alpine3.17

docker image build -f dockerfiles/Dockerfile.node -t custom-node:latest dockerfiles

yarn
yarn workspace prisma-client build
yarn

This monorepo has the following workspaces:

apps/frontend
apps/backend
packages/prisma-client

Why put Prisma in a workspace?

App workspaces can access Prisma types

apps/backend/src/app.service.ts

import {Injectable} from "@nestjs/common";
import {PrismaService} from "nestjs-prisma";
import type {User} from "prisma-client";

@Injectable()
export class AppService {
  constructor(private readonly prisma: PrismaService) {}
  getHello(): string {
    return "Hello World!";
  }

  getUsers(): Promise<User[]> {
    return this.prisma.user.findMany();
  }
}

apps/frontend/src/use-data.ts

import React from "react";
import {ofetch} from "ofetch";
import type {User} from "prisma-client";

export default function useData() {
  const [data, setData] = React.useState<User[]>([]);

  React.useEffect(() => {
    (async () => {
      const data = await ofetch("http://localhost:3333/users");
      setData(data);
    })();
  }, []);

  return data;
}

In frontend/backend package.json

{
  "dependencies": {
    "prisma-client": "*"
  }
}

Simplifies generating the prisma client in Docker containers

packages/prisma-client/package.json

{
  "name": "prisma-client",
  "version": "1.0.0",
  "main": "dist/index.js",
  "files": ["src/index.ts"],
  "repository": "https://github.com/moofoo/turborepo-tricks-prisma-workspace.git",
  "author": "moofoo <nathancookdev@gmail.com>",
  "license": "MIT",
  "private": true,
  "scripts": {
    "build": "npx -y rimraf dist/* && prisma generate && npx tsc"
  },
  "dependencies": {
    "@prisma/client": "^4.15.0"
  },
  "devDependencies": {
    "@types/node": "^20.2.5",
    "prisma": "^4.15.0",
    "rimraf": "^5.0.1",
    "typescript": "^5.1.3"
  }
}

With prisma generate in the build script, turbo run build ... will generate the prisma client for workspaces that have prisma-client as a dependency. This is particularly useful when it comes to writing Dockerfiles, since it makes it easier to write generic Dockerfiles for development.

Build time difference between `--filter=service` and `--filter=service^...`

If you compare docker-compose.good.yml and docker-compose.bad.yml, you'll see that the only difference is whether the Node.js services use Dockerfile.good or Dockerfile.bad.

The only difference between those Dockerfiles is on line 30

Dockerfile.good

RUN turbo run build --no-cache --filter=${APP}^...

Dockerfile.bad

RUN turbo run build --no-cache --filter=${APP}

The latter RUN command is equivalent to running yarn workspace ... build for the given app workspace and all dependent workspaces

PLEASE NOTE THAT THE `compare.sh` BASH SCRIPT RUNS `docker system prune -f` TO ACCURATELY COMPARE BUILD TIMES

Run compare.sh to see the difference:

$ bash compare.sh
Cleaning up
Building bad
yarn run v1.22.19
$ docker compose -f docker-compose.bad.yml build --no-cache -q
Done in 155.18s.

real    2m35.339s
user    0m0.531s
sys     0m0.230s
Cleaning up
Building good
yarn run v1.22.19
$ docker compose -f docker-compose.good.yml build --no-cache -q
Done in 94.58s.

real    1m34.768s
user    0m0.498s
sys     0m0.165s

`--filter=workspace` : 2m35.339s

`--filter=workspace^...` : 1m34.768s

(I intentionally didn't follow dependency best practices with the Frontend app to increase its build time, to make the difference between the two build commands more clear. The basic point is don't build workspaces if you don't need to)

Fully featured report generation in Node with the JSReports rendering core

Nathan Cook — Fri, 26 May 2023 05:39:03 +0000

(Check out this repo to get an idea of what's possible)

If you're interested in a free, self-hosted NodeJS report generation solution that doesn't compromise on templating functionality, you should check out JSReport, specifically the functionality one can build using the jsreport 'rendering core'.

JSReport is open-source, and unlike many SaaS providers in this space, they do not gatekeep ANY of their product's core functionality behind tiered subscription pricing. While JSReport does charge for their web-based 'Template Studio' and SaaS offerings, the report generation framework that powers these products is open source and free to use however you want.

Let's get started with a basic example.

Open up your terminal (I'm assuming linux, no promises if you're in Windows-land) and run the following:

git clone https://github.com/moofoo/basic-jsreport-core-example.git && \
cd basic-jsreport-core-example && \
yarn

First, lets look at the package.json

{
  "name": "basic-jsreport-core-example",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "@jsreport/jsreport-core": "^3.11.4",
    "@jsreport/jsreport-docx": "^3.7.1",
    "@jsreport/jsreport-handlebars": "^3.2.1",
    "@jsreport/jsreport-unoconv": "^3.0.1",
    "handlebars": "^4.7.7"
  }
}

@jsreport/jsreport-core is the "minimalist jsreport rendering core", on to which we'll add 'extensions' (plugins, what have you), to build up the functionality we want.

JSReport categorizes extensions into three categories: Engines, Recipes, Everything Else

Engines - These are templating languages, i.e. handlebars, ejs, etc. The current example uses handlebars, by way of the @jsreport/jsreport-handlebars extension. For any given Engine you will also need the actual templating language in your dependencies - handlebars@4.7.7 in this case.
Recipes

"A recipe represents the technique used to print the document. It can be an HTML to pdf conversion, DOCX rendering, and others."

The current example employs the docx recipe, so we have the @jsreport/jsreport-docx extension as a dependency.

3, Everything Else - for instance, this repo uses the @jsreport/jsreport-unoconv extension to do PDF conversion via unoconv.

Now let's look at index.js. Here's that file:

const { readFileSync, writeFileSync, unlinkSync } = require("fs");
const templateData = require('./data.json');

// remove existing report files, if they exist
try {
  unlinkSync("./report.docx");
  unlinkSync("./report.pdf");
} catch (err) {
  console.log("no report files");
}

// Create jsreport instance
const jsreport = require("@jsreport/jsreport-core")();

// Add plugins: docx recipe, handlebars engine and unoconv extension for pdf conversion
jsreport.use(require("@jsreport/jsreport-docx")());
jsreport.use(require("@jsreport/jsreport-handlebars")());
jsreport.use(require("@jsreport/jsreport-unoconv")());

(async () => {
  // Initialize jsreport instance
  await jsreport.init();

  // Read template.docx, base64 encoded
  const content = readFileSync("./template.docx", {encoding: "base64"});

  // Render a .docx report from template
  const resultDocx = await jsreport.render({
    template: {
      content: "",
      recipe: "docx",
      engine: "handlebars",
      docx: {
        templateAsset: {
          content,
          encoding: "base64",
        },
      },
    },
    data:templateData
  });

  // Write report.docx to disk
  await writeFileSync("./report.docx", resultDocx.content, {encoding: "utf-8"});
  console.log("report.docx created");

  // Render a .pdf report from template using unoconv extension
  const resultPdf = await jsreport.render({
    template: {
      content: "",
      recipe: "docx",
      engine: "handlebars",
      docx: {
        templateAsset: {
          content,
          encoding: "base64",
        },
      },
      unoconv: {
        format: "pdf",
        enabled: true,
      },
    },
    data: templateData
  });

  // Write report.pdf to disk
  await writeFileSync("./report.pdf", resultPdf.content, "binary");
  console.log("report.pdf created");
})();

Let's go over the JsReport-relevant lines. We start with some initialization boilerplate:

// Create jsreport instance
const jsreport = require("@jsreport/jsreport-core")();

// Add plugins: docx recipe, handlebars engine and unoconv extension for pdf conversion
jsreport.use(require("@jsreport/jsreport-docx")());
jsreport.use(require("@jsreport/jsreport-handlebars")());
jsreport.use(require("@jsreport/jsreport-unoconv")());

The next lines initialize the instance given the added extensions and gets the template file:

  // Initialize jsreport instance
  await jsreport.init();

  // Read template.docx, base64 encoded
  const content = readFileSync("./template.docx", {encoding: "base64"});

Note the base64 encoding.

At this point, the jsReport instance is ready to render docx (or pdf) reports from .docx templates:

// Render a .docx report from template
  const resultDocx = await jsreport.render({
    template: {
      content: "",
      recipe: "docx",
      engine: "handlebars",
      docx: {
        templateAsset: {
          content,
          encoding: "base64",
        },
      },
    },
    data:templateData
  });

  // Write report.docx to disk
  await writeFileSync("./report.docx", resultDocx.content, {encoding: "utf-8"});
  console.log("report.docx created");

Let's go over the options passed to jsreport.render, specifically the template config:

content: "",

While the content param isn't used here, JsReport will throw an error if it is undefined. An empty string suffices.

recipe: "docx"

This sets the render 'recipe'. Regarding naming conventions:

"The convention is that jsreport repository extension starts with jsreport-xxx, but the extension real name and also the recipes or engines it registers excludes the jsreport- prefix. This means if you install extension @jsreport/jsreport-handlebars the engine's name you specify in the render should be handlebars."

Accordingly, @jsreport/jsreport-docx transmutes to 'docx', here.

engine: "handlebars"

same story

docx: {
  templateAsset: {
    content,
    encoding: "base64",
  },
},

content is just the template.docx file, base64 encoded, and encoding informs the render method about that encoding.

The next jsreport.render call is identical to the previous one, with one addition to the template options:

 unoconv: {
    format: "pdf",
    enabled: true,
 },

So, when this render runs, a PDF will be created, rather than a .docx file. Note that enabled is assumed to be false if undefined, so it must be set to true here.

Using whatever document viewer you have handy, check out whats in template.docx. This is just an invoice example I pulled from the JSReport Playground

Ok, let's run this thing:

node index.js

Assuming nothing goes horribly wrong, you should now have two report files in the repo root, report.pdf and report.docx.

--------------------

While the code presented here is nothing fancy, the real magic is how this extremely simple setup gives you full access to JSReport's robust templating features, for example:

And that's just for .docx based templates.

That's all for now!

NestJS + JSReport integration will be covered in a future article, however the repo for that article is already complete: https://github.com/moofoo/nestjs-jsreport-examples

Creating a development dockerfile and docker-compose.yml for yarn 1.22 monorepos using Turborepo.

Nathan Cook — Wed, 17 May 2023 03:01:31 +0000

Check out my new tutorial on this subject here

(Be sure to check out the example repo)

If you've ever worked in a yarn monorepo project with inter-dependent workspaces, you know that creating docker containers for development in a way that avoids unnecessary rebuilds can be a challenge.

Turborepo, "...an intelligent build system optimized for JavaScript and TypeScript codebases", provides tools that make this task much easier.

Let's assume a project that looks like something like this:

- /project-directory
    - /apps
        - /frontend
            - package.json
            - other files...
        - /backend
            - package.json
            - other files...
    - /packages
        - /shared-stuff
            - package.json
            - other files...
    - .dockerignore
    - package.json
    - turbo.json
    - Dockerfile.dev
    - docker-compose.yml

.dockerignore

**/node_modules
**/.next
**/dist

This ensures that node_modules and build artifacts are excluded when copying directories to the container from the host in our Dockerfile.

package.json

{
  "name": "turbo-docker-monorepo",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "packageManager": "yarn@1.22.19",
  "devDependencies": {
    "turbo": "^1.9.6"
  }
}

This is the minimal package.json you'll need for a yarn monorepo that makes use of turborepo with workspaces in the 'apps' and 'packages' directories. Not much else to say!

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

This turbo.json file is taken from the basic turborepo example.

Let's assume that the backend app has the packages/shared-stuff workspace as a dependency (meaning the backend package.json has "shared-stuff": "*" in its list of dependencies).

We can use turborepo to build backend in a way that respects its dependence on the shared-stuff package with the command turbo run build --filter=backend, which will build (in order) the shared-stuff package and then backend app. Cool!

Dockerfile.dev

# syntax=docker/dockerfile:1.5.2
# based on: https://github.com/vercel/turbo/blob/main/examples/with-docker/apps/api/Dockerfile

FROM node:20.2-alpine3.17 as base

# adding apk deps to avoid node-gyp related errors and some other stuff. adds turborepo globally
RUN apk add -f --update --no-cache --virtual .gyp nano bash libc6-compat python3 make g++ \
      && yarn global add turbo \
      && apk del .gyp

#############################################
FROM base AS pruned
WORKDIR /app
ARG APP

COPY . .

# see https://turbo.build/repo/docs/reference/command-line-reference#turbo-prune---scopetarget
RUN turbo prune --scope=$APP --docker

#############################################
FROM base AS installer
WORKDIR /app
ARG APP

COPY --from=pruned /app/out/json/ .
COPY --from=pruned /app/out/yarn.lock /app/yarn.lock

# Forces the layer to recreate if the app's package.json changes
COPY apps/${APP}/package.json /app/apps/${APP}/package.json

# see https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/reference.md#run---mounttypecache
RUN \
      --mount=type=cache,target=/usr/local/share/.cache/yarn/v6,sharing=locked \
      yarn --prefer-offline --frozen-lockfile

COPY --from=pruned /app/out/full/ .
COPY turbo.json turbo.json

# For example: `--filter=frontend^...` means all of frontend's dependencies will be built, but not the frontend app itself (which we don't need to do for dev environment)
RUN turbo run build --no-cache --filter=${APP}^...

# re-running yarn ensures that dependencies between workspaces are linked correctly
RUN \
      --mount=type=cache,target=/usr/local/share/.cache/yarn/v6,sharing=locked \
      yarn --prefer-offline --frozen-lockfile

#############################################
FROM base AS runner
WORKDIR /app
ARG APP
ARG START_COMMAND=dev

COPY --from=installer /app .

CMD yarn workspace ${APP} ${START_COMMAND}

Let's go over what happens in each layer. For the following discussion, assume that the backend app service is being created, which has shared-stuff as a dependency.

base

FROM node:20.2-alpine3.17 as base

RUN apk add -f --update --no-cache --virtual .gyp nano bash libc6-compat python3 make g++ \
      && yarn global add turbo \
      && apk del .gyp

This layer adds container dependencies to ensure NPM modules that use node-gyp build correctly. It also adds turborepo globally. The remaining layers are built from 'base'

pruned

FROM base AS pruned
WORKDIR /app
ARG APP

COPY . .

RUN turbo prune --scope=$APP --docker

This layer copies over the project files and runs turbo prune for the service in question. The $APP argument will be either 'frontend' or 'backend' (assuming the later, for this example), which is set in docker-compose.yml (this will be covered last). Regarding the --docker flag:

With the docker flag, the prune command will generate folder called out with the following inside of it:

A folder json with the pruned workspace's package.jsons

A folder full with the pruned workspace's full source code, but only including the internal packages that are needed to build the target.

A new pruned lockfile that only contains the pruned subset of the original root lockfile with the dependencies that are actually used by the packages in the pruned workspace.

Assuming we're building the backend service container, here is what the 'out' directory in the ‘pruned’ layer would look like at this point:

- /out
    - /full
       - /apps
           - /backend (all files)
       - /packages
           - /shared-stuff (all files)
       - .gitignore
       - package.json
       - turbo.json
    - /json
        - /apps
            - /backend
                - package.json
        - /packages
            - /shared-stuff
                - package.json
        - package.json
    - yarn.lock

Note that the 'frontend' app is not present and (according to the turborepo docs) its dependencies were excluded from yarn.lock, which is what we want!

installer

FROM base AS installer
WORKDIR /app
ARG APP

# COPY 1
COPY --from=pruned /app/out/json/ .
COPY --from=pruned /app/out/yarn.lock /app/yarn.lock
COPY apps/${APP}/package.json /app/apps/${APP}/package.json

# RUN 1
RUN \
      --mount=type=cache,target=/usr/local/share/.cache/yarn/v6,sharing=locked \
      yarn --prefer-offline --frozen-lockfile

# COPY 2
COPY --from=pruned /app/out/full/ .
COPY turbo.json turbo.json

# RUN 2
RUN turbo run build --no-cache --filter=${APP}^...

# RUN 3
RUN \
      --mount=type=cache,target=/usr/local/share/.cache/yarn/v6,sharing=locked \
      yarn --prefer-offline --frozen-lockfile

The COPY 1 command series begins by copying the json directory in out from the pruned layer, as well as the 'scoped' yarn.lock file. It also redundantly copies the app's package.json from the host, which I've found necessary for the container to recreate correctly when shared workspace dependencies change.

The first run command (RUN 1) runs yarn and uses a cache mount targeting the yarn cache directory, which will help speed up subsequent re-builds.

The next two statements (COPY 2) copy the contents of out/full from the pruned layer as well as turbo.json from the host.

Since this container will run in a dev environment, it means we can safely skip building the backend app. However, we do need to build packages/shared-stuff, which in the current example is a dependency of backend. This is done with the command in RUN 2: RUN turbo run build --no-cache --filter=${APP}^.... In this case, since we're building the backend service container, the filter flag will resolve to --filter=backend^.... What this means is that all workspace dependencies of backend, but not backend itself, will be built, which is what we want.

This is a huge time saver for certain frameworks (looking at you, Next.js).

The final RUN command (RUN 3) is just a copy of the first (RUN 1). This final yarn call ensures that dependencies between workspaces are linked correctly.

runner

FROM base AS runner
WORKDIR /app
ARG APP
ARG START_COMMAND=dev

COPY --from=installer /app .

CMD yarn workspace ${APP} ${START_COMMAND}

The final layer copies over the installer layer and runs the command to start the app (based on the START_COMMAND argument).

Now let's look at docker-compose.yml, specifically the config for the backend service (almost done!)

version: '3.8'

x-defaults:
  &defaults
  init: true
  tty: true
  networks:
    - my_monorepo_network

networks:
  my_monorepo_network:

services:
    backend:
        <<: *defaults
        ports:
          - "3333:3333"
        command: yarn workspace backend dev
        environment:
          - PORT=3333
        build:
          args:
            APP: backend
            START_COMMAND: dev
          context: .
          dockerfile: ./Dockerfile.dev
        volumes:
          - ./apps/backend:/app/apps/backend
          - /app/apps/backend/node_modules
    ...other services...

This is a pretty typical definition for a Node service. Here you can see the build args, which are used in Dockerfile.dev.

Changing dependencies

tl;dr: docker compose up -d -V --build <service>

When you change dependencies for your node services on the host, you need to rebuild the container for it to reflect those changes.

You don't need to use docker compose build --no-cache <service> for this. There are better methods which don't require completely busting cache and starting from scratch.

The complicating factor for node services, as commonly configured in docker compose projects, is anonymous volumes:

...

volumes:
   - ./apps/backend:/app/apps/backend
   - /app/apps/backend/node_modules # <-- this guy

...

In the context of yarn 1.22 monorepos, apps/backend/node_modules contains development dependencies that are unique to that workspace.

The point of the anonymous volume /app/apps/backend/node_modules is to make it so node_modules in the backend workspace within the container is excluded from the bind mount ./apps/backend:/app/apps/backend.

Because of that volume, simply running docker compose build <service> or docker compose up -d --build <service> won't work like you expect it to when development dependencies for backend change.

There are two ways I've found to reliably recreate containers when deps change, while dealing with anonymous volumes:

1 The -V, --renew-anon-volumes flag

docker compose up -d -V --build <service>

You don't need to stop or restart the service.

2 rm container and build

docker compose rm -f -s <service> && docker compose up -d --build <service>

Either of these methods will do the trick.

NestJS + Prisma + PostgreSQL ~ RLS multi-tenancy using nestjs-prisma, nestjs-cls and Prisma Client Extensions

Nathan Cook — Thu, 11 May 2023 23:33:00 +0000

(Github repository for this article)

Here's a simple way to do multi-tenancy in NestJS with Prisma using Client Extensions and AsyncLocalStorage (via nestjs-cls).

This post describes the basics of a generic NestJS implementation. Look at this repo for a complete and functional example app. Checkout branch async-hooks to see the AsyncLocalStorage-based implementation (which relates to this post). The repo also demonstrates how to use request-scoped providers (main branch) and durable request-scoped providers (durable branch).

Step #1: Setup AsyncLocalStorage using nestjs-cls in your bootstrap function:

// main.ts
import {ClsMiddleware} from 'nestjs-cls';

async function bootstrap() {
  // init app...

  app.use(
    new ClsMiddleware({
      async setup(cls, req) {
        cls.set('TENANT_ID', req.params('tenant_id'));
      },
    }).use
  );

  // etc
}

Step #2: Add ClsModule.forRoot({ global:true }) to your App Module (app.module.ts) imports.

Step #3: Create a file that exports a custom Factory Provider that returns an extended Prisma client.

// prisma-tenancy.provider.ts
import { PrismaModule, PrismaService } from 'nestjs-prisma';
import { ClsService } from 'nestjs-cls';

const useFactory = (prisma: PrismaService, store: ClsService) => {
    return prisma.$extends({
        query: {
            $allModels: {
                async $allOperations({ args, query }) {
                    const tenantId = store.get('TENANT_ID');


                    const [, result] = await prisma.$transaction([
                        prisma.$executeRaw`SELECT set_config('tenancy.tenant_id', ${`${tenantId || 0}`}, TRUE)`,
                        query(args),
                    ]);

                    return result;
                },
            },
        },
    });
};

export type ExtendedTenantClient = ReturnType<typeof useFactory>;

export const TENANCY_CLIENT_TOKEN = Symbol('TENANCY_CLIENT_TOKEN');

export const PrismaTenancyClientProvider = {
    provide: TENANCY_CLIENT_TOKEN,
    imports: [PrismaModule],
    inject: [PrismaService, ClsService],
    useFactory
};

Step #4: Create a module that exports the above Factory Provider

// prisma-tenancy.module.ts
import { Module, Global } from '@nestjs/common';
import { PrismaTenancyClientProvider, TENANCY_CLIENT_TOKEN } from './prisma-tenancy.provider';
import { PrismaModule } from 'nestjs-prisma';

@Global()
@Module({
    imports: [PrismaModule],
    providers: [PrismaTenancyClientProvider],
    exports: [TENANCY_CLIENT_TOKEN]
})
export class PrismaTenancyModule { }

Step #5: Add the module above to your root app.module.ts imports.

Now, you can inject the extended client using the token for your custom provider (TENANCY_CLIENT_TOKEN, in this case).

import {Injectable, Inject} from "@nestjs/common";
import {
  TENANCY_CLIENT_TOKEN,
  ExtendedTenantClient,
} from "./prisma-tenancy.provider";

@Injectable()
export class SomeService {
  constructor(
    @Inject(TENANCY_CLIENT_TOKEN) private readonly prisma: ExtendedTenantClient
  ) {}

  // etc
}

Useful Links

Introducing DNV - Frictionless Node development with Docker Compose

Nathan Cook — Tue, 03 Aug 2021 00:23:21 +0000

Hello! If you're a Node developer who uses Docker Compose, you should check out DNV.

DNV works behind the scenes to keep dependencies in your Docker container in-sync with your local project.

It also comes with a custom made, featureful ncurses-like UI designed for use when developing apps using Docker Compose.

This was my 'covid isolation' personal project to learn more about Node fundamentals, and I think it turned out pretty good! If you do check it out and run into any problems, please create an issue.

Here's a showcase recorded using Asciinema which shows how you can shell in to containers, install and run programs with full interactivity, open the README.md for your dependencies, show a live 'metrics' display with CPU, memory and event loop stats of the Node process, view a list of and run .sh scripts and script entries from your package.json in the container, and more!

DNV Showcase

Forem: Nathan Cook

Typescript Monorepo Development using Docker Compose Watch, Turborepo and PNPM

Introduction

Required Packages for Tutorial repo

Tutorial repo description and goals

Development Dockerfile

The turbo.json file

The docker-compose.yml file

An example workflow

Using TMUX and tmuxinator for a better docker compose experience

Article Index

The Pitch

Install necessary packages

TMUX command basics

How to show the list of TMUX keybindings

How to detach from a TMUX session

How to open the 'command prompt' in TMUX and kill the current session and exit TMUX

Configuring TMUX with the ~/.tmux.config file

Summary

Configuring TMUX in .yaml with tmuxinator

Going over each section of this config file from the top:

Extending TMUX with the Tmux Plugin Manager

1. Install the Tmux Plugin Manager

2. Edit your ~/.tmux.config file to use the plugin

2. Configure/use the plugin

Resources and Links

TMUX Cheat sheets

Plugins

Docs and Other

Extra: Considerations when using docker compose develop 'watch' functionality

Using mkcert and Caddy with Docker Compose to host web services over HTTPS for local development

Introduction

First Steps

- Make sure you have the following required packages installed

- Run the following commands in whatever directory you keep your coding projects to clone the tutorial repo and cd into the directory:

Update /etc/hosts

- Open your the hosts file at /etc/hosts and add these lines at the bottom:

Creating certificates for Caddy

- Run the following individual commands (or use the helper ./scripts/certs.sh script mentioned afterwards) to generate wildcard certificates for "*.caddy-test.local" in the ./certs directory

The Caddy configuration file

Service setup in docker-compose.yml

Run that thang!

Tips

Optimize Yarn 1.2 Monorepo Docker Development with Turborepo: Tips for Prisma and Dockerfile build filtering

Setup

Why put Prisma in a workspace?

App workspaces can access Prisma types

In frontend/backend package.json

Simplifies generating the prisma client in Docker containers

Build time difference between --filter=service and --filter=service^...

The latter RUN command is equivalent to running yarn workspace ... build for the given app workspace and all dependent workspaces

PLEASE NOTE THAT THE compare.sh BASH SCRIPT RUNS docker system prune -f TO ACCURATELY COMPARE BUILD TIMES

--filter=workspace : 2m35.339s

--filter=workspace^... : 1m34.768s

Fully featured report generation in Node with the JSReports rendering core

--------------------

Creating a development dockerfile and docker-compose.yml for yarn 1.22 monorepos using Turborepo.

.dockerignore

package.json

turbo.json

Dockerfile.dev

base

pruned

installer

runner

Changing dependencies

1 The -V, --renew-anon-volumes flag

2 rm container and build

NestJS + Prisma + PostgreSQL ~ RLS multi-tenancy using nestjs-prisma, nestjs-cls and Prisma Client Extensions

Useful Links

Introducing DNV - Frictionless Node development with Docker Compose

- Open your the hosts file at `/etc/hosts` and add these lines at the bottom:

Build time difference between `--filter=service` and `--filter=service^...`

PLEASE NOTE THAT THE `compare.sh` BASH SCRIPT RUNS `docker system prune -f` TO ACCURATELY COMPARE BUILD TIMES

`--filter=workspace` : 2m35.339s

`--filter=workspace^...` : 1m34.768s