dip app new scaffolds a starting manifest for you. It’s
materialized to a manifest.json file that’s byte-identical however it was produced, which is what
lets the platform detect drift between your source and what you last built.
Top-level fields
Pin source to a plane-local repository
An app version can record source provenance from a same-tenant plane-local Git repository. The Git source is metadata, not a build request. Continue to supply the executable image through the existing pushed-image or bring-your-own-image flow.
The
plane_git entitlement and your current repository role are checked when you bind a new source.
GitHub and GitLab URLs are not accepted because Dippr does not mirror external repositories.
Components
Today your manifest has exactly one component: the container that runs your app.A component’s role is always
service in v1. worker and job are reserved for a future
run-as-owner mode and are rejected if you declare them today.Static apps
A browser-only app, like the onedip app new --runtime frontend creates, has nothing to run on a
server. It is a folder of HTML, JavaScript and CSS. Declare that folder as staticRoot and Dippr
serves the files for you:
frontend template’s image is FROM scratch plus the built folder.
The rules for staticRoot:
- It is an absolute path other than
/, with no.or..parts, no trailing slash, and at most 256 bytes. - It goes on the component that serves the app’s pages, and that component sets no
image,command,argsorenv. - The folder holds only regular files and folders. A symbolic link, hard link, device or FIFO anywhere under it stops the install, and so does a file, link, device or FIFO in place of any folder above it.
- The folder holds an
index.htmlat its top. Each file’s path inside the folder is at most 1,024 bytes and has no backslash (\). - It holds at most 2,000 files and 16 MB in total, and the files must compress to 900 KB or less. These limits fit a typical single-page app many times over. The file and byte counts include every copy of a file that the image’s layers write under the folder, even a copy that a later layer replaces or deletes, so build the folder in one layer.
- The image is pushed with gzip-compressed layers, which is what
docker buildxanddip app pushproduce. An image whose layers use zstd or no compression is refused. - The platform reads the image’s layers to find the folder, and stops after 2 GB of uncompressed layer content in total, counting what is outside the folder too. Build the static app on a small base image, or on none, as the template does.
/servesindex.html. A path with no file extension that matches no file also servesindex.html, so links into your app’s own pages work after a reload. A missing file with an extension, such as/missing.js, is a 404.- The folder’s files answer only
GETandHEAD. The page’s queries are separate requests to the platform, described next, and work as in any app. - The app’s queries go through the same
/.altimate/addresses as any app, so each visitor still sees only the rows their own access allows.
image, command, args or env beside staticRoot, is
refused before anything is installed: dip app check reports it, and the platform refuses to register
that version. A folder that breaks the rules ends the install as Failed, and its message names the
file or layer and the rule. Fix the image, push a new version, and select that version on the
installation.
An app published before its template declared staticRoot keeps running as a container until you
push a new version of it and select that version on each installation. See Versioning.
Routes
Routes map a URL path, on your app’s own host, to the component that serves it:- Up to 16 entries. Paths must be unique, but one component can back any number of routes.
- Matching is longest-prefix.
- There’s no path rewriting: a request to a path such as docs/x arrives at your component exactly as written, unchanged.
- Omit
routesentirely and the root path is routed for you. - The
/.altimate/prefix is reserved for the platform’s own endpoints (identity and the same-origin engine proxy) and can never be routed to your app. Browser code uses/.altimate/engineto query;POST /.altimate/tokenis refused.
Capabilities
Capabilities are the data your app asks to access, and they’re what an admin reviews and consents to at install time. In v1, onlykind: "data" is accepted:
Leaving a segment empty widens the scope. Catalog alone means catalog-wide; catalog and schema
means schema-wide; all three means exactly one table.
Each capability reduces to one canonical, positionally-parsed string,
data:<catalog>:<schema>:<table>:<read|write>, which is what an installation’s consent is actually
checked against. You never write this string yourself; the SDK constructors and the server both derive
it from the structured fields above, so it can never disagree with what you declared.
Declaring both a wide capability and a narrower one it already covers (say, catalog-wide read on
lakehouse alongside a schema-wide read on lakehouse.sales) is rejected. Declare the one that says
what you mean.
What gets rejected, and why
Both SDKs run the same checks at authoring time that the server runs again at registration, so you find a mistake atdip app check rather than at push:
- An
idthat isn’t a valid slug, or aversionthat isn’t semver. - A capability written in the flat, non-nested shape. An early draft of this guide showed it, and it’s rejected by name rather than silently accepted as a second valid spelling.
- A capability with no
reason, or one over 200 characters. - A
tablewithout aschema. - More than one component, more than 16 routes, or more than 8 declared
engineKinds. - A route under
/.altimate/. - An environment key named
PORT,HOME, or prefixedALTIMATE_. - An unrecognized
schemaVersion. An old server refuses a manifest shape it doesn’t understand, rather than half-parsing it.
Versioning
version must increase when you change the app’s code. An unchanged rebuild that runs the same
platform images can keep its version, even when the image index has a different digest.
A version number identifies a published release you can select. An installation also records the
exact image and manifest selected for it. Publishing another version or rebuilding the same version
does not replace that selection. Consent, retries, and wake follow the installed selection until you
explicitly choose a different version.
Every published version is retained, so you can roll an installation back to an older release. See
Build and push an image for the publish flow and
Install an app for version selection and rollback.
One component today
The manifest schema modelscomponents as a list of up to 8, and the platform will grow to run
multiple containers per app, but registering or installing a manifest with more than one component is
refused today, naming this as a roadmap limit rather than a parse error. An app deploys as a single pod.
A complete example
manifest.json
Related
Build a data app
Scaffold an app and read who’s calling it before you write a manifest by hand.
Build and push an image
Publish a new version once your manifest is ready to ship.