DatumHuedatumhue.com
Contents

Overview

A DatumHue Enterprise deployment is the set of services your organization runs so that its people can use DatumHue on its own servers: from the workstation app and from a browser. This manual is for the person who installs and runs those services. It assumes you know Linux servers, TLS certificates and your organization's sign-in service, and nothing about DatumHue.

What you deploy

Every deployment uses these:

  • The workstation app, on each person's computer, or a browser at the aggregator's URL: what people use, connected as described below.
  • Aggregator, on one public host or several: connects everything else, and serves the browser workstation.
  • Deployment Tool, on any Linux machine: makes every service's settings, keys and capabilities.
  • Package Provider, on a provider host: serves the apps people run.
  • Identity Provider, on a provider host: lets people sign in with your sign-in service. Leave it out only when no one signs in.

Add these for what your apps need:

Workstations and browsers find every provider through the aggregator, so only the aggregator needs a public address. Each program is one Linux x86-64 file that runs on glibc 2.31 or later.

The words this manual uses:

  • Deployment: one organization's aggregators and providers, under one license.
  • Aggregator: the service every workstation, browser and provider connects to first, at its public HTTPS URL.
  • Provider: a service that serves one kind of thing to apps: packages, folders, data, web services, events or sign-in.
  • Mount: one named thing a provider serves, such as a shared folder or a database. Apps open a mount by its name.
  • Capability: a signed permission that lets one provider announce one mount or namespace for a limited time.
  • Seat: one of the license's places for a session or a provider instance. A running workstation or provider holds a seat; a stopped one frees it.
  • Access key: the deployment's shared secret that admits its workstations; a provider is admitted by its capabilities instead.
  • Sign-in service: your organization's OIDC service, Keycloak or Okta for example, where people sign in. The Identity Provider connects it to the deployment.

Before you start

  • The license file, customer.dhlicense, which DatumHue sends to your billing contact. It sets how many sessions, aggregators and providers the deployment may run.
  • A DNS name for the aggregator, such as datumhue.example.com, and a host that answers on it on 443/tcp and 7842, 3478 and 7843/udp.
  • A certificate for that name, or none: the aggregator can make and keep its own certificate authority.
  • Your sign-in service, with a client registered for DatumHue, if people sign in.
  • Hosts for the providers: any Linux x86-64 machines that reach the aggregator and the things they serve.

Setup order

  1. On any Linux machine, describe the deployment in deployment.kdl and generate its bundle with the Deployment Tool. The bundle holds one folder per host, each with a README.md that lists that host's steps.
  2. Set up the Aggregator first, following its host's README.md. Check that its log says License loaded and verified.
  3. Set up each provider on its host the same way, from its own page in this manual. Each provider logs its public key, which matches the bundle's pubkeys.txt.
  4. Check that the providers announced: https://<aggregator>/api/tracker/namespace_count?namespace=<name> counts the providers serving a namespace.
  5. Publish your shell and fallback apps, as The first app describes.
  6. Connect workstations and browsers, as described below.

Authorizing providers

The aggregator lists a provider only when it holds a capability for what it announces. The deployment tool makes the capabilities, under the deployment secret, when it generates the bundle or adds a provider; each provider renews its own as it runs. So a provider that is not in the deployment description can announce nothing, even with the program and a valid key. Provider authorization covers making, renewing and withdrawing capabilities.

Each provider holds one of the license's provider seats while it runs and one of its capabilities stands; a revoked provider loses its seat within about ten seconds. A provider needs no access key: its capability admits it. When every seat is taken, the next provider stops at start; stop one, or extend the license.

On the aggregator's host, aggregator lease list shows the seats taken and aggregator lease kick ends a workstation session, as Seats describes.

Connecting workstations and browsers

The workstation app reads four settings from its environment; the bundle's datumhue-client.env holds the first three. It holds the deployment's access key, so hand it out privately and keep it readable by its user only:

VariableDescription
DATUMHUE_AGGREGATOR_URLThe aggregator's public HTTPS URL
DATUMHUE_ACCESS_KEYThe deployment's access key. Anything that connects as a workstation, the datumhue command line included, needs it
DATUMHUE_CERT_PATHThe aggregator's CA certificate, when the aggregator made its own
DATUMHUE_BOOTSTRAP_PACKAGEThe first app the workstation opens, your deployment's own shell; @datumhue/bootstrap unless set

Browsers open the access link, in the bundle's access-link.txt, once: it admits that browser for 30 days, and later visits use the aggregator's public URL. A browser trusts only certificates its system trusts, so either serve a certificate from a public CA, or install the aggregator's ca-cert.pem on every computer that opens it.

A link to the browser workstation can choose what the tab opens, with these parameters joined by &, as in https://datumhue.example.com/?bootstrap=@acme/shell&data-mount=kpi:sales. The workstation app takes the same choices on its command line, such as --data-mount kpi:sales.

ParameterWhat it does
bootstrap=<package>The first app the tab opens; @datumhue/bootstrap unless set
namespace=<name>The namespace that app and the package catalog come from; datumhue unless set
session=<name>Names the tab's session. Without it, each tab has a session of its own, kept through reloads
continueTakes this browser's most recent session again
arg=<value>An argument for the first app, in datumhue.args.argv; repeat it for more
remote-dir=<name>:<mount>Grants the first app a filesystem provider's mount, read-only, as datumhue.args.dirs.<name>; remote-dir-rw= grants it read and write
data-mount=<name>:<mount>Grants the first app a data provider's mount, read-only, as datumhue.args.data_mounts.<name>; data-mount-rw= grants it read and write
http-mount=<name>:<mount>Grants the first app an egress provider's mount, as datumhue.args.http_mounts.<name>
ingress-mount=<name>:<channel>Grants the first app an ingress provider's channel, as datumhue.args.ingress_mounts.<name>

arg= also works after a # at the end of the link, as in https://datumhue.example.com/#arg=notes&arg=today. Those arguments follow the ones before the #, and the browser keeps them out of its requests to the aggregator. Pasting a link that differs from the tab's address only after the # reloads the tab.

A link that opens an app other than @datumhue/bootstrap from datumhue, or that grants a mount, opens only after the person in front of the browser confirms the app, its namespace and its mounts; Cancel opens @datumhue/bootstrap without the link's choices. A link that only passes arguments, or picks a session, opens without asking.

Each <name> may be given once, and namespaces is reserved. A link whose bootstrap is not @scope/name, whose namespace is not a valid namespace, or with a mount parameter that is malformed, repeats a <name> or uses namespaces, opens the @datumhue/fallback app, which lists what is wrong. A parameter not listed here is ignored.

For sign-in, register <public URL>/oidc-callback.html as a redirect URI of your sign-in service's client. For sign-in from the workstation app, also allow loopback redirect URIs on any port, http://127.0.0.1:*. A service that lists every redirect URI exactly takes a client-secret instead, as Registering the client describes.

The first app

DatumHue includes no apps for an Enterprise deployment, so yours publishes its own. A workstation or browser first opens @datumhue/bootstrap from the datumhue namespace: your shell, the app that frames and starts the others. When that app can't start, it opens @datumhue/fallback from the same namespace, which can show what went wrong and start what still works. The workstation app's manual describes writing both, in "Write a window manager or launcher".

Publish both to the package provider that serves datumhue, with --seed-from or datumhue pkg push, as the Package Provider page describes. While the shell is missing from its catalog, workstations and browsers show "DatumHue couldn't start", and list each app not found there.

To open another app first, set DATUMHUE_BOOTSTRAP_PACKAGE on workstations, or add bootstrap= to the browser link. A browser asks to confirm such a link on every visit, so publish the shell your browsers open as @datumhue/bootstrap.

Updating a deployment

Every workstation, provider and aggregator of a deployment must run the same DatumHue version: an aggregator refuses workstations and providers of another version, and other aggregators of another version. Update in one maintenance window:

  1. Stop every provider, then every aggregator.
  2. Install the new programs, and the new static/ folder on each aggregator host.
  3. Start the aggregators, then the providers.
  4. Give people the new workstation app.

What to back up

Each component's page lists what it keeps on disk; the deployment tool keeps nothing itself, but its description, bundle and passphrase are the source of every key.

Help

For questions, bug reports and feedback, write to support@datumhue.com or open an issue at https://github.com/datumhue/datumhue/issues.

To report a vulnerability, write to security@datumhue.com with the version, the steps that reproduce it and its impact.

datumhue.com

Victor Mono is licensed under the SIL Open Font License 1.1
Copyright (c) 2024, Rune Bjørnerås (https://github.com/rubjo)

This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL


-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------

PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.

The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.

DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.

"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).

"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.

"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.

PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:

1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.

2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.

3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.

4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.

5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.

TERMINATION
This license becomes null and void if any of the above conditions are
not met.

DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.
    ↑↓ selectEnter openTab filter

    Settings

    Theme
    Text
    Print

    Keyboard shortcuts

    / or Ctrl KSearch
    ↑ ↓ EnterPick a result
    TabNext result filter
    j kNext or previous entry
    [ ]Previous or next page
    yCopy a link to the current entry
    ?These shortcuts
    EscClose

    On this page