Run StepZen in Docker for Local Development

StepZen can be run on your local machine in Docker for development purposes

StepZen can be run locally using Docker for development purposes (any recently released GA Docker version is supported).


You must have Docker installed on your machine. We recommend using Docker Desktop or similar.

Also, you need to have the StepZen CLI installed. You can install the StepZen CLI, which requires you to have the Node.js runtime on your local machine.

Run the service

The StepZen service itself is stateless, and needs a separate PostgreSQL database to store the metadata such as such as endpoints, backend connection details, etc. We recommend PostgreSQL 14, but versions 12, 13, and 15 will also work. You can follow the command below to create a new local PostgreSQL database with Docker, or use your own PostgreSQL database.

  1. To set up a new PostgreSQL database for your local StepZen service you can run the following Docker command:
docker run --name stepzen-metadata -e POSTGRES_USER=YOUR_USERNAME -e POSTGRES_PASSWORD=YOUR_PASSWORD -p5432:5432 -d postgres:alpine

You need to replace YOUR_USERNAME and YOUR_PASSWORD with a username and password. As this setup is for local development, you could use stepzen and dbpassword as its values.

This command creates a PostgreSQL container with a fresh database listening for connections on your localhost port 5432, with the username and password you provided. The database name will be equal to the provided username.

  1. After setting up the database that will be used to store the metadata of StepZen's service, you can start the service using the StepZen CLI:
stepzen service start --dsn postgresql://YOUR_USERNAME:YOUR_PASSWORD@

NOTE: Use the IP address instead of localhost because this is the default IP address your localhost would have for connections from inside other Docker containers.

The StepZen service will now start in a Docker container, and a local configuration file ~/.stepzen/stepzen-config.local.yaml will be created.

  1. To use the StepZen CLI for local development, you must log in by pointing the CLI to the local configuration:
stepzen login --config ~/.stepzen/stepzen-config.local.yaml 

You can now use StepZen for local development and the CLI in the same way as when running StepZen in the cloud. For example, you can import a SQL or NoSQL Database, connect a REST or SOAP API, or federate graphs. To create a new StepZen project, please continue to the Getting Started section in the documentation.

Next steps

StepZen is deployed as a cloud service by default, and any StepZen GraphQL API you create locally using Docker can be deployed to the cloud. Next to this, StepZen can also be run in a private cloud or colocation data center.

You can find the terms of service for StepZen here.


  • We recommend fetching the Docker postgres:alpine container image periodically. Here is an example command to do this, but the best way to do it depends on your setup and platform. This pulls the public postgres:alpine image from the default image repository:
docker pull postgres:alpine
  • The container running StepZen will use the ports 8080, 8087, and 8088. The CLI will throw an error when starting the service if any of these ports are already in use.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.