Shipping a data app means turning your checked code into a container image a registry can serve, then approving its access and receiving a ready link. Once dip app check passes locally, publish and install through dip, or bring an image you built and host yourself to the Live Apps page. Publishing from this computer requires Docker, a running Docker daemon and the buildx plugin. Run dip doctor before starting the app so you can resolve missing prerequisites early.

Push from your terminal

Publish and receive a ready link
Default pushes show build phases, a heartbeat every 30 seconds, and a build/upload timing summary. The first push builds every layer from scratch (base image download, dependencies, conformance checks) and can take several minutes; later pushes reuse cached layers. Full build output is saved in a fresh dip-app-push-*.log file in your system temporary directory; the printed path remains available after the push. Use --verbose or DIP_VERBOSE=1 to stream raw build output instead. If Docker fails, --json includes up to the last 40 lines of sanitized build output and the local build log path in error.message, with common credential patterns and URL query strings redacted. Logs larger than 64 KiB omit the diagnostic from JSON because a truncated private-key block cannot be safely redacted; inspect the local log. This also applies with --verbose. Identified connection failures have class unreachable and a next_action to check connectivity and the registry before retrying. Authentication errors use credential, registry refusals use refused, and build or conformance failures retain usage with their diagnostic. An ambiguous failure is not classified as a network outage. A failed build command does not prove that nothing was uploaded: may_have_landed is true. Check the registry before retrying; the error supplies no confirmed publication receipt. The local log contains raw output, so inspect it for secrets before sharing it. dip app build runs a Docker build, bakes your manifest into the image as a label, and re-runs the conformance check inside the build. The image runs as a non-root user. dip app push logs in to your tenant’s registry and pushes a multi-platform image (linux/amd64,linux/arm64 by default); the push auto-registers the app from that embedded manifest label, and it shows up on the Live Apps page within seconds. dip app install then asks you to confirm that exact version’s access and code trust, waits for it to become ready, and prints the link to share. It uses your human login and the plane you pushed to. See Install the app you built. A publication receipt is a record of the exact app, version and image your push registered. dip saves it in the app directory and uses it for installation and retry. A successful upload whose registration is pending or unreadable supplies no confirmed receipt. Use dip app push --json when a script needs a nonzero exit for either unconfirmed outcome, plus structured receipt data on success. On managed AWS or GCP deployments configured for readable app addresses, releases enable them after deployment checks succeed. A ready installation can use an address such as revenue--acme.apps.us.dippr.ai. Deployment upgrades preserve existing links. To request a readable address for an existing installation, run dip app install from the same app directory and confirm the selected version and access. A same-version retry keeps the published artifact. Wait for readiness before sharing the resulting link; installation-ID links continue to work. dip keeps the receipt and its record of your installation in a .dip folder inside the app directory. A scaffolded app’s .dockerignore leaves that folder out of the image. If you write your own .dockerignore, add a .dip line, so that installing a version does not change what a rebuild of that version contains.
A multi-platform push builds whichever architecture your machine isn’t natively running, under emulation. Docker Desktop ships that emulation already; a plain Linux Docker install needs it set up separately. dip doctor can’t reliably tell you whether it’s available until a build or push actually runs.
Both default architectures let the same app run on Intel/AMD and Arm nodes, including when your computer uses a different architecture from the data plane. On an Arm Mac, building amd64 uses emulation and takes longer. If you know the target nodes are all amd64, use dip app push --platform linux/amd64; for all-Arm nodes, use --platform linux/arm64.

Which registry it pushes to

Your tenant can run more than one data plane, and each has its own registry. An app can only be installed on the plane it was pushed to. dip picks the target in this order:
  1. --registry (or $DIPPR_REGISTRY) if you named one. Set --slug alongside it if the registry host doesn’t already carry your tenant’s slug (a foreign registry such as ghcr.io).
  2. Several available registries with a named default: that default automatically, including on a terminal.
  3. Several registries without a named default: a numbered choice on a terminal. A headless run uses the first listed registry and announces the selection; use --registry HOST to choose explicitly.
  4. If no choice was made from the current plane list, the registry your session saved at login.
  5. Nothing cached and exactly one available plane: that plane’s registry.
  6. No saved registry: the registries your tenant publishes about itself, with its default preferred.

From CI, with no browser

Use an isolated runner account with no cached human login. A selected human login takes precedence over an API key set in the environment.
Push from CI
The key you use needs two independent things, granted in two different places: If neither permission is granted, dip app push refuses before the build starts. It inspects the token it receives and stops with a named error, rather than running a multi-minute multi-platform build only to fail at the very last step. If the scope is missing entirely, the key can’t authenticate to the registry at all. CI keys can publish, but cannot install: apps:install is available only through a person’s explicit login consent. The CI guide describes push-only automation.

Bring your own image

If you’d rather build and host your image somewhere else, push it there yourself, then register it from the Live Apps page’s Register app dialog under Bring your own image:
  • The image reference (for example ghcr.io/acme/sql-console:0.1.0).
  • Optional pull credentials, if the image isn’t public. The password is sealed to your data plane and never shown again; a password that starts with enc:v1: (the prefix of a value Dippr has already sealed) is refused.
  • The manifest.json your image was built with, pasted in or uploaded as a file.
The console parses the manifest and shows you a live preview (its id, version, and each declared capability) before you register it. The image itself isn’t fetched or inspected at registration time. If the reference is wrong, that surfaces later as a failed installation rather than a registration error.

Record source from plane-local Git

You can attach a same-tenant plane-local repository and ref when registering an app version. Dippr resolves the ref once and stores its immutable commit and optional source folder with the version. It does not build that commit. Build and supply the image through dip app push or the bring-your-own image flow above. A moving or missing ref, a cross-tenant repository, an escaped source path, or an external GitHub or GitLab URL is refused. Existing pushed-image and bring-your-own-image versions are unchanged.

Updating a version

Members with viewer, including analyst, can create and publish versions of their own read-only apps by default. Your current role must allow Publish own apps; ownership alone does not grant publication. An administrator can turn this off in Settings → Roles & permissions, and the change applies to credentials you already hold. Broad app create and update permissions remain independent, including support for writable manifests. To register a later version, use the owner’s credentials with own-app publishing enabled, or an identity with broad app update permission. Explicit app denies still apply. Creating apps does not permit updating someone else’s app, and broad update permission alone does not permit creation. A refusal naming another owner tells you to ask them or an admin, or rename the manifest’s id and push a separate app. Increasing version does not resolve an ownership refusal. Your ownership and current publication permissions are checked before an upload can replace stored content in the app repository or any component repository. Registration checks them again after the push. See App ownership. Publish a new version by building and pushing again with a higher version in your manifest. version must strictly increase, whichever path you use. Pushing a different image under a version that is already published does not replace it: the push is not registered, and installations keep running the earlier image. A rebuild that runs the same platform images as the published version is the same version, even though its image index has a new digest, and it registers (for a version published after your tenant started recording each version’s platform images). dip app push warns you before it builds, and fails with the action to take when the registry rejects the push. Every version you ever publish is retained, which is what makes pinning and rolling an installation back possible. See Changing version. An installation keeps the image and manifest selected when you installed it or last changed its version. A same-version rebuild can update the published image without changing existing installations. Retry install, waking after suspension, and recovery after a restart reuse the installation’s selected image. To run another published version, use Change version and review its requested access. From the app directory, publishing the new version and running dip app install makes the same deliberate move after your confirmation. Repeating an unchanged install resumes the existing installation; it still checks whether your role currently allows it. If the installation’s recorded image details are incomplete or inconsistent, it cannot start and the app’s detail page shows the error. Publishing a new image does not substitute it for the installation’s selected image. You can still park or uninstall the installation. After a platform upgrade, an older installation, including one still being installed during the upgrade, may lack the recorded image details required to start. Retry install cannot recreate these details. Uninstall and reinstall the app to select a published version and review its access again.

Why does building or pushing my app fail?

See the dip app command reference for every flag.

Write the app manifest

Every field your manifest declares, and what gets validated at registration.

Manage the app registry

Naming, quotas and troubleshooting for the image registry a push lands in.

Design your app

New apps include the app-design skill alongside the SDK guide. Ask your coding agent to use it for navigation, charts, tables, actions and query states. It includes a design checker, and the starter already carries the stylesheet (dippr-app.css) for every runtime except Streamlit, so your agent does not copy it from the skill. The same skill is installed by dip login or dip skill install. Run the design checker from the installed skill directory before publishing, then run dip app check. Inspect the app in a browser at desktop and phone widths. The source checker recognizes literal remote asset URLs, including extensionless image and font URLs; dynamically computed URLs still need browser verification. Streamlit uses its documented theme values, and viewer markup does not exempt the rest of a Python file from palette checks. Source checks cannot verify how the app looks or whether an action works. Use dip app new --no-skill when you do not want either authoring skill copied into a new app.