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).
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
- Start a local StepZen service instance using the StepZen CLI:
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.
- 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.
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
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.
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.
- To set up a new PostgreSQL database for your local StepZen service you can run the following Docker command:
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_PASSWORDwith a username and password. As this setup is for local development, you could use
dbpasswordas 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.
- After setting up the database that will be used to store the metadata of StepZen's service, start the service using the StepZen CLI:
stepzen service start --dsn postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/YOUR_USERNAME
- 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
stepzen service start --port 43526.