Guides

Configuration Reference

This page describes how a Manifest Self-Hosted deployment is configured: the setup wizard, the configuration file it writes, and how to change values after the platform is running. For the install workflow itself, see the Installation Guide.

The Setup Wizard

manifest-installer setup interactively prompts for deployment-specific values such as the base domain, the administrator email, and (optionally) SMTP, OIDC, and CA certificate settings. On re-runs, the prompts default to your previous answers, so you can hit Enter to accept or type a new value to change it.

📘

If the wizard renders incorrectly

Over a serial console, a limited SSH client, or a screen reader, the full-screen interface can render garbled. Run TERM=dumb manifest-installer setup to get the same questions as a plain line-by-line prompt flow with no screen redrawing.

Where Configuration Is Stored

Every answer — plus a set of workload credentials the installer generates for you (database passwords and similar) — is written to a single file, ~/.config/manifest/config.yaml (file mode 0600, inside a 0700 directory). That includes the sensitive values: the SMTP password, the OIDC client secret, the license key, and the generated workload passwords. config.yaml is the single durable copy of these values — it is the artifact to back up and protect. The wizard asks you to make an encryption choice before it writes anything; see Encryption & Key Management for the choices and the consequences of key loss.

Changing Configuration After Install

Change values by re-running the wizard (prompts default to your previous answers) or by editing the file directly with deploy-config edit, then re-run deploy to apply the changes to the running platform:

manifest-installer setup        # or: manifest-installer deploy-config edit
manifest-installer deploy

Re-running deploy at the same version applies only what changed and does not restart healthy workloads.

Maintaining config.yaml

The deploy-config command groups the maintenance operations over config.yaml:

manifest-installer deploy-config validate                  # check completeness; offers to fill defaults and newly required values
manifest-installer deploy-config edit                      # decrypt into your editor, re-encrypt on save
manifest-installer deploy-config rekey --age <age1...>     # add a recipient (second operator or escrow key)
manifest-installer deploy-config encrypt --age <age1...>   # encrypt a plaintext config.yaml after the fact
manifest-installer deploy-config decrypt                   # print the decrypted config to stdout (reveals secrets)

If your ops team prepares config.yaml on another machine, copy it into ~/.config/manifest/ (together with its key file, if setup generated a password-protected key), then run manifest-installer deploy-config validate to confirm it is complete for the version you're deploying.

Host Configuration

Storage Configuration

Most deployments need a single filesystem. Give / the whole disk. The totals in Requirements cover everything listed below.

The platform writes to these paths:

PathMinimumWhat lives there
/var/lib/ranchersee belowContainer images, the self-extracted runtime binaries, and Kubernetes persistent volumes
/var/lib/kubeletsee belowkubelet state and pod ephemeral storage
/var/log/podssee belowPod logs
/root/.local/share/manifest20 GBInstaller package cache, about 4.7 GB per version. Versions you have deployed are not removed automatically
/tmp10 GBStaged installation artifacts, and each package is extracted here while it deploys

/var/lib/rancher and /var/lib/kubelet must be on the same filesystem, and need at least 200 GB between them. /var/log/pods may be a separate filesystem, and is on a STIG-partitioned host.

Storage needs will increase over time with use. The kubelet manages garbage collection of container images using k3s defaults.

STIG Compliance

Manifest Self-Hosted supports deployment on STIG-hardened systems. The setup wizard includes a STIG-hardened option; when enabled, deploy applies the SELinux, nftables, and fapolicyd host components appropriate for the hardened host.

  • SELinux: Supported on RHEL 9, including enforcing mode
  • AppArmor: Supported on Ubuntu 24.04 and Debian 12

Where the STIG requires /var on its own filesystem, mount it nodev. Do not mount it noexec or nosuid: the container runtime executes binaries from beneath the cluster data directory, and either option prevents the platform from starting. Use nofail on every non-root entry in /etc/fstab, or a single bad entry drops the host to emergency.target.

FIPS 140 Compatibility

Manifest Self-Hosted supports FIPS 140 installs. A FIPS install runs RKE2 in place of k3s and uses FIPS-built container images, which ship as a separate package set (download --flavor fips). The host must already be running in FIPS mode; the installer does not enable it. Answer yes to FIPS 140 compliant install in the setup wizard, and deploy refuses to run if the downloaded packages do not match that answer. See Installation → FIPS 140 installs.

If you have additional questions about STIG-hardened deployments, FIPS 140-3 cryptography, or other compliance requirements, contact Manifest Cyber at [email protected].

OIDC Configuration

Manifest Self-Hosted supports Google, Azure AD (Entra ID), Keycloak, and AD FS as named providers. Any other OpenID Connect provider is supported as Generic OIDC. All providers require the following information.

NameDescriptionExample
ProviderOne of Google, Azure AD (Entra ID), Keycloak, AD FS, or Generic OIDC. The choice selects how the provider's claims map to a Manifest user (see Required Claims)Azure AD (Entra ID)
Provider IDUnique name of OIDC providermicrosoft
Friendly NameName that's displayed for users at sign-in (e.g. "Login with Microsoft")Microsoft
Client IDClient ID for OIDC application (may be called "application id")abcd-1234-efgh-5678
Client SecretSecret value for OIDC applicationxyz-098-qrs-765
Issuer URLUnique URL that identifies the OIDC provider (you can find this from your applications .well-known/openid-configuration endpoint)https://login.microsoftonline.com/tenant-id/v2.0
Requested ScopesOIDC scopes requested from the provider, comma or space separated. Leave blank for openid email profile, plus allatclaims when the provider is AD FSopenid email profile
Claim MapperGeneric OIDC only, optional. A Kratos claim mapper in Jsonnet, given as plain Jsonnet or as base64:// followed by the base64-encoded Jsonnet. It must set identity.traits.userId and identity.traits.email. Leave blank to use the standard claimsbase64://bG9jYWwgY2...

Required Claims

Manifest reads a user's identity from the claims in the ID token your provider issues. Claims the provider returns only from its userinfo endpoint, or only in the access token, are not used. Every sign-in must yield a user ID and an email address; if either is missing, the sign-in fails.

Configure your provider to include these claims in the ID token:

ProviderUser IDEmail
Googlesubemail, unless email_verified is false
Azure AD (Entra ID)subpreferred_username, otherwise email, otherwise upn
Keycloaksubemail
AD FSsubemail, otherwise upn
Generic OIDCsubemail
Generic OIDC with a Claim MapperWhatever your mapper setsWhatever your mapper sets

The name, given_name, and family_name claims are optional and, when present, fill in the user's display name.

The email address must match the user's Manifest account. For the first sign-in, that is the administrator email you entered during setup (orgAdminEmail). Its domain must also be one of your organization's domains: a user whose address matches neither an existing account nor an organization domain cannot sign in.

On Azure AD (Entra ID), the address Manifest uses is usually the user principal name (UPN), because preferred_username carries it and is read first. On AD FS, the UPN is used whenever the ID token has no email claim. If your UPNs differ from your users' email addresses, for example [email protected] or [email protected] instead of [email protected], either create Manifest accounts and organization domains under the UPN form or, on AD FS, send the email claim.

Configuring the Redirect URI

To finish configuring your OIDC provider, you must add a redirect URI (callback URI) to your OIDC application. For the Manifest platform, the redirect URI is:

https://auth.<domain>/self-service/methods/oidc/callback/<provider-id>

Replace <domain> with your Manifest deployment domain and <provider-id> with the Provider ID you configured.

AD FS

Choose AD FS as the provider. The issuer URL is https://<adfs-host>/adfs.

AD FS emits an email address only when an issuance transform rule maps one, so add a rule to the application group that sends the user's email address (or make sure upn is sent).

By default, AD FS places the claims from your issuance transform rules in the access token, not the ID token, so the ID token arrives without an email and sign-in fails. To copy those claims into the ID token, the client requests the allatclaims scope, and AD FS must permit it:

  1. In AD FS, open the application group's Web API, and on Client Permissions, permit the allatclaims scope alongside openid, email, and profile.
  2. In manifest-installer setup, leave Requested scopes blank. For AD FS, blank requests openid email profile allatclaims. If you enter your own scopes, include allatclaims; setup and deploy print a warning when AD FS scopes leave it out, but do not stop you, since an AD FS configured to issue the claims in the ID token another way works without it.

On AD FS 2016, copying claims into the ID token requires update KB4019472 on the AD FS servers. Later versions include it.

An install configured before this default was added has openid email profile saved as its Requested scopes. To adopt the default, re-run manifest-installer setup, clear Requested scopes, and deploy.

Related Documentation

Updated 4 days ago

Did this page help you?