v1 → v2 migration

What changed

The v1 build flow built a Docker image locally, tagged it as docker.${connectionConfig.domain}/grotte/custom-envs/<id>:<build>, and pushed it to a Docker registry hosted at the same domain (docker.grotte.parallactic.fr).

That registry is not provisioned on the GROTTE Scaleway deployment. The orchestrator builds layers internally from the steps you describe — no external image registry is involved. v1 invocations died with an unhelpful DNS error after running through docker login + docker build:

dial tcp: lookup docker.grotte.parallactic.fr: no such host

CLI 0.1.5 short-circuits before that DNS lookup so you get a usable signal instead.

Three ways to build a template now

1 · Dashboard (recommended)

The fastest path. Navigate to Templates → New template in the dashboard, paste your Dockerfile (or upload a build manifest), pick CPU + memory, and start the build. Logs stream into the page.

This route reads a build-manifest.json and forwards to the API's POST /v2/templates/{id}/builds/{id} for you. No CLI needed.

2 · CLI v2

For local-Dockerfile workflows, the supported command is now grotte template create:

# Build a template named "my-env" from ./grotte.Dockerfile
grotte template create my-env
 
# Or point at a specific Dockerfile + start command
grotte template create my-env \
  --dockerfile ./Dockerfile.dev \
  --cmd "node server.js" \
  --cpu-count 2 \
  --memory-mb 1024

Template names must match [a-z0-9-_]+. --memory-mb must be even.

3 · Direct API

For scripted / operator builds, hit the API directly with an X-API-Key header. Two calls — register, then start:

# Register
curl -X POST https://api.grotte.parallactic.fr/v3/templates \
  -H "X-API-Key: $GROTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias":"my-env","cpuCount":2,"memoryMB":1024}'
 
# Start the build (id + buildId from the response above)
curl -X POST \
  https://api.grotte.parallactic.fr/v2/templates/$TEMPLATE_ID/builds/$BUILD_ID \
  -H "X-API-Key: $GROTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{"type":"FROM","args":["python:3.11"]}]}'

The orchestrator unpacks steps (FROM, RUN, ENV, USER, COPY) into internal layers — same primitives as a Dockerfile, just transmitted as JSON instead of staged through a registry.

Side by side

Already have a grotte.toml + Dockerfile?

Run the migration helper — it converts your grotte.toml config and Dockerfile to the new template SDK format:

grotte template migrate

You can also pass --dockerfile and -l <python|typescript> to control inputs and the generated example language. See grotte template migrate --help.

Self-hosted GROTTE with your own registry?

The v1 flow stays available for self-hosted deployments that wire up their own Docker registry. Set GROTTE_IMAGE_URI_MASK to your registry's URL mask before invoking grotte template build and the v1 short-circuit is bypassed:

export GROTTE_IMAGE_URI_MASK="myregistry.example.com/grotte/{templateID}:{buildID}"
grotte template build

The {templateID} and {buildID} placeholders are interpolated by the CLI.

Related

• Defining a template — Dockerfile structure and what the v2 build accepts.
• Build authentication error — fixing docker login failures on legacy v1 invocations.
• Support — where to get help.