Quickstart¶
Build Datum, inspect the example fleet, then try one managed file on Linux. You do not need a Git remote or a running service for this walkthrough. To manage a host continuously, follow Install and run the agent.
Build and inspect the example¶
You need Git, Make and the Go toolchain specified in go.mod. Clone the source and build it:
git clone https://github.com/dsgnr/datum.git
cd datum
make build
./bin/datum validate --repo examples/fleet
./bin/datum render --host web-001 --repo examples/fleet
./bin/datum explain 'File[nginx-config]' --host web-001 --repo examples/fleet
validate checks the repository, render shows the resources selected for web-001,
and explain shows where one resource's values came from. All three read repository
content only and work on a development machine without changing its configuration.
The example fleet manages packages, services and kernel settings. For a first reconciliation, use the single file below.
Open a Linux shell¶
Applying changes requires Linux. On Linux, continue with the binary you just built:
On macOS or another development platform with Docker, open a disposable Linux container:
The container already has datum on its path. Run the rest of this walkthrough in that
shell. It manages only /tmp/datum-hello, with reports in a temporary state directory.
Describe one file¶
Create a separate fleet in a temporary directory. datum init creates the fleet root
and a base layer, which applies to every host you declare.
trial_dir=$(mktemp -d)
datum init --repo "$trial_dir" --name quickstart
mkdir -p "$trial_dir/fleet/hosts"
cat > "$trial_dir/fleet/hosts/web-001.yaml" <<'YAML'
datum: v1alpha1
type: Host
name: web-001
YAML
cat > "$trial_dir/fleet/base/hello.yaml" <<'YAML'
datum: v1alpha1
type: File
name: hello
desired:
path: /tmp/datum-hello
mode: "0644"
content: |
Hello from Datum.
YAML
init warns that the directory is outside a Git work tree. Local commands can read it
as it is; a continuously running agent needs a committed repository and configured source.
Preview, apply and check¶
The plan should propose creating File[hello]. If /tmp/datum-hello already exists,
inspect the proposed update before continuing. plan exits 2 when it finds drift;
that is an expected result, not a validation failure.
Create a private state directory and record an observation without applying changes:
mkdir -m 0700 "$trial_dir/state"
datum reconcile --host web-001 --repo "$trial_dir/fleet" --state "$trial_dir/state" --mode observe
datum status --state "$trial_dir/state"
An observe pass with drift also exits 2. When the plan matches what you want, apply it:
datum reconcile --host web-001 --repo "$trial_dir/fleet" --state "$trial_dir/state" --mode enforce
cat /tmp/datum-hello
datum status --state "$trial_dir/state"
datum plan --host web-001 --repo "$trial_dir/fleet"
The file now contains Hello from Datum., status reports the pass result, and the final
plan should find no changes and exit 0. Editing the file and planning again demonstrates
drift; another enforce pass restores its declared content.
These commands read a local directory directly and do not fetch or verify Git signatures. They need permission to write the target and state directory; this temporary-file example can run as your own user on Linux.
Continue with your own host¶
Install and run the agent covers packages, trusted signers, configuration, and the systemd service. Start it in observe mode and review drift before enabling enforcement.
For more resources, use the resource type reference. For multiple hosts, read fleet composition. The CLI reference lists flags and exit codes.