Skip to main content
Version: Next

Dockerize a Platformatic App

This guide explains how to create a new Platformatic DB app, which connects to a PostgreSQL database.

We will then create a docker-compose.yml file that will run both services in separate containers

Generate a Platformatic DB App

To start the Platformatic creator wizard, run the appropriate command for your package manager in your terminal:

npm create platformatic@latest

This interactive command-line tool will guide you through setting up a new Platformatic project. For this guide, please choose the following options:

- What kind of project do you want to create?   => Application
- Where would you like to create your project? => quick-start
- Which kind of project do you want to create? => @platformatic/db
- What is the name of the service? => (generated-randomly), e.g. legal-soup
- What is the connection string? => sqlite://./db.sqlite
- Do you want to create default migrations? => Yes
- Do you want to create another service? => No
- Do you want to use TypeScript? => No
- What port do you want to use? => 3042
- Do you want to init the git repository? => No

After completing the wizard, your Platformatic application will be ready in the quick-start folder. This includes example migration files, plugin scripts, routes, and tests within your service directory.


If the wizard does not handle dependency installation, ensure to run npm/yarn/pnpm install command manually:

Create Docker image for the Platformatic DB App

In this step you are going to create some files into the root project directory

  • .dockerignore - This file tells Docker to ignore some files when copying the directory into the image filesystem
  • - This is our entrypoint. We will run migrations then start platformatic

echo "Running migrations..." && \
npx platformatic db migrations apply && \
echo "Starting Platformatic App..." && \
npm start

Make sure you make this file executable with the command chmod +x

  • Dockerfile - This is the file Docker uses to create the image
FROM node:18-alpine
WORKDIR /usr/src/app
COPY . .
RUN npm install
COPY . .
CMD [ "./" ]

At this point you can build your Docker image with the command

$ docker build -t platformatic-app .

Create Docker Compose config file

docker-compose.yml is the configuration file for docker-compose which will spin up containers for both PostgresSQL and our Platformatic App

version: "3.3"
- "5433:5432"
image: "postgres:15-alpine"
- "3042:3042"
image: 'platformatic-app:latest'
- postgresql
- postgresql
DATABASE_URL: postgres://postgres:postgres@postgresql:5432/postgres

A couple of things to notice:

  • The Platformatic app is started only once the database container is up and running (depends_on).
  • The Platformatic app is linked with postgresql service. Meaning that inside its container ping postgresql will be resolved with the internal ip of the database container.
  • The environment is taken directly from the .env file created by the wizard

You can now run your containers with

$ docker-compose up # (-d if you want to send them in the background)

Everything should start smoothly, and you can access your app pointing your browser to

To stop the app you can either press CTRL-C if you are running them in the foreground, or, if you used the -d flag, run

$ docker-compose down