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.
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.
- 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_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, you can start the service using the StepZen CLI:
stepzen service start --dsn postgresql://YOUR_USERNAME:YOUR_PASSWORD@172.17.0.1:5432/YOUR_USERNAME
NOTE: Use the IP address
localhostbecause 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.
- 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.
- We recommend fetching the Docker
postgres:alpinecontainer 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:alpineimage from the default image repository:
docker pull postgres:alpine
- The container running StepZen will use the ports
8088. The CLI will throw an error when starting the service if any of these ports are already in use.