Doctrine · Publishing & exporting

Configuration that leaves the building

Two documents carry everything you set up, and neither takes your credentials with it.

The two documents

Document	Carries	Get it
Doctrine	The ruleset and the constants those rules read	/api/doctrine/export
Asset manifest	Every connection you hold, and every device on it	/api/manifest.yaml

Doctrine is covered in Doctrine as a file. This page is the manifest.

The asset manifest

assets.yaml

apiVersion: dome/v1
kind: AssetManifest
metadata:
  name: north-site
spec:
  links:
    - id: north-mast
      adapter: mqtt
      endpoint: ''
      direction: inbound
      discovery: off
    - id: dock-1
      adapter: dji_cloud
      endpoint: mqtt:127.0.0.1:1883/thing/product/+/osd
      direction: inbound
      discovery: off
      config:
        app_key: secret://dock-1-app-key
  assets:
    - name: ACOUSTIC-01
      product: batear/acoustic-node
      recipe: our-broker
      link: north-mast
      config:
        lat: '1.3521'
        lon: '103.8198'

Links come first, and an asset can only attach to a link declared above it. A connection is shared: ten acoustic nodes on one broker have one address and one credential between them, so it is declared once rather than repeated ten times.

An asset's own settings stay on the asset. Where a mast stands is the mast's, not the connection's. Two nodes on one broker differ there and have to.

Credentials stay behind

A secret in the file holds secret://name and never a value. That is the whole reason the file exists: it can go in a repository, into a ticket, or to a colleague, without carrying anything that grants access.

On import, DomeCommand resolves each reference against its own secret store. A reference with nothing behind it is reported by name, so you know exactly which credential to supply.

Get it

curl -H "X-API-Key: $DOME_API_KEY" \
     https://your-deployment/api/manifest.yaml > assets.yaml

Apply it

Paste it into Settings → Assets → ADD → import, or post it. Every link is validated before anything is created, and a problem names the item it is about rather than failing generically:

spec.links[1] `dock-1`: mqtt does not speak udp
spec.assets[0] `ACOUSTIC-01`: link `north-mast` is not declared

An error on a fifty-asset file that says only "invalid manifest" is not something anyone can act on, so each one carries its index and its id.

A manifest moves between sites

An inbound link's endpoint is often empty in the file, and that is correct rather than missing. When the device connects to us, the broker address is ours to publish, not yours to write down. On apply it is filled in from the receiving deployment's own configuration.

So a manifest exported at one site imports at another and points at that site's broker. The file describes what you hold; each deployment supplies where it lives.

What to keep in version control

Keep	Why
The doctrine file	It should be identical across sites, and changes to it deserve review
The asset manifest	It rebuilds a site's inventory without anyone retyping fifty devices
Nothing else	Sites, zones and runs are specific to a place and a moment

Where to go next

• Doctrine as a file for the ruleset document and its import checks.
• Onboarding an asset for adding a device by hand.