For the complete documentation index, see llms.txt.
Skip to main content

Docker Compose

Learn how to run reShapr locally using Docker Compose for development and testing purposes.

Watch the setup

The 11-second local Docker demo previews the startup flow. Use this guide for version-pinned commands and verification.

Prerequisites​

Before you begin, make sure you have the following installed on your machine:

  • Docker with Docker Compose v2, or Podman with Compose support
  • Node.js 20 or later, required by the reShapr CLI
  • The reShapr CLI installed globally:
npm install -g @reshapr/reshapr-cli --allow-scripts=@scarf/scarf

Quick start with the CLI​

The simplest way to run reShapr locally is through reshapr run. Pin the release so the downloaded Compose file, container images, and this guide use the same version:

reshapr run --release 1.0.0

The CLI downloads the release-owned docker-compose-all-in-one.yml, updates its reShapr image tags to 1.0.0, caches it under ~/.reshapr/, and starts the stack in the background.

Without --release, the CLI resolves latest through GitHub Releases. Use an explicit release for a reproducible environment. Use nightly only when you deliberately want artifacts from the main branch:

reshapr run --release nightly

The CLI auto-detects Docker or Podman. To select one explicitly, use --engine:

reshapr run --release 1.0.0 --engine podman

Add the optional Web UI with --ui:

reshapr run --release 1.0.0 --ui

The Web UI addon is downloaded from the same release and becomes available at http://localhost:3333. The compose files are cached at ~/.reshapr/docker-compose-<release>.yml and ~/.reshapr/docker-compose-ui-addon-<release>.yml.

Check status​

Once the containers are running, verify their status:

reshapr status

The output identifies the selected release and container engine, then reports the Compose service status. Names and timestamps depend on your local engine and are not stable identifiers.

The control plane is available at http://localhost:5555 and the MCP proxy at http://localhost:7777.

Log in with the CLI​

With your user created, authenticate the CLI against your local control plane:

reshapr login --server http://localhost:5555

You'll be prompted for your username and password. Once authenticated:

info

The default username is admin, and the default password is password.

reshapr login --server http://localhost:5555
ℹī¸  Enter your credentials
✅ Login successful!
ℹī¸  Welcome, admin!
ℹī¸  Organization: reshapr
✅ Configuration saved to /Users/you/.reshapr/config

From here, follow Your First MCP Endpoint, End to End to import a versioned API contract, expose it, and call a Tool through the local proxy.

Stop the containers​

When you're done, shut everything down:

reshapr stop

This runs the selected engine's Compose down command on every saved compose file, including the Web UI addon when enabled, and cleans up the run state.

Manual setup (without the CLI)​

If you prefer to manage Docker Compose directly, check out the same release used by this guide:

git clone --branch 1.0.0 --depth 1 https://github.com/reshaprio/reshapr.git
cd reshapr

Start all services (control plane, proxy, and database) at once:

docker compose -f install/docker-compose-all-in-one.yml up -d

To include the Web UI, compose the addon with the base file:

docker compose -f install/docker-compose-all-in-one.yml \
  -f install/docker-compose-ui-addon.yml up -d

With Podman, replace docker compose with podman compose in these commands.

podman compose -f install/docker-compose-all-in-one.yml up -d
docker compose -f install/docker-compose-all-in-one.yml down

Result​

reshapr status reports the Compose services as running, the control plane responds at http://localhost:5555, and the proxy accepts MCP requests at http://localhost:7777.

Limits​

  • This topology is intended for local development and testing, not production availability or durability.
  • Local credentials and ports in this guide use the release defaults; change them before exposing the stack beyond your machine.
  • Stopping the stack does not remove its named volumes. Manage local data lifecycle with your container engine.

Next step​

Agent View