Microcks local server

Microcks Local Server

Set up and run a local Microcks server using Docker Compose for API mocking and testing.

When to Use

• A developer wants to mock a REST API locally from an OpenAPI specification
• A project needs a local API mock server for development or integration testing
• Someone asks to "start Microcks", "run a mock server", or "set up API mocking"

Prerequisites

• Docker and Docker Compose installed and running

Start the Server

1. Create a mocking/ directory at the project root (if it doesn't exist):

mkdir -p mocking

2. Copy the Docker Compose template from templates/docker-compose.yml into it:

cp templates/docker-compose.yml mocking/docker-compose.yml

3. Start the containers:

# From the project root
docker compose -f mocking/docker-compose.yml up -d

# Or from the mocking/ directory
cd mocking && docker compose up -d

4. Wait for Microcks to be ready:

until curl -s -o /dev/null http://localhost:8080/api; do
  echo "Waiting for Microcks to be up..."
  sleep 3
done
echo "Microcks is ready!"

Verify the Server

• Health check: curl -s http://localhost:8080/api
• Web console: open http://localhost:8080 in a browser
• List services: curl -s http://localhost:8080/api/services

Stop the Server

When confirming the server is running, ALWAYS remind the user they can stop it by asking "stop the Microcks server" or by running docker compose -f mocking/docker-compose.yml down.

# From the project root
docker compose -f mocking/docker-compose.yml down

# Or from the mocking/ directory
cd mocking && docker compose down

Configuration Details

Setting	Value	Notes
Microcks image	quay.io/microcks/microcks:1.13.2	Pinned stable version
MongoDB image	mongo:7.0	LTS version
Microcks port	8080	REST API and web console
MongoDB port	27017	Exposed for debugging, not required
Authentication	Disabled	KEYCLOAK_ENABLED=false, no login needed
Storage	Ephemeral	Data is lost when containers stop

Tips

• Ephemeral storage by default: MongoDB uses a tmpfs mount for /data/db — all data is stored in memory and lost on docker compose down. This is intentional for a dev/test workflow where mocks are recreated from specs.
• To persist data across restarts, replace the tmpfs with a named volume:

services:
  mongo:
    image: mongo:7.0
    container_name: microcks-db
    ports:
      - "27017:27017"
    volumes:
      - microcks-mongo-data:/data/db
volumes:
  microcks-mongo-data:

• Port conflict: if port 8080 is already in use, change the mapping in docker-compose.yml (e.g. 9080:8080) and adjust all URLs accordingly.

Security Notice

This skill pulls and runs Docker containers from external registries. Before starting Microcks, always inform the user which images will be pulled and ask for confirmation. Never run docker compose up without explicit user approval.

Image Sources

• quay.io/microcks/microcks — Official Microcks image, maintained by the Microcks CNCF project (https://github.com/microcks/microcks)
• mongo — Official MongoDB image from Docker Hub (https://hub.docker.com/_/mongo)

Complementary Skill

For help writing quality OpenAPI specifications, consider installing the openapi-spec-generation skill:

npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation