Using Docker for local API development

API Connect Essentials can be run on your local machine in Docker for development purposes.

Before you begin

You must have Docker installed on your machine; for example, Docker Desktop or similar.
You must have the API Connect for GraphQL CLI installed. See Setting up your environment for instructions on installing the CLI.

About this task

API Connect Essentials 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 (known as WSL2).

Attention: The container running API Connect Essentials uses port 9000 by default. 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; for example:

stepzen service start --port 43526

Procedure

Run the service.
1. Start a local API Connect for GraphQL service instance using the API Connect for GraphQL CLI:
```
stepzen service start
```
  The API Connect for GraphQL starts in a Docker container, and a local configuration file called ~/.stepzen/stepzen-config.local.yaml is created.
2. Log in to API Connect for GraphQL by pointing the CLI to the local configuration:
```
stepzen login --config ~/.stepzen/stepzen-config.local.yaml 
```
(Optional) Configure a custom database for metadata storage.

The API Connect for GraphQL service itself is stateless, and needs a separate PostgreSQL database to store metadata such as endpoints and backend connection details.

When running stepzen service start, the API Connect for GraphQL CLI automatically creates a local Docker container with a PostgreSQL database and uses it as metadata storage. You can optionally use a different metadata storage by providing a custom database connection string.

The following example shows how to create a new local PostgreSQL database with Docker and then configure the local API Connect for GraphQL service instance to use it.
1. Run the following Docker command to create a PostgreSQL container with a new database:
```
docker run --name my-stepzen-metadata -e POSTGRES_USER=YOUR_USERNAME -e POSTGRES_PASSWORD=YOUR_PASSWORD -p5432:5432 -d postgres:alpine
```
  Replace YOUR_USERNAME and YOUR_PASSWORD with a user name and password. The user name is also used as the database name.
  
  The command creates a PostgreSQL container with a new database listening for connections on your localhost port 5432, with the user name and password that you provided.
2. Run the following command to start the local service using the API Connect for GraphQL CLI:
```
stepzen service start --dsn postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/YOUR_USERNAME
```