Diagnostic bundle

When something’s wrong and you don’t know where to start, run ./scripts/diagnose.sh. It packages everything we’d ask for in a support ticket into one tarball — with secrets redacted automatically.

cd ~/.deepsql/self-host       # or wherever you installed
./scripts/diagnose.sh

Output:

================================================================
Diagnostic bundle created (217 KB):

  /home/ec2-user/deepsql-diag-20260517-164938-ip-10-0-1-42.tar.gz

Secrets matching *KEY/*SECRET/*PASSWORD/*TOKEN/*CREDENTIAL/*EMAIL
are redacted in env.redacted. Open the tarball and review before
sharing if you want to double-check.
================================================================

What’s in the bundle

File	Contents
`metadata.txt`	When it was generated, hostname, install dir
`system.txt`	OS, kernel, CPU count, memory, disk usage
`docker.txt`	Docker + Docker Compose versions, daemon info, disk usage
`stack.txt`	`compose ps`, image refs, container health, resource snapshot
`logs/{postgres,valkey,backend,frontend}.log`	Last 1000 lines per service
`env.redacted`	Your `.env` with secret values masked
`docker-compose.yml`	Copy of the compose file (no secrets)
`network.txt`	DNS resolution + TCP 443 reachability to install / ghcr / GitHub / npm / Azure
`status.txt`	Output of `./scripts/status.sh`
`smoke-test.txt`	Output of `./scripts/smoke-test.sh`
`backend-errors.txt`	Pre-filtered error/exception/failure lines from the backend log
`install-context.txt`	Git rev (if a checkout), install dir listing
`README.txt`	Index of all files + secrets-handling notes

What is NOT collected

Database contents, queries, query results, LLM prompts and responses, user data, vector embeddings. The script reads .env, container logs, and system metadata only.

Secret redaction

Values for any .env key whose name matches one of these patterns are replaced with ***REDACTED***:

*KEY (e.g. AZURE_OPENAI_KEY, ENCRYPTION_KEY)
*SECRET (e.g. SECURITY_JWT_SECRET, ADMIN_BOOTSTRAP_SECRET)
*PASSWORD (e.g. DB_PASSWORD, DEEPSQL_INITIAL_ADMIN_PASSWORD)
*TOKEN, *CREDENTIAL, *EMAIL

Customizing where the bundle lands

# Write to a specific directory instead of $HOME
DEEPSQL_DIAG_OUT_DIR=/var/log ./scripts/diagnose.sh

# Point at a non-default install location
DEEPSQL_COMPOSE_FILE=/opt/deepsql/docker-compose.yml \
DEEPSQL_ENV_FILE=/opt/deepsql/.env \
  ./scripts/diagnose.sh

Running on a CloudFormation-deployed instance

aws ssm start-session --region <region> --target <instance-id>
# On the instance:
cd ~/.deepsql/self-host
./scripts/diagnose.sh
# Copy the tarball out via SSM file transfer or a scratch S3 bucket

Where to send it

GitHub issue: https://github.com/DeepSQLAI/deepsql-self-host/issues — attach the tarball
Email: support@deepsql.ai

Include a one-paragraph description of what you were doing, what you expected, and what happened instead.