querybook

packaged by Chainguard

Chainguard Container for querybook

Querybook is an open-source Big Data IDE for writing, scheduling and sharing SQL queries and data documents.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/querybook:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard Querybook image is built from the upstream Querybook source with the same layout as upstream's Dockerfile build. It ships the Python backend, the production build of the web UI and the querybook/scripts helpers in /opt/querybook, which is also the working directory, so the commands from upstream's Docker Compose files and Helm chart run from the same place, with the differences listed below.

Differences from an image built with upstream's Dockerfile:

• The image runs as the nonroot user (UID 65532) instead of root. Upstream's Helm chart starts the scheduler with --pidfile=/opt/celerybeat.pid, which only root can write. The chart has no value for it, so change it in templates/scheduler/scheduler-deployment.yaml to a writable path such as --pidfile=/tmp/celerybeat.pid. The file result store writes to /opt/store/, so mount a volume there that UID 65532 can write, or use the default db store.
• Without arguments the image starts the production web server, ./querybook/scripts/runservice prod_web (uWSGI on port 10001). The image has no entrypoint, so the prod_web, prod_worker, prod_scheduler, and web roles and the init_db script can be passed as the command. The webpack role needs npx, which the image does not include. As in an image built with upstream's Dockerfile, the worker, scheduler, worker_scheduler, and flower roles need watchmedo or Flower, which neither includes.
• The image runs Python 3.11 instead of the Python 3.10 of upstream's Dockerfile, so plugins and their dependencies must support Python 3.11.
• uwsgi, celery and alembic are on PATH, and the scripts run the Python interpreter from the virtual environment at /usr/share/querybook/venv.
• Node.js and Yarn are not included. The UI is prebuilt, so the --initweb flag of bundled_docker_run_web and its hot-reload mode are not supported. Upstream's Helm chart starts the web pod with bundled_docker_run_web --initdb, which runs Flask's debug server and a webpack watcher that fails without Node.js. The chart has no value for these arguments, so in production change them in templates/web/web-deployment.yaml: run bash -e ./querybook/scripts/init_db once and use the default prod_web command.
• cryptography, grpcio and pyarrow come from Chainguard packages linked against the system OpenSSL rather than wheels that bundle their own. PyNaCl is not included: it is only needed to create GitHub secrets through PyGithub, which Querybook does not do, and for MariaDB's opt-in ed25519 authentication plugin, so the metadata database account must use another authentication method.
• Passwords for the built-in authentication are hashed with pbkdf2:sha256, as in upstream's builds. Existing password hashes keep working.
• Query engine client libraries are newer than upstream's pins. snowflake-sqlalchemy no longer accepts host, protocol, private_key_file, token_file_path and similar connection parameters in the connection string's query; set them under the engine's connect_args instead.
• Flask, Werkzeug and langchain are a major version newer than upstream's pins, so plugins must not import names those releases removed, such as flask.json.JSONEncoder, flask.Markup or langchain.prompts.

Getting Started

Querybook stores its data in a MySQL-compatible database, uses Redis for Celery and caching, and Elasticsearch 7 or OpenSearch 2 for search. Its Elasticsearch 7 client does not work with OpenSearch 3, so the example uses the opensearch:2 tag. Create a network and start the backing services:

docker network create querybook

docker run -d --name querybook-db --network querybook \
  -e MARIADB_ROOT_PASSWORD=root \
  -e MARIADB_DATABASE=querybook \
  -e MARIADB_USER=querybook \
  -e MARIADB_PASSWORD=querybook \
  cgr.dev/ORGANIZATION/mariadb:latest

docker run -d --name querybook-redis --network querybook \
  cgr.dev/ORGANIZATION/valkey:latest

docker run -d --name querybook-search --network querybook \
  -e DISABLE_INSTALL_DEMO_CONFIG=true \
  -e DISABLE_SECURITY_PLUGIN=true \
  cgr.dev/ORGANIZATION/opensearch:2 \
  -Ediscovery.type=single-node -Enetwork.host=0.0.0.0

Store the settings shared by every Querybook container in an environment file:

cat > querybook.env <<EOT
FLASK_SECRET_KEY=change-me
DATABASE_CONN=mysql+pymysql://querybook:querybook@querybook-db:3306/querybook?charset=utf8mb4
REDIS_URL=redis://querybook-redis:6379/0
ELASTICSEARCH_HOST=querybook-search:9200
EOT

Wait until OpenSearch reports at least a yellow cluster status:

docker run --rm --network querybook cgr.dev/ORGANIZATION/curl:latest \
  -fsS --retry 30 --retry-all-errors --retry-delay 2 \
  'http://querybook-search:9200/_cluster/health?wait_for_status=yellow&timeout=60s'

Once the database and OpenSearch accept connections, create the schema and the search indices with upstream's init_db script. It does not stop on errors by itself, so run it with bash -e to make a failed migration fail the command:

docker run --rm --network querybook --env-file querybook.env \
  cgr.dev/ORGANIZATION/querybook:latest bash -e ./querybook/scripts/init_db

Start the web server, the Celery worker and the scheduler:

docker run -d --name querybook-web --network querybook --env-file querybook.env \
  -p 10001:10001 \
  cgr.dev/ORGANIZATION/querybook:latest

docker run -d --name querybook-worker --network querybook --env-file querybook.env \
  cgr.dev/ORGANIZATION/querybook:latest \
  ./querybook/scripts/runservice prod_worker -c 4 -l info

docker run -d --name querybook-scheduler --network querybook --env-file querybook.env \
  cgr.dev/ORGANIZATION/querybook:latest \
  ./querybook/scripts/runservice prod_scheduler

Check that the web server is up:

curl http://localhost:10001/ping/

The UI is available at http://localhost:10001. With the default password authentication, the first account to sign up becomes an administrator.

Configuration

Querybook reads its settings from environment variables, which take precedence over querybook/config/querybook_config.yaml. Every container needs the same four:

• FLASK_SECRET_KEY: the key that signs sessions. Use a long random value and keep it the same across containers.
• DATABASE_CONN: the SQLAlchemy URL of the metadata database.
• REDIS_URL: the Celery broker and cache.
• ELASTICSEARCH_HOST: the search backend as host:port.

The image sets production=true, which marks the session cookie Secure, so browsers only keep it over HTTPS (or on localhost). Serve Querybook behind a TLS-terminating proxy or ingress, and set WS_CORS_ALLOWED_ORIGINS to the URL users open, as a JSON list such as ["https://querybook.example.com"]. It defaults to http://localhost:10001, and live updates over WebSocket fail from any other origin.

To use your own plugins, mount them at /opt/querybook/plugins, where QUERYBOOK_PLUGIN and PYTHONPATH already point. For another path, set QUERYBOOK_PLUGIN to it and add it to PYTHONPATH after /opt/querybook/querybook/server. The image has no pip, so upstream's RUN pip install step for plugin dependencies does not apply; put pure-Python dependencies in a directory on PYTHONPATH too.

Documentation and Resources

• Querybook documentation
• Querybook on GitHub

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.