Deployment
canardstack is one binary. The deploy examples use that binary in two roles:
canardstack servereceives OTLP/HTTP and serves the Prometheus, Loki, and Tempo-shaped query APIs.canardstack serve-catalogserves the DuckLake metadata catalog over Quack.
The app keeps its raw spool and working DuckDB state on a local filesystem. It talks to the catalog over Quack and writes DuckLake data files to object storage. Keep both services at one instance unless you are changing the writer model deliberately.
Choose a path
Section titled “Choose a path”| Path | Use it for | Storage shape |
|---|---|---|
| Local quickstart | First run, laptop checks, development | Local DuckLake catalog and data files under .canardstack. |
| Send telemetry | Configure OTLP/HTTP producers | OpenTelemetry Collector otlphttp exporter to canardstack. |
| MotherDuck | Fast remote DuckLake experiments | Local app and Grafana, hosted DuckLake catalog through md:. |
| GCP Cloud Run | Push-button GCP demo | Cloud Run app and catalog services, GCS DuckLake data files. |
| AWS ECS/Fargate | Push-button AWS demo | ECS app and catalog services, EBS for local state, S3 DuckLake data files. |
Shared topology
Section titled “Shared topology”Common settings
Section titled “Common settings”CANARDSTACK_DUCKLAKE_ATTACH_URI points the app at a DuckLake catalog. In the
cloud examples it is a Quack URI such as
ducklake:quack:catalog.internal:443. With MotherDuck it is an md: URI.
CANARDSTACK_DUCKLAKE_DATA_PATH points DuckLake at object storage for Parquet
data files, such as gcs://bucket/prefix/ or s3://bucket/prefix/. It is not
used for the MotherDuck quick path shown here.
CANARDSTACK_DUCKLAKE_QUACK_TOKEN is shared by the app and the catalog service.
Treat it as a secret. Quack is the catalog authentication boundary in these
examples.
CANARDSTACK_DUCKLAKE_CATALOG_PATH belongs on the catalog service. Do not set it
on the app when the app attaches to a remote Quack catalog.
CANARDSTACK_DUCKLAKE_QUACK_INSECURE_TLS is used only where the catalog service
terminates TLS with the in-binary self-signed TLS shim. The AWS example needs it
because ECS Cloud Map names do not have managed TLS. Cloud Run does not need it
because Cloud Run terminates TLS with a managed certificate.
CANARDSTACK_POSTGRES_DSN stays unset in these examples.
Deployment artifacts
Section titled “Deployment artifacts”The deploy source files stay in the repository:
Those directories contain the runnable artifacts. These docs are the operator guide for using them.