Skip to content
Mint

Deployment

This page describes a generic private Linux deployment.

It uses systemd and a stable release link.

It does not describe a live host or its private coordinates.

Topology

Section titled “Topology”

Use one private Linux host for the broker.

Run the broker under a dedicated operating-system account.

Expose the listener through a private network boundary.

Use TailnetWhoisAuth for production caller identity.

Keep SharedSecretAuth local-only.

The broker resolves peer identity from the connection address.

Do not trust caller-supplied identity headers.

Systemd owns process lifecycle.

A stable service command points to the current release link.

The release link points to one content-addressed directory.

Keep audit data on a writable state volume.

Keep declarations and binaries read-only after activation.

Keep custody files outside the release bundle.

Unit contract

Section titled “Unit contract”

Install the unit as the service manager declaration.

Run a daemon reload after changing the unit.

Use a dedicated User and Group.

Set ProtectSystem=strict.

Set PrivateTmp=yes.

Set NoNewPrivileges=yes.

Allow writes only to the audit state directory.

Keep PrivateTmp=yes with TailnetWhoisAuth.

Whois captures bounded command output through a temporary file.

ProtectSystem=strict makes the normal temporary directory read-only.

PrivateTmp supplies a service-private writable temporary filesystem.

Removing PrivateTmp can make every whois lookup fail closed.

Keep ExecReload pointed at SIGHUP.

Keep Restart enabled for process failures.

Keep the parser paths explicit in ExecStart.

The release checker rejects a different effective command.

Immutable bundle

Section titled “Immutable bundle”

Stage a candidate with the release staging script.

The candidate contains this exact file set:

  • bin/mint
  • config/aliases.yaml
  • config/call-guards.yaml
  • config/capabilities.yaml
  • config/credentials.json
  • config/policy.yaml

The credentials metadata file contains names and identifiers only.

It does not contain credential values.

The staging script validates every declaration before promotion.

The release digest covers every fixed bundle member.

The release directory name equals the content digest.

The bundle contains no symbolic links.

Bundle members are not writable after staging.

The candidate binary runs its own preflight parser.

Use a synthetic staging root in local examples.

./scripts/stage-mint-release.sh ./target/release/mint ./deploy <release-root>

Do not run this example against a production root.

Candidate checks

Section titled “Candidate checks”

Run the candidate's release preflight before activation.

./<release-root>/releases/<candidate-sha256>/bin/mint release preflight

Preflight checks exact bundle shape and ownership.

Preflight parses policy, call guards, aliases, and capabilities.

Preflight requires an explicit empty capabilities declaration for Tailnet mode.

Preflight checks credential metadata against aliases.

Preflight checks content addressing.

Validate the effective systemd command before activation.

./<release-root>/releases/<candidate-sha256>/bin/mint release systemd-contract

The release command must run from the staged candidate.

The activation command requires a rollbackable prior release.

Activation sequence

Section titled “Activation sequence”
  1. Build a release candidate.
  2. Stage the fixed bundle.
  3. Run candidate preflight.
  4. Drain or stop the current service.
  5. Verify no unresolved prepared effects remain.
  6. Acquire the deployment lock.
  7. Reload the service manager.
  8. Validate the effective service command.
  9. Switch the current link atomically.
  10. Restart the service.
  11. Wait for live health.
  12. Read runtime evidence.
  13. Keep the candidate or restore the prior link.

The activation code writes durable deployment state.

Do not publish deployment receipt contents.

Treat deployment receipts as private operational evidence.

The readiness check expects HTTP 200 from the local health endpoint.

The runtime evidence includes restart count and unresolved audit effects.

A failed readiness check triggers rollback.

A failed active receipt write also triggers rollback.

The prior release must become healthy before rollback succeeds.

Use a synthetic previous target in command examples.

./<release-root>/releases/<candidate-sha256>/bin/mint release activate --expected-old releases/<previous-sha256>

Run activation with the required service-manager privileges.

Unit migration

Section titled “Unit migration”

Use the unit installation script when migrating an existing unit.

The script records a durable pending state before overwrite.

It retains a previous unit for recovery.

It validates the effective release command after daemon reload.

It restarts the service and checks health.

An interrupted migration retains recovery state.

Rerun the script to complete verified recovery.

Do not delete recovery state manually.

Rollback

Section titled “Rollback”

Stop new traffic before a rollback.

Restore the previous content-addressed target through the release command.

Restart the service.

Wait for HTTP 200 health.

Check restart count and unresolved audit effects.

Keep the failed candidate for later diagnosis.

Do not copy custody material while rolling back.

Deployment boundaries

Section titled “Deployment boundaries”

Deployment proves bundle integrity and service wiring.

Deployment does not prove every upstream route.

Deployment does not prove caller adoption.

Deployment does not prove that a credential value stayed out of every external process.

Use verification for behavior gates.

Use operations for health, drain, and audit procedures.

Source map

Section titled “Source map”