Your DataOrchester needs a licence to keep its engine running: without one, every start runs the engine for two hours, and then it stops. This is how to put a licence on it, keep it current, and give it back. For what a licence actually is and how it behaves, see How licensing works.
[!IMPORTANT] Configuration editing never needs a licence. You can install, configure and inspect an instance before it is licensed, and every start runs its engine for two hours while you put a licence on it — only keeping it running after that requires one.
The buttons
A licence is handled with a few buttons: some in the licence pane of the DataOrchester, the rest on the licence in your licences page.
| In the licence pane | What it does |
|---|---|
| Copy DO Id | Copies the DO Identifier: a block of text that describes this DataOrchester and holds no secret. |
| Check for licence | Collects the licence bound to this DataOrchester now, rather than at its next automatic check. |
| Register offline | Registers an offline key. While the DataOrchester holds an offline licence, it reads Register new key. Not offered while a Free licence is in force online: a Free licence runs online only. |
| Release licence | Gives an offline licence back and produces a release key. |
| Copy release key | Copies the release key of the licence given back last. |
| On the licence, in the portal | What it does |
|---|---|
| Bind | Binds a DataOrchester to the licence, from its DO Identifier. |
| Clear | Unbinds the DataOrchester, so the licence can run another. |
| Convert to Offline | Switches the licence to an offline key, for a DataOrchester with no internet access. Not for a Free licence, which runs online only. |
| Copy offline key | Copies the offline key the licence runs on. |
| Replace offline key | Cuts a new offline key from a fresh DO Identifier. |
| Release | Takes the release key a DataOrchester produced and brings the licence back online. |
| Extend | Buys more months on a licence bought for a term. |
Each licence offers only the buttons that apply to it right now: Convert to Offline once a DataOrchester is bound to a licence that is not Free, Copy offline key and Replace offline key once the licence is offline, and so on. Buy a licence and Extend appear once online purchase is open; until then, contact us to buy or extend a licence.
Two hours per start
Every start runs the engine for two hours, whatever its licence says: starting it from the site, restarting it after saving its configuration, or starting its service or container. After that it keeps running only while its licence is in force; otherwise it stops. Starting an engine its licence will not keep running tells you why, and when it will stop; the log says so too.
- An engine the licence stopped starts again by itself once a valid licence arrives: at its next licence check, from Check for licence, or when a key is registered.
- A licence that arrives while the engine still runs on the two hours of a start that loaded without one makes it load its configuration again and restart once, so everything the licence enables applies at once. An engine that loaded with its licence is never restarted this way.
Online activation
If your DataOrchester can reach the internet, nothing has to be typed into it:
- Get a licence on your licences page: Buy a licence, or Get a free licence. A free licence needs a confirmed email address, and there is one per person and one per organization.
- In the DataOrchester's licence pane, select Copy DO Id.
- On the licence, select Bind, paste the DO Identifier and select Bind again.
- The DataOrchester collects the licence at its next check, within four hours. Select Check for licence in the licence pane to collect it now. An engine the licence stopped starts again by itself as soon as it has one, and one still running on the two hours of its start restarts once.
The DataOrchester signs every request with its own key, the portal answers with a licence signed by Amtiri, and the DataOrchester verifies that signature itself before applying it. Nothing is trusted blindly, in either direction: the DO Identifier you pasted is what tells the portal which key to expect, so only that machine can collect the licence bound to it.
From then on the DataOrchester checks in when it starts and every four hours after that, and renews its licence by itself.
A container with no user interface
A container has no licence pane to copy a DO Identifier from. Give it the activation code that comes with the
licence instead — shown when you claim a free licence, and sent to your organization's contact address when you
buy one — in the DATAORCHESTER_ACTIVATION_CODE environment variable. When it starts without a licence, the
DataOrchester redeems the code, collects its licence and starts. If the code cannot be redeemed, the engine starts
all the same and stops two hours later: restart the container once the portal can be reached.
Keep instance/ on a persistent volume, like entities/, logs/ and loggers/: it holds the DataOrchester's
identity and its licence.
Offline activation
For a DataOrchester with no route to the internet, on any licence but Free — a Free licence runs online only. Everything travels in and out as text:
- In the licence pane, select Copy DO Id, and carry the DO Identifier out.
- On the licence, select Bind, paste the DO Identifier and select Bind again.
- On the same licence, select Convert to Offline, paste the same DO Identifier once more and select Convert to Offline. The portal shows the offline key: a licence file issued for that DataOrchester and no other. Copy it — Copy offline key hands it over again at any time.
- Carry the key in. In the licence pane, select Register offline, paste the key and select Register. An engine the licence stopped starts again by itself, and one still running on the two hours of its start restarts once.
Going offline is a one-way step for that licence: from then on the DataOrchester runs on its offline key and never contacts the portal, and only a release key produced on the machine brings the licence back online.
Renewing
Online — nothing to do. While it can reach the portal, the DataOrchester renews its licence by itself, a week at a time, and the portal confirms the licence at the check-ins in between. Without that confirmation it runs for seven days before it stops, and the licence pane warns from the second day. That holds for every edition, Free and permanent included: a DataOrchester that cannot reach the portal for longer needs an offline key, which a Free licence cannot have.
Offline — select Extend on the licence, then Copy offline key: once the licence is extended it hands over a new key carrying the new expiry, cut from what the portal already holds, so nothing has to be fetched from the machine. Carry it in and register it with Register new key in the licence pane.
A monthly licence renews itself, and a Free or permanent licence never ends, so neither offers Extend.
When an expired licence is extended or its payment settled, an online DataOrchester collects it at its next check, reloads its configuration and starts by itself; Check for licence does it at once. An engine that an operator stopped stays stopped — start it again yourself.
Giving a licence back
When you retire or rebuild a machine, give its licence back so it can run another.
Online — select Clear on the licence. The licence is free at once, to Bind another DataOrchester. The one you cleared stops within about four hours, at its next licence check — or seven days after it last reached the portal, if it cannot reach it, and up to two weeks if it has not been updated. Clear it once you are done with the machine, not before. Cleared the wrong one? Bind it again with its DO Identifier, and it collects the licence back.
Offline — an air-gapped DataOrchester cannot be told anything by the portal, so its offline key stays valid whatever the portal forgets. It has to give the licence back itself:
- In the licence pane, select Release licence, then Release. From this moment the DataOrchester holds no licence, and a running engine stops at its next licence check, within four hours.
- Select Copy release key, and carry the release key out.
- On the licence in the portal, select Release, paste the release key and select Release again.
The licence stays on that DataOrchester and is online again: if the machine can reach the portal, Check for licence collects it and the engine runs on. To use the licence on another machine, select Clear. The key given back, and any key cut for that machine before it, can no longer be registered on it.
A machine that is gone — failed, wiped or unreachable — cannot produce a release key. Tell us, and we release the licence from our side: it is free at once, and we send you a revocation to keep. If that machine ever comes back, paste the revocation into Register new key in its licence pane: the licence ends there, and the engine stops — once the two hours of its start are over, if it was started less than two hours earlier.
Replacing an offline key
Replace offline key cuts a new key from a fresh DO Identifier. You need it when:
- the DataOrchester was updated to a version that no longer trusts the key its licence was signed with — the licence pane says so; or
- its hardware changed, and the licence pane says it is running on its grace period.
- In the licence pane of that DataOrchester, select Copy DO Id.
- On the licence in the portal, select Replace offline key, paste the DO Identifier and select Replace offline key. Copy the new key.
- In the licence pane, register it with Register offline — or with Register new key, while the DataOrchester still holds its offline licence.
A key is replaced only for the same DataOrchester, on hardware that still matches its licence closely enough. If the portal answers that the hardware no longer matches, contact us and we reissue the key for the changed machine.
Moving a licence to another machine
A licence runs one DataOrchester at a time.
- Online — select Clear, then Bind with the new machine's DO Identifier. The new DataOrchester collects the licence by itself; the old one stops within about four hours, as a cleared one does.
- Offline — give the licence back on the old machine first, as described above, which brings it back online. Then select Clear, Bind the new machine's DO Identifier, select Convert to Offline with the same DO Identifier, and register the key on the new machine with Register offline.
Next steps
- How licensing works — states, renewal and what stops an engine
- Configuration reference
- Upgrading