Quickstart: Docker

This page does one job: get the MCPDBWizard console running on Docker and sign you into it. Everything after that — loading a config, generating a server, issuing a token, connecting an agent — is the same wherever the container runs, and it is in the Quickstart.

Use Docker when you are evaluating the product, authoring configs against a development database, or running it on a server you already administer. For managed capacity in a cloud account, see Quickstart: AWS.

Before you start

Docker, and an Oracle database the container can reach. 12c through 26ai are supported.
The demo user and schema from Quickstart steps 1 and 2. If you are pointing at your own schema instead, skip them.

1. Settle the five settings

Four are required; the port defaults to 1521. Exporting them first keeps the password off the docker run command line and out of your shell history.

export MCPDBWIZARD_ORACLE_HOST=endowment
export MCPDBWIZARD_ORACLE_PORT=1521
export MCPDBWIZARD_ORACLE_SID=/FREEPDB1
export MCPDBWIZARD_ORACLE_USER=mcpdemo
export DB_PASS=mcpdemo

A leading / on the SID selects the service-name form, which is what a pluggable database like FREEPDB1 needs. Without it you get the older SID form and a failure that reads like a wrong hostname. See Connecting to Oracle.

These are not extras to add later. Without them the console starts, serves the Users and Runtime pages, and refuses every Design page — there is no connect form, so there is nowhere else for them to come from.

2. Pull and run

docker pull ghcr.io/srmadscience/mcpdbwizard:2.0.29

docker run -d --name mcpdbwizard \
  -p 8080:8080 \
  -v mcpdbwizard-data:/data \
  -e MCPDBWIZARD_ORACLE_HOST \
  -e MCPDBWIZARD_ORACLE_PORT \
  -e MCPDBWIZARD_ORACLE_SID \
  -e MCPDBWIZARD_ORACLE_USER \
  -e DB_PASS \
  ghcr.io/srmadscience/mcpdbwizard:2.0.29

-e NAME with no =value copies the variable through from the shell running docker.

Pin the version tag. :latest moves under you, and — worse — docker run does not contact the registry for an image the machine already has, so a box that pulled :latest once keeps starting that same build months later with nothing in the output to say so. Launching on Docker has the digest comparison that settles which build you actually have.

Only 8080 is published, and that is deliberate. Generated servers bind 8090–8109 on loopback inside the container and are reached through the proxy on 8080, which is the only component that knows who is calling. Publishing them directly bypasses the accounts and the access grid.

Open http://localhost:8080.

There is no default password. This installation generated one for itself and wrote it to initial-admin-password in the config directory; the sign-in page names the exact path.

docker exec mcpdbwizard cat /data/initial-admin-password

Sign in as admin and choose your own password. You are made to — the generator will not run until you have — and the file is deleted the moment you do.

Set ADMIN_INITIAL_PASSWORD on the docker run if you would rather choose it yourself. You are still made to change it at first sign-in.

4. Keep the volume

Configs, accounts, access grants, each runtime’s workspace and the audit spool all live on /data. Replacing the image is then routine; losing the volume is losing your curation. Declaring it external in a compose file makes docker compose down -v unable to remove it.

That is not a backup. Taking one — docker run --rm -v mcpdbwizard-data:/data -v "$PWD":/backup alpine tar czf /backup/mcpdbwizard-data.tgz -C /data . is the whole of it — is your job.

Two settings people miss

MCPDBWIZARD_ORACLE_OTHER_USER names a second schema whose objects are listed alongside the connected account’s own — the usual case being an application account with grants on a schema it does not own. Leave it out and you see only what MCPDBWIZARD_ORACLE_USER owns, which looks exactly like missing privileges. Add -e MCPDBWIZARD_ORACLE_USER_OBJECTS=false to list only that second schema. The strip along the top of every Design tab always says which you are getting.

A memory limit. Without a cgroup limit the container’s memory metric is a percentage of the whole host. The limit is shared by the web app, the forked generator and one MCP server per running config; at the shipped defaults 4 GB holds the web app and about four concurrent servers. Raise it before raising the number of configs you run at once.

You have a console. Continue at Quickstart step 4 — load the demo config, generate the server, issue a token and point an agent at it.

The full reference for this page is Launching on Docker and Docker parameters.