Docker

This guide walks you through setting up a Prisma ORM application within a Docker environment. You'll learn how to configure a Node.js project, integrate Prisma for database management, and orchestrate the application using Docker Compose. By the end, you'll have a fully functional Prisma application running in a Docker container.

• Docker and Docker Compose installed
• Node.js version: A compatible Node.js version, required for Prisma 7.

See our system requirements for all minimum version requirements.

Before starting, ensure that no PostgreSQL services are running locally, and that the following ports are free to avoid conflicts: 5432 (PostgreSQL), 3000 (application server) or 5555 (Prisma Studio server).

To stop existing PostgreSQL services, use:

sudo systemctl stop postgresql  # Linux

brew services stop postgresql   # macOS

net stop postgresql             # Windows (Run as Administrator)

To stop all running Docker containers and free up ports:

docker ps -q | xargs docker stop

Start by creating a small Node.js application with Prisma ORM and Express.js.

First, create a new project directory and initialize a Node.js project:

mkdir docker-test

cd docker-test

bun init

mkdir docker-test
cd docker-test
pnpm init

mkdir docker-test
cd docker-test
yarn init

mkdir docker-test
cd docker-test
npm init

This will generate a package.json file:

{

  "name": "docker-test",

  "version": "1.0.0",

  "description": "",

  "main": "index.js",

  "scripts": {},

  "keywords": [],

  "author": "",

  "license": "ISC"

}

Next, install the Prisma CLI as a development dependency and Express.js for the server:

bun add prisma@prev @types/pg --dev

pnpm add prisma@prev @types/pg --save-dev

yarn add prisma@prev @types/pg --dev

npm install prisma@prev @types/pg --save-dev

bun add @prisma/client@7 @prisma/adapter-pg pg dotenv express

pnpm add @prisma/client@7 @prisma/adapter-pg pg dotenv express

yarn add @prisma/client@7 @prisma/adapter-pg pg dotenv express

npm install @prisma/client@7 @prisma/adapter-pg pg dotenv express

Now, initialize Prisma to generate the necessary files:

bunx --bun prisma init --output ../generated/prisma_client

pnpm prisma init --output ../generated/prisma_client

yarn prisma init --output ../generated/prisma_client

npx prisma init --output ../generated/prisma_client

This creates:

• A prisma folder containing schema.prisma, where you will define your database schema.
• An .env file in the project root, which stores environment variables.

Add a User model to the schema.prisma file located in the prisma/schema.prisma folder:

datasource db {

  provider = "postgresql"

}

generator client {

  provider = "prisma-client"

  output = "../generated/prisma_client"

}

model User { 

  id        Int      @id @default(autoincrement()) 

  createdAt DateTime @default(now()) 

  email     String   @unique

  name      String?

} 

Now, create a prisma.config.ts file in the root of your project:

import "dotenv/config";

import { defineConfig, env } from "prisma/config";

export default defineConfig({

  schema: "prisma/schema.prisma",

  migrations: {

    path: "prisma/migrations",

  },

  datasource: {

    url: env("DATABASE_URL"),

  },

});

With the Prisma schema in place, create an Express.js server to interact with the database. Start by creating an index.js file:

touch index.js

Add the following code to set up a basic Express server:

const express = require("express"); 

const { PrismaClient } = require("./generated/prisma_client/client"); 

const { PrismaPg } = require("@prisma/adapter-pg"); 

const adapter = new PrismaPg({

  connectionString: process.env.DATABASE_URL, 

}); 

const app = express(); 

const prisma = new PrismaClient({

  adapter, 

}); 

app.use(express.json()); 

// Get all users

app.get("/", async (req, res) => {

  const userCount = await prisma.user.count(); 

  res.json(

    userCount == 0

      ? "No users have been added yet."

      : "Some users have been added to the database.", 

  ); 

}); 

const PORT = 3000; 

app.listen(PORT, () => {

  console.log(`Server is running on http://localhost:${PORT}`); 

}); 

Update the package.json scripts to include commands for running the server and deploying migrations:

"scripts": {

  "test": "echo \"Error: no test specified\" && exit 1", 

  "dev": "node index.js", 

  "db:deploy": "npx prisma migrate deploy && npx prisma generate"

}

With the application set up, the next step is to configure a PostgreSQL database using Docker Compose.

To perform database migrations, we'll create a standalone PostgreSQL database using Docker Compose.

Create a docker-compose.postgres.yml file in the root directory:

version: '3.7'services:   postgres:     image: postgres:15    restart: always    environment:       - POSTGRES_DB=postgres      - POSTGRES_USER=postgres      - POSTGRES_PASSWORD=prisma    ports:       - "5432:5432"    networks:       - prisma-network    healthcheck:       test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]       interval: 5s      timeout: 2s      retries: 20    volumes:       - postgres_data:/var/lib/postgresql/data    command: postgres -c listen_addresses='*'    logging:       options:         max-size: "10m"        max-file: "3"networks:   prisma-network: volumes:   postgres_data: 

Run the following command to start the database:

docker compose -f docker-compose.postgres.yml up -d

With the database running, update the .env file with the following database connection url:

DATABASE_URL="postgresql://postgres:prisma@localhost:5432/postgres?schema=public"

Run the migration to create the database schema:

bunx prisma migrate dev --name init

pnpm prisma generate

yarn prisma generate

npx prisma generate

Then generate Prisma Client:

bunx prisma generate

pnpm run dev

yarn dev

npm run dev

No users have been added yet.

This should generate a migrations folder in the prisma folder and the Prisma Client in the generated/prisma_client directory.

Start the server and verify it works:

bun run dev

Visit http://localhost:3000 to see the message:

No users have been added yet.

Stop the local server.

Once testing is complete, remove the standalone PostgreSQL container:

docker compose -f docker-compose.postgres.yml down --remove-orphans

This command will:

• Stop running containers.
• Remove containers.
• Remove the default network created by Docker Compose.
• Remove associated volumes (if not named explicitly).

With the application tested locally, the next step is to containerize it with Docker.

Containerizing the application means it runs the same way on any host that has Docker installed.

To do that create a Dockerfile in project root:

touch Dockerfile

For the next step, you'll need to choose between two options for the base image: node:alpine (lightweight) or node:slim (stable). Both options are fully supported by Prisma ORM, but may have to be configured differently.

The node:alpine image is based on Alpine Linux, a lightweight Linux distribution that uses the musl C standard library. Choose it if you want a small container image. Prisma supports Alpine on amd64 out of the box, and supports it on arm64 since prisma@4.10.0.

Add the following content to the Dockerfile:

FROM node:lts-alpine3.17

WORKDIR /usr/src/app

COPY package.json package-lock.json ./

RUN npm ci

COPY . .

CMD ["sh", "-c", "npm run db:deploy && npm run dev"]

Related Docker images:

• node:lts-alpine
• node:16-alpine
• node:14-alpine

The node:slim image is based on Linux Debian, a stable and widely supported distribution that uses the glibc C standard library. It is mostly supported out of the box on amd64 and arm64, making it a good choice if you're running into compatibility issues with Alpine or need a more production-ready environment. However, some older versions of this image may come without libssl installed, so it's sometimes necessary to install it manually.

Add the following content to the Dockerfile:

FROM node:slim

RUN apt-get update -y \

&& apt-get install -y openssl

WORKDIR /usr/src/app

COPY package.json package-lock.json ./

RUN npm ci

COPY . .

CMD ["sh", "-c", "npm run db:deploy && npm run dev"]

Related Docker images:

• node:lts-slim
• node:bullseye-slim
• node:buster-slim
• node:stretch-slim

With the Dockerfile ready, use Docker Compose to manage the app and the database together, so you can start and stop both with one command.

Create a docker-compose.yml file in your project folder:

touch docker-compose.yml

Add the following configuration to the file:

version: '3.7'services:   postgres_db:     image: postgres:15    hostname: postgres_db    container_name: postgres_db    restart: always    environment:       POSTGRES_DB: postgres      POSTGRES_USER: postgres      POSTGRES_PASSWORD: prisma    ports:       - '5432:5432'    networks:       - prisma-network    healthcheck:       test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]       interval: 5s      timeout: 2s      retries: 20  server:     build:       context: .      dockerfile: Dockerfile    ports:       - '3000:3000'    stdin_open: true    tty: true  # Keeps the container running for debugging    depends_on:       postgres_db:         condition: service_healthy    env_file:       - .env.prod    networks:       - prisma-networknetworks:   prisma-network:     name: prisma-network

Before running the app, we need to configure the environment variables. Create a .env.prod file:

touch .env.prod

Add the following database connection url to the .env.prod file:

DATABASE_URL="postgresql://postgres:prisma@postgres_db:5432/postgres?schema=public"

Build and run the app using Docker Compose:

docker compose -f docker-compose.yml up --build -d

Visit http://localhost:3000 to see your app running with the message:

No users have been added yet.

Prisma Studio offers a graphical user interface (GUI) that allows you to view and manage your database directly in the browser. It is useful for inspecting and editing data during development.

To add Prisma Studio to your Docker setup, update the docker-compose.yml file:

version: '3.7'services:  postgres_db:    image: postgres:15    hostname: postgres_db    container_name: postgres_db    restart: always    environment:      POSTGRES_DB: postgres      POSTGRES_USER: postgres      POSTGRES_PASSWORD: prisma    ports:      - '5432:5432'    networks:      - prisma-network    healthcheck:      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]      interval: 5s      timeout: 2s      retries: 20  server:    build:      context: .      dockerfile: Dockerfile    ports:      - '3000:3000'    stdin_open: true    tty: true  # Keeps the container running for debugging    depends_on:      postgres_db:        condition: service_healthy    env_file:      - .env.prod    networks:      - prisma-network  prisma-studio:     image: node:lts-alpine3.17    working_dir: /usr/src/app    volumes:       - .:/usr/src/app    command: npx prisma studio --port 5555 --browser none    ports:       - "5555:5555"    env_file:       - .env.prod    networks:       - prisma-network    depends_on:       postgres_db:         condition: service_healthy      server:         condition: service_startednetworks:  prisma-network:    name: prisma-network

This will start Prisma Studio at http://localhost:5555 alongside the main app at http://localhost:3000. You can use Prisma Studio to manage your database with a GUI.

Run the following command to start everything:

docker compose -f docker-compose.yml up --build -d

Your Prisma app and database now run together under Docker Compose.