Configure a repository for Spinnery

Before you start

Your repository needs a Docker Compose file that starts successfully. Keep build contexts, commands, health checks, ports, volumes, and same-repository dependencies in Compose. Spinnery reads that model; it does not replace it.

1. Create spinnery.yml

Put the file at the repository root. If your default Compose file is docker-compose.yml and you do not need a browser preview, this is the complete manifest:

version: 1
compose: {}

version must be the integer 1. compose is required; an empty mapping uses docker-compose.yml automatically.

2. Publish a browser preview

Name the Compose service and its container port. Enable HMR only when that development server supports it.

version: 1

compose:
  file: docker-compose.yml
  previews:
    - service: web
      port: 5173
      hmr: true

default_preview: web

• service must match a service from docker compose config --services.
• port is the application's container port, not a host-mapped port.
• A single preview becomes the default automatically; declare default_preview when there are several.

3. Connect services with inputs and outputs

Repositories stay independent. A provider publishes a named output; a consumer declares the same input and maps it to the environment variable its application already reads.

version: 1

compose:
  previews:
    - service: api
      port: 8080

default_preview: api

outputs:
  api_url:
    from: service.url

version: 1

compose:
  previews:
    - service: web
      port: 5173
      hmr: true

default_preview: web

inputs:
  api_url:
    required: true

environment:
  VITE_API_URL:
    from: input.api_url

Spinnery connects a same-name output automatically when only one selected service provides it. Use a project binding only to override or disambiguate that source. Never name another repository or add depends_on to spinnery.yml.

4. Validate before you merge

Validation is local and does not require login. It checks the manifest, resolves the Compose service list, verifies preview names, and catches undeclared input references.

spin validate
spin validate ./path/to/repository
spin validate ./spinnery.yml --json

Docker Compose v2 is required. A nonzero exit means the repository is not ready for workspace creation.

Next steps