Run StepZen in Docker for Local Development

StepZen can be run locally using Docker for development purposes. Any recently released Docker version is supported. This works on Linux, macOS and Windows (both "natively" and in the Windows Subsystem for Linux a.k.a. WSL2).

Prerequisites

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

1. Start a local StepZen service instance using the StepZen CLI:

Copy
stepzen service start

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

2. To use the StepZen CLI for local development, you must log in by pointing the CLI to the local configuration:

Copy
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.

To switch back to the cloud StepZen service, log in with your stepzen.com account and admin key again

Copy
stepzen login

Using a custom database for metadata storage

The StepZen service itself is stateless, and needs a separate PostgreSQL database to store the metadata such as endpoints, backend connection details, etc. When running stepzen service start StepZen CLI automatically creates a local Docker container with a PostgreSQL database and uses it as a metadata storage. You can provide a custom database connection string to use a different metadata storage.

The example below shows how to create a new local PostgreSQL database with Docker and condifure the local StepZen service instance to use it.

1. To set up a new PostgreSQL database for your local StepZen service you can run the following Docker command:

Copy
docker run --name my-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.

2. After setting up the database that will be used to store the metadata of StepZen's service, start the service using the StepZen CLI:

Copy
stepzen service start --dsn postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/DATABASE_NAME

Troubleshooting

• The container running StepZen will use the port 9000. The CLI will throw an error when starting the service this port is already in use. If that happens, select a different port with the --port flag, e.g. stepzen service start --port 43526.