Skip to content
DeepSQL Docs

What install.sh does

This page documents exactly what happens when you run:

Terminal window
curl -fsSL https://install.deepsql.ai/install.sh | bash

It’s the same script that runs inside the CloudFormation deploy — there’s no second installer.

The 14 phases, in order

Section titled “The 14 phases, in order”

  1. Bootstrap from the internet (if needed).

    When piped from curl | bash, the script has no local docker-compose.yml. It resolves which version to install:

    1. DEEPSQL_SELF_HOST_REF env var if set (explicit pin, e.g. v1.0.0 or main)
    2. Latest GitHub release tag via api.github.com/repos/DeepSQLAI/deepsql-self-host/releases/latest
    3. main as a fallback if the API is unreachable or there are no releases

    It then downloads that ref’s repo archive, extracts to ~/.deepsql/self-host/, and re-executes itself from there. If you ran the script from a local checkout, this step is skipped.

  2. Capture preset env vars.

    Reads AZURE_OPENAI_KEY, AZURE_OPENAI_ENDPOINT, DEEPSQL_INITIAL_ADMIN_EMAIL, DEEPSQL_INITIAL_ADMIN_PASSWORD, image overrides, and port overrides from your environment so they win over .env defaults.

  3. Auto-install prerequisites.

    Detects your host’s package manager (dnf, yum, apt-get, apk, pacman, zypper, or brew on macOS) and installs any of curl, tar, openssl that are missing. Architecture-agnostic — the same logic works on x86_64 and arm64. You may be prompted for your sudo password on Linux.

  4. Ensure Docker is available.

    If docker isn’t already installed:

    • Amazon Linux 2023: uses dnf install docker (the official get.docker.com script doesn’t support AL2023). Also installs the Compose v2 plugin manually from the GitHub release.
    • Other Linux: downloads and runs get.docker.com (Ubuntu, Debian, Fedora, RHEL, etc.). Verifies Compose v2 plugin is present; downloads it from GitHub if missing.
    • macOS: runs brew install --cask docker and launches Docker Desktop.

    Then waits up to ~3 minutes for the Docker daemon to come up. On Linux, falls back to sudo docker if the current user can’t reach the daemon directly.

  5. Create .env from the template (if it doesn’t already exist).

    Copies .env.example → .env. On subsequent runs, your existing .env is preserved. Image refs in the template are pinned to a specific version tag (e.g. :1.0.0).

  6. Load .env into the current shell.

    Parses .env line by line and exports each KEY=VALUE.

  7. Fetch bundled LLM configuration.

    Silently curls an obscure config URL on install.deepsql.ai and extracts AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT. If your .env already has real values (not placeholders), the remote config is ignored. Skip with DEEPSQL_SKIP_REMOTE_CONFIG=true.

  8. Auto-generate security secrets.

    For any of these that are still placeholders, the script generates a fresh value with openssl rand:

    • SECURITY_JWT_SECRET (64 bytes, base64)
    • ENCRYPTION_KEY (32 bytes, base64)
    • DB_PASSWORD (16 bytes, base64)
    • ADMIN_BOOTSTRAP_SECRET (32 bytes, base64)

  9. Prompt for admin credentials (only on first install or if bootstrap is still enabled).

    Asks for an email (default: admin@yourcompany.com) and a 12+ character password (entered twice). Skip the prompts entirely by setting both as environment variables before running.

  10. Pull DeepSQL images.

    docker compose pull backend frontend from ghcr.io. Skip with DEEPSQL_SKIP_IMAGE_PULL=true if you’ve pre-loaded images locally.

  11. Start the stack.

    • docker compose up -d postgres valkey and wait for health.
    • Sync the generated DB_PASSWORD with the running Postgres instance.
    • docker compose up -d (backend + frontend).
    • Run schema migrations: enable pg_stat_statements, create the db-scheduler task table.
    • Wait for backend (/api/actuator/health) and frontend HTTP endpoints to respond.

  12. Bootstrap the initial admin user.

    Calls the backend’s internal admin-reset endpoint (gated by ADMIN_BOOTSTRAP_SECRET) to create/reset the admin login. Then disables the bootstrap flag in .env and restarts the backend so the secret can no longer be used.

  13. Install the MCP package and auto-login the CLI.

    Runs npm install -g @deepsql/mcp@latest, then authorizes the CLI against the local instance using your admin credentials via deepsql login --password --password-stdin --url http://localhost:<backend-port>. The long-lived MCP token is persisted to ~/.config/deepsql/auth.json.

    Skipped if DEEPSQL_SKIP_MCP=true or npm isn’t installed. See MCP & coding agents for details.

  14. Configure MCP for your coding agents.

    Prompts you to pick from Claude Code, Codex, Cursor (or all, or skip). Auto-skipped if there’s no TTY (CloudFormation UserData, CI). For each selection:

    Terminal window
    deepsql mcp config --install --for <agent> --force

Idempotency

Section titled “Idempotency”

install.sh is safe to re-run.

  • Existing .env values are preserved
  • Auto-generated secrets are only generated once (subsequent runs see real values and skip)
  • Admin bootstrap is disabled after first successful run, so re-runs won’t reset the admin password
  • docker compose up -d only restarts changed services
  • The deepsql CLI login is re-attempted; it overwrites any existing token

If you want to start fresh, run ./scripts/uninstall.sh first (purges volumes by default — see Uninstall).

Exit codes

Section titled “Exit codes”
CodeMeaning
0Success
1Generic failure — see the last printed error

The script uses set -euo pipefail, so it fails fast on the first error. Look at the message immediately above the exit for the cause.

Logs

Section titled “Logs”

When running via CloudFormation UserData, the full installer output is written to /var/log/deepsql-install.log on the instance. When running interactively, output goes to your terminal.

When something goes wrong, collect a diagnostic bundle and attach it to your support ticket.