@metabase/rde 0.1.10 → 0.1.12

package/README.md

@@ -41,10 +41,10 @@ The wizard shows its checklist first (`✓` done, `○` to do, `–` not applica
 – Connect a git repository
 ○ Summary
 │
-●  Running npm install -g @metabase/cli@alpha-fix-transform-test-ee-path
+●  Running npm install -g @metabase/cli@alpha-release-65-integration-branch
 ```
 
-The steps up to the license run without a question, save one: `mb` is installed with the package manager that installed `rde`, the skill goes to the coding agents you pick from the ones found on the machine (at a terminal; without one, to every agent found), Metabase runs in Docker when Docker is there (the jar with your Java otherwise), on the first free port from 3100 up, with an admin user whose password is generated and kept in `~/.rde`, `mb` is logged in under its `default` profile (the one question here comes when `default` already points at another Metabase), and a Postgres sample database comes up in a second container, connected to Metabase as a place transforms can write. Each of those choices is printed as it is made and can be overridden with a flag. The prompts that remain are the license token (Enter skips it), a connection string for your own database (Enter skips it), and, with a license that includes remote sync, where the git repository lives and which remote it uses.
+The steps up to the license run without a question, save one: `mb` is installed with the package manager that installed `rde`, the skill goes to the coding agents you pick from the ones found on the machine (at a terminal; without one, to every agent found), Metabase runs in Docker when Docker is there (the jar with your Java otherwise), on the first free port from 23000 up that no other container or instance claims, with an admin user whose password is generated and kept in `~/.rde`, `mb` is logged in under its `default` profile (the one question here comes when `default` already points at another Metabase), and a Postgres sample database comes up in a second container, connected to Metabase as a place transforms can write. Each of those choices is printed as it is made and can be overridden with a flag. The prompts that remain are the license token (Enter skips it), a connection string for your own database (Enter skips it), and, with a license that includes remote sync, where the git repository lives and which remote it uses.
 
 The databases step asks once. At a terminal, without `--yes` or `--skip-databases`, and while none of your own databases is connected, it lists what is connected (the sample database) and asks for a connection string: paste one and `rde` reads the engine from it (or asks which, when the string fits several, or shows the engine list when it fits none), then shows the connection for review, tests it, adds it, and offers another. Enter skips it, and the skip is remembered, so the next `rde init` does not ask again; `rde init --only databases` and `rde db add` still do. With `--yes` or without a terminal it asks nothing and the sample database stands in; `--database` connects yours ahead of time.
 
@@ -53,13 +53,13 @@ The git step reads `–` until a license with remote sync is active; it is check
 | Step | What it does |
 | --- | --- |
 | Check this machine | Platform, Node version, git, and a reachable Docker daemon or a Java 21+ runtime |
-| Install the Metabase CLI | `@metabase/cli` (`mb`) at the `alpha-fix-transform-test-ee-path` dist-tag, with the package manager that installed `rde` |
+| Install the Metabase CLI | `@metabase/cli` (`mb`) at the `alpha-release-65-integration-branch` dist-tag, with the package manager that installed `rde` |
 | Install the rde and data-app skills | The data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`) from `metabase/metabase/skills#master`, then the `rde` and `rde-data-apps` skills from the `main` branch of `metabase/agent-skills` (the rde skill hands an explicit app request to `rde-data-apps`, which hands the build to the data-app skills), for the coding agents you pick at a terminal, from the ones found on this machine (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf). When none is found, the step is skipped and says how to add the skills once an agent is installed; `rde` installs no agent. Without a terminal, or with `--yes`, every agent found gets the skills; `--agents` picks a set ahead of time (the skills are installed for them whether or not they are on the machine yet), `--skip-agents` none; `RDE_SKILL_SOURCE` installs the two rde skills from another URL or a local checkout of `metabase/agent-skills` |
-| Install Metabase | **Docker** when it is available: pulls `metabase/metabase-enterprise-head:latest` (or `--image`) and creates the container. **Jar** otherwise, or with `--runtime jar`: downloads the latest enterprise release (or the tag or `.jar` path given as `--jar`) into `~/.rde/jars/` and runs it with your Java. Either way on port 3100, or the first free port above it, or `--port` |
+| Install Metabase | **Docker** when it is available: pulls `metabase/metabase-enterprise-head:latest` (or `--image`) and creates the container. **Jar** otherwise, or with `--runtime jar`: downloads the latest enterprise release (or the tag or `.jar` path given as `--jar`) into `~/.rde/jars/` and runs it with your Java. Either way on port 23000, or the first free port above it that nothing else claims, or `--port` |
 | Start Metabase | Starts the container or the jar and waits for `/api/health`, showing Metabase's own progress |
 | Create the admin user | `admin@metabase.local` with a generated password that `rde credentials` shows, or your own with `--admin prompted`, see [Credentials](#credentials) |
 | Connect the Metabase CLI | Creates an API key named `rde` and logs `mb` in with it under the profile `default`, so plain `mb` uses the instance; when `default` already points at another Metabase it asks first, see [The `mb` profile](#the-mb-profile); a key Metabase rejects is replaced |
-| Connect a sample database | Runs Metabase's Postgres sample data (`metabase/qa-databases:postgres-sample-15`) in a container named `rde-sampledb-default` on the first free port from 15432 (or one Docker picks, when another program or a concurrent `rde init` takes that port first), connects it as `Sample Database`, and switches transforms on. It replaces the H2 sample database Metabase would otherwise bundle, which cannot be a transform target. Needs Docker, so a jar instance on a machine without Docker keeps the H2 one instead |
+| Connect a sample database | Runs Metabase's Postgres sample data (`metabase/qa-databases:postgres-sample-15`) in a container named `rde-sampledb-default` on the first free port from 25432 (or one Docker picks, when another program or a concurrent `rde init` takes that port first), connects it as `Sample Database`, and switches transforms on. It replaces the H2 sample database Metabase would otherwise bundle, which cannot be a transform target. Needs Docker, so a jar instance on a machine without Docker keeps the H2 one instead |
 | Activate your license | Optional. Paste a token, or press Enter to skip; remote sync needs one with the `remote-sync` feature |
 | Connect your databases | At a terminal, until you connect one of your own or skip it: paste a connection string (Enter skips), review, test, add; repeat. `--database` names them ahead of time; with `--yes` or without a terminal nothing is asked. `rde db add` starts from the engine list, where the fields can also be filled one by one |
 | Connect a git repository | Only with a license. Initializes or reuses a repository and points Metabase's remote sync at it |
@@ -84,13 +84,13 @@ The second run on the same machine detects every step as done and prints the sum
 │
 ◇  Your environment ─────────────────────────────────────────────────────────────────╮
 │                                                                                    │
-│  Metabase: http://localhost:3100                                                   │
+│  Metabase: http://localhost:23000                                                  │
 │  Login: admin@metabase.local (rde credentials shows the password)                  │
 │  Metabase CLI: mb <command>                                                        │
 │  Databases:                                                                        │
 │    Sample Database (postgres, sync complete)                                       │
 │    warehouse (postgres, syncing; `rde status` shows when it finishes)              │
-│  Sample database: psql "postgres://metabase:metasample123@localhost:15432/sample"  │
+│  Sample database: psql "postgres://metabase:metasample123@localhost:25432/sample"  │
 │  Remote sync: not configured (no license)                                          │
 │  rde skill: installed for Claude Code                                              │
 │  Start working:                                                                    │
@@ -102,14 +102,14 @@ The second run on the same machine detects every step as done and prints the sum
 └  rde init finished
 ```
 
-Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. A step that fails ends the run with exit code 1 (2 for a missing answer) and a last line naming the step and the command that resumes there: `rde init stopped at "Connect a sample database": <reason>. Resume with rde init --from sample-database.` `rde init --from license` re-runs from a step on (a later step that does not apply, such as the git step without a license that has remote sync, stays skipped), `rde init --only databases` runs one step.
+Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. A run on an instance that already exists says so first (`Resuming instance "default" (Metabase http://localhost:23000, repository /Users/you/rde-content); steps already done are skipped.`, and that `rde uninstall` comes first to start over). A flag or answers-file section for a step that does not run, because it is already done, does not apply (a license skipped before), or is left out by `--only`, is ignored with a warning naming the flag and the step and how to get it done instead: `--database ignored: "Connect your databases" is already done. Connect another with rde db add --url <connection string>.` A skip flag for a step that is already done asks nothing of it and is not warned about. A step that fails ends the run with exit code 1 (2 for a missing answer) and a last line naming the step and the command that resumes there: `rde init stopped at "Connect a sample database": <reason>. Resume with rde init --from sample-database.` `rde init --from license` re-runs from a step on (a later step that does not apply, such as the git step without a license that has remote sync, stays skipped), `rde init --only databases` runs one step.
 
 ## The sample database
 
-Every instance gets a second container, `rde-sampledb-default`, running `metabase/qa-databases:postgres-sample-15`: the Postgres edition of Metabase's own sample data, the same tables and rows the bundled H2 sample database has (`orders`, `products`, `people`, `reviews`, `accounts`, `invoices`, `feedback`, `analytic_events`), with the user `metabase`, the password `metasample123`, and the database `sample`. `init` publishes it on `127.0.0.1` at the first free port from 15432 up (5432 is usually your own Postgres), connects it to Metabase as `Sample Database`, and sets `transforms-enabled`, so transforms have somewhere to write on the first run: the H2 sample database refuses to be a transform target, this one creates the target schema on demand. The `metabase` user is the cluster superuser, so any schema name works. Metabase is started with `MB_LOAD_SAMPLE_CONTENT=false`, so the H2 sample database and the example content built on it are never created and the Postgres one is the only `Sample Database`.
+Every instance gets a second container, `rde-sampledb-default`, running `metabase/qa-databases:postgres-sample-15`: the Postgres edition of Metabase's own sample data, the same tables and rows the bundled H2 sample database has (`orders`, `products`, `people`, `reviews`, `accounts`, `invoices`, `feedback`, `analytic_events`), with the user `metabase`, the password `metasample123`, and the database `sample`. `init` publishes it on `127.0.0.1` at the first free port from 25432 up (5432 is usually your own Postgres, and 15432 a common stand-in for it), connects it to Metabase as `Sample Database`, and sets `transforms-enabled`, so transforms have somewhere to write on the first run: the H2 sample database refuses to be a transform target, this one creates the target schema on demand. The `metabase` user is the cluster superuser, so any schema name works. Metabase is started with `MB_LOAD_SAMPLE_CONTENT=false`, so the H2 sample database and the example content built on it are never created and the Postgres one is the only `Sample Database`.
 
 ```sh
-psql "postgres://metabase:metasample123@localhost:15432/sample"   # the summary and `rde status` show the port
+psql "postgres://metabase:metasample123@localhost:25432/sample"   # the summary and `rde status` show the port
 ```
 
 `rde start` and `rde stop` bring the container up and down with Metabase, `rde status` shows its state and sync, `rde doctor` checks it, and `rde uninstall` removes it (with `--remove-image`, its image too). The data lives inside the container: `stop`/`start` keep it, and a container that is removed comes back with the pristine sample data on the next `rde init`. The jar runtime gets the sample database as well whenever Docker is available; on a machine without Docker the step is `–` and there is no sample database at all (the H2 one is switched off for every instance).
@@ -161,7 +161,7 @@ Docker is used whenever it is available: the image is self-contained, and the co
 
 | Command | What it does |
 | --- | --- |
-| `rde start` | Starts the sample database and the instance, and waits until Metabase is healthy |
+| `rde start` | Starts the sample database and the instance, and waits until Metabase is healthy; `--port <n>` moves the instance to another port first (see [The instance's port is taken](#troubleshooting)) |
 | `rde stop` | Stops both; the data stays |
 | `rde status` | The login email, the `mb` profile, the init checklist, whether setup is complete (or the first step `init` did not finish, with the `rde init --from` command that resumes there), runtime state, health, databases with their sync state, the sample database's container and connection string, remote sync state and the content repository's working directory (`contentRepository`); `--json` for scripts and agents (`mbProfile`, `adminEmail`, `setup`, never a secret); exit 0 whatever it reports |
 | `rde credentials` | The Metabase URL, admin email, and password; `--json` for scripts and agents; `--api-key` for the API key alone |
@@ -213,17 +213,17 @@ Every prompt can be answered ahead of time, by a flag or by a JSON answers file,
 
 ```sh
 rde init --skip-license \
-         --database "postgres=postgres://user:pass@localhost:5432/app" \
+         --database "postgres://user:pass@localhost:5432/app" \
          --git-dir ~/analytics --git-remote local
 ```
 
 | Flag | Answers |
 | --- | --- |
 | `--agents claude-code,codex` / `--skip-agents` | Which agents get the skill, instead of asking at a terminal or taking the ones found on the machine |
-| `--runtime docker\|jar`, `--image`, `--jar`, `--port` | How Metabase runs, the Docker image or the jar (`latest`, a release tag, or a `.jar` path), and the host port, instead of Docker when available, `metabase/metabase-enterprise-head:latest`, the latest release, and the first free port from 3100; `--image` implies `docker` and `--jar` implies `jar`; the sample database always runs in Docker |
+| `--runtime docker\|jar`, `--image`, `--jar`, `--port` | How Metabase runs, the Docker image or the jar (`latest`, a release tag, or a `.jar` path), and the host port, instead of Docker when available, `metabase/metabase-enterprise-head:latest`, the latest release, and the first free port from 23000 that nothing else claims; `--image` implies `docker` and `--jar` implies `jar`; the sample database always runs in Docker |
 | `--admin generated\|prompted`, `--admin-email`, `--admin-password` | The admin user, `generated` unless given; an email or password implies `prompted` |
 | `--license-token` / `--skip-license` | The license |
-| `--database <engine>=<connection string>` (repeatable) / `--skip-databases` | Your own databases; `--skip-databases` connects none of them, and the sample database is still connected |
+| `--database <connection string>` (repeatable) / `--skip-databases` | Your own databases, the engine read from the string; `<engine>=<connection string>` names it when the string fits several (`druid=jdbc:avatica:…`); `--skip-databases` connects none of them, and the sample database is still connected |
 | `--git-dir`, `--git-remote local\|hosted`, `--git-url`, `--git-token` / `--skip-git` | The content repository; a remote or URL without `--git-dir` means the current directory |
 | `--mb-profile default\|rde` | The `mb` profile when `default` already points at another Metabase; `default` (replace it) unless given |
 | `--yes` | Every confirmation, and the recommended choice of a question (replacing `default`); skips the question about your own databases, and the sample database is still connected. A driver's toggle (SSL, an SSH tunnel) is a setting, not a confirmation, and keeps the driver's default |
@@ -296,7 +296,7 @@ Start with `rde doctor`. It checks the machine (platform, Node, git, Docker, Jav
 
 ```
 ✓ container    rde-metabase-default stopped (metabase/metabase-enterprise-head:latest)
-✓ port         3100 is free
+✓ port         23000 is free
 ✗ health       unreachable
                → `rde start`
 – admin user   Metabase is not healthy
@@ -325,9 +325,11 @@ Fix the items above and run rde init again
 
 Start Docker (or `colima start`), or install Java, and run `rde init` again. `rde start` and `rde status` report the same condition on an existing instance. An instance that was set up with Docker keeps needing Docker: `rde doctor` marks it ✗ then, whatever Java is there.
 
-**The instance is not on port 3100.** The runtime step takes the first free port from 3100 up and says so: `Port 3100 is in use; using 3101`. 3100 rather than 3000 because a Metabase checkout's dev server, and most other local tools, sit on 3000 and its neighbours. `rde status` and the summary show the URL; `--port` pins a port of your choice and refuses a busy one. A container that exists with a different port or image is reported with the `docker rm -f` command that clears it.
+**The instance is not on port 23000.** The runtime step takes the first free port from 23000 up and says so: `Port 23000 is in use or claimed; using 23001`. rde's ports are the standard ones plus 20000 (Metabase's 3000, Postgres's 5432), a block no common local tool uses and that Docker and the kernel never pick from on their own. A port counts as claimed when any Docker container, running or stopped, from this rde home or another, is created to publish it, or when another instance of this home uses it, because that container or instance takes it back the moment it starts. `rde status` and the summary show the URL; `--port` pins a port of your choice and refuses a busy or claimed one, naming who claims it. A container that exists with a different port or image is reported with the `docker rm -f` command that clears it.
 
-**The sample database is not on port 15432.** The same rule: `Port 15432 is in use; using 15433 for the sample database`. The summary, `rde status`, and the `psql` line carry the port that was taken, and Metabase's connection uses it too. A sample database container that was removed by hand comes back on the next `rde init` (`rde doctor` points at it); if another program took its port meanwhile, it moves to the next free one and `init` says which Metabase database still points at the old port.
+**The sample database is not on port 25432.** The same rule: `Port 25432 is in use or claimed; using 25433 for the sample database`. The summary, `rde status`, and the `psql` line carry the port that was taken, and Metabase's connection uses it too. A sample database container that was removed by hand comes back on the next `rde init` (`rde doctor` points at it); if another program took its port meanwhile, it moves to the next free one and `init` says which Metabase database still points at the old port.
+
+**The instance's port is taken.** While an instance is stopped, another program can take its port. `rde start` then refuses rather than talk to that program: `port 23000 is in use by another program, so Metabase cannot start on it; stop that program and run \`rde start\` again, or move this instance with \`rde start --port 23001\``, and `rde status` says `another program answers at http://localhost:23000` instead of reporting it healthy. Stopping the other program is enough when it is temporary. `rde start --port <n>` moves the instance for good: Metabase stops, the container is created again on the new port from the image it already runs (the data is in `~/.rde` and stays), the state and Metabase's site URL take the new address, and the `mb` profile follows once Metabase answers there (if that start fails, the next `rde start` finishes moving the profile). Anything outside rde that knows the old URL (a bookmark, a data app's config) needs the new one. A container whose port forward Docker lost, which happens when its start once failed on a taken port, is repaired by the next `rde start`, which says so in one line.
 
 **The jar's Java is wrong.** The jar runtime needs Java 21 or newer and says which one it found: `Java 17.0.9 at /usr/bin/java is too old`. Point `JAVA_HOME` at a newer runtime, or put one first on `PATH`; the next `rde start` uses it. A pid file left by a reboot is recognized as stale (the pid is free, or runs something else) and ignored.