deploy

Deploy or reconnect to a local CedarDB instance via Docker.

Rules

• Never use absolute paths.
• Write final literal values, not shell variables or placeholders.
• Do not delete or recreate containers or data unless the user explicitly asks.
• Do not run privileged host-fix commands automatically.

1. Inspect first

Run:

docker --version
docker info
docker ps -a --filter name=cedardb --format '{{.Names}}\t{{.Status}}'

Check port 5432:

ss -tln | grep ':5432 ' || netstat -tln 2>/dev/null | grep ':5432 '

Choose host port:

• 5432 if free
• otherwise 5433

If Docker is missing or the daemon is not running, stop and tell the user what to do:

• Linux install: curl -fsSL https://get.docker.com | sh
• Linux start daemon: sudo systemctl start docker
• macOS/Windows: install or open Docker Desktop

Summarize:

• Docker available or not
• daemon running or not
• existing cedardb container state
• chosen host port
• next safe action

If the user has not explicitly asked to deploy, start, or recreate, stop here.

2. Reuse or start when possible

If cedardb exists and is running, prefer reuse.

If cedardb exists and is stopped and the user wants reuse, run:

docker start cedardb

If the user explicitly wants recreation, run:

docker rm -f cedardb

Do not remove cedardb-data unless the user explicitly asks to remove stored data too.

3. Deploy a new instance

Generate a password:

openssl rand -hex 16

Create the data directory and pull the image:

mkdir -p cedardb-data
docker pull cedardb/cedardb

Run the container with the chosen host port and the literal generated password:

docker run -d \
  --name cedardb \
  --restart unless-stopped \
  -p <host-port>:5432 \
  -v ./cedardb-data:/var/lib/cedardb/data \
  -e CEDAR_PASSWORD=<generated-password> \
  cedardb/cedardb

Replace <host-port> and <generated-password> with literal final values.

4. Verify readiness

Run docker ps and logs in the background, then check the output:

docker ps --filter name=cedardb
docker logs --tail 20 cedardb

If the container is not running or logs show errors, report and stop. Otherwise wait a few seconds and verify the database is accepting connections before proceeding.

5. Write .cedardb

Write the file in the current working directory using literal final values:

cat > .cedardb <<'EOF'
CEDAR_DSN=postgresql://postgres:<password>@localhost:<host-port>/postgres
CEDAR_LABEL=cedardb
EOF

Replace <password> and <host-port> with literal final values before writing.

If .gitignore exists, append .cedardb only if missing:

grep -qxF '.cedardb' .gitignore || echo '.cedardb' >> .gitignore

6. Return to the user

Return:

• action taken: inspect-only, reuse, start, or new deploy
• container name: cedardb
• data directory: ./cedardb-data
• host: localhost
• host port
• user: postgres
• database: postgres
• password
• DSN string
• whether .cedardb was written

Useful commands:

docker logs -f cedardb
docker stop cedardb
docker start cedardb
docker rm -f cedardb
rm -rf cedardb-data

Only include the last command when discussing full cleanup.

Troubleshooting

• If the container exits immediately, run docker logs cedardb.
• If 5432 is occupied, use host port 5433 and update the DSN.
• If existing data was initialized with different credentials, either reuse the original credentials or explicitly remove cedardb-data and recreate.