Certheim · Interactive Setup Guide

Plan your Certheim deployment

A plain-English checklist that builds itself around you. Pick your edition, sign-in method, and runtime below and every step, command, and config file on this page updates to match — then follow them top to bottom. No technical background needed.

🔒

This runs entirely in your browser. Your details are used only to fill in the steps below — nothing is uploaded, logged, or stored, and nothing ever touches a Certheim server. Refresh the page and it’s gone.

Two kinds of steps. 🖥️ Web steps happen in the Certheim admin UI (point & click). ⌨️ Terminal steps happen once, in a command window on your server — copy the box exactly and paste it in. We fill in your details for you, so you can’t get them wrong.
Working through this before Certheim is installed? Perfect — that’s what it’s for. Once it’s running, the same guide is also linked inside the app as Setup Guide in the top bar. Stuck on a field? Click the little ? next to it for help.

Your details

Everything here stays in your browser — nothing is sent anywhere. Leave anything blank and we’ll show a clearly-marked placeholder you can fill in later.

Jump to: What you needInstallFirst admin LicenseOrg identitySign-in Auto-signingNotifications First certificateConfirm it worksHelp

0What you need first

Gather these before you start. If you don’t have one, ask the person who gave you Certheim.

✅ A Linux server (RHEL or AlmaLinux 9) that you can sign into, with administrator (sudo) rights.
✅ The Certheim installer files (a folder, or an certheim-offline-*.tar.gz file for sealed/offline networks).
✅ Your license file — a short text blob you received after purchase (issued from your vendor’s License portal).
✅ For automatic signing: the connection details for your CA backend (OpenBao PKI) and any credential it needs — covered in Step 6. For OpenBao that’s the address + an AppRole role_id and secret_id from whoever runs your Vault.
✅ For bring-your-own TLS: your web-server certificate (PEM, leaf + chain) and its private key on the server.
✅ For step-ca TLS: your step-ca base URL and its root fingerprint (step certificate fingerprint root_ca.crt).
✅ For CAC sign-in: your client-certificate CA bundle (e.g., the DoD root/intermediate chain) for the web server.
✅ For OIDC sign-in: your identity provider’s discovery URL (its …/.well-known/openid-configuration) and a client ID + client secret from an app/client you register there (Keycloak, Entra ID, Okta, Google Workspace…).
✅ For SAML sign-in: your IdP’s metadata (a URL or an XML file) and the ability to register Certheim as a Service Provider using the ACS URL + Entity ID that Certheim shows you.
Don’t have a server yet? That part is a one-time job for an IT admin. Once it exists, everything below is copy-paste or point-and-click.

1Install Certheim ⌨️

You chose Single server (VM), storing data in Built-in (SQLite). The boxes below are written for exactly that — change How do you want to run Certheim? above and they re-tailor instantly.

A · Normal (internet-connected) server

Run this from inside the Certheim files folder. It asks a few simple questions and does the rest.

run on your server
sudo bash install/online-install.sh

Prefer no questions? This pre-answers everything from your details above:

unattended install — your details filled in
sudo FQDN={{FQDN}} \
     AUTH_MODE={{AUTH}} \
     SERVICE_USER={{SVC}} \
{{OBINSTALL}}     ASSUME_DEFAULTS=yes \
     bash install/online-install.sh

B · Sealed / offline network

On a connected machine, build a self-contained bundle, copy it across, then run its installer.

on a connected machine
./make-offline-bundle.sh        # makes certheim-offline-<version>.tar.gz
on the offline server
tar xzf certheim-offline-*.tar.gz
cd certheim-offline-*
sudo bash install/online-install.sh   # the bundle carries everything it needs
When it finishes, Certheim is running at https://{{FQDN}}/csr/. Open that in a browser to continue.

⚙️ Prefer to automate it? Generated Ansible playbook

One playbook, pre-set to your chosen method (Single server (VM)). It uses only ansible.builtin — no extra collections. Download it alongside the installer files above and run it.

certinel-deploy.yml

    
run it


ansible-playbook -i your-server, -u you --become certinel-deploy.yml

  


  
  

    
2Create the first administrator

    
The very first person to sign in becomes the administrator. You turn this on for the initial setup, and it switches itself off automatically once you exist.


    
⌨️ Turn on first-admin mode. On the server, open the settings file and set the bootstrap line to 1:

    

    
run on your server


sudo sed -i 's/^CSR_BOOTSTRAP_FIRST_ADMIN=.*/CSR_BOOTSTRAP_FIRST_ADMIN=1/' /etc/certinel/certinel.env
sudo systemctl restart certinel-api

    

    
    

    
🖥️ Make your account. Go to https://{{FQDN}}/csr/ → Register →
       enter your name, email, and a password. You’re now the admin.

    
🖥️ Sign in with your CAC. Go to https://{{FQDN}}/csr/ with your card inserted.
       Your identity is read from the card and the first one in becomes the admin.


    
Already created a normal account and need to promote it? On the server run
      sudo certinel-bootstrap-admin your-username.

    
Security tip: once you can see the Admin menu, set
      CSR_BOOTSTRAP_FIRST_ADMIN=0 again (same file as above) so nobody else can self-promote.

  


  
  

    
3Install your license 

    
    

      
Your license unlocks your edition’s features. It’s verified right on your server — nothing phones home.

      
🖥️ In Certheim, open Admin → License, paste your license blob into the box, and click Save.

      
It should immediately show Commercial Edition with a green check. If it says
        “invalid,” you probably copied an extra space — paste it again cleanly.

      
Prefer a file instead of pasting? Put the blob in /etc/certinel/license.txt, add
        CSR_LICENSE_FILE=/etc/certinel/license.txt to /etc/certinel/certinel.env, and restart with
        sudo systemctl restart certinel-api.

    

  


  
  

    
4Set your organization identity

    
This fills in the “who” on every certificate (country, organization, units). Set it once.

    
🖥️ Open Admin → CSR Subject.

    
🖥️ Pick a profile from the list (e.g., U.S. Department of Defense, Army, Navy…). It pre-fills
      Country = US and Organization = U.S. Government, and offers DoD/command unit tags (USEUCOM, DISA, …).

    
🖥️ Fill in Organization (your organization), Country, State/Province, City,
      and any Organizational Units (e.g., IT, Security). Click Save.

    
There’s a live preview of the certificate “subject” line so you can see exactly what it’ll look like.

  


  
  

    
5Choose how people sign in

    

      
You chose username & password. It’s already on — nothing more to do here. Optional extras:

      
🖥️ Admin → Authentication — turn self-registration on/off, require admin approval of
        new accounts, or restrict sign-ups to your email domain.

    

    

      
You chose CAC / smart card. Two parts: the web server must check the card, then Certheim switches to card mode.

      
⌨️ One-time: point the web server at your card-issuer CA bundle (the DoD chain). Your IT admin sets the
        client-certificate CA bundle on the Certheim web server (nginx).

      
🖥️ In Certheim, open Admin → Authentication, set Sign-in method to
        CAC / smart card (mTLS), confirm, and Save.

      
CAC sign-in is included in Government. On Commercial it needs a CAC add-on on your license.

    

    

      
You chose single sign-on with OIDC. It’s configured entirely in the app — no server edits.

      
🖥️ Open Admin → Single sign-on and select the OIDC tab.

      
🖥️ In your identity provider, register a new OIDC client / app. Copy the Redirect URL shown on
        Certheim’s OIDC tab into the provider’s list of allowed redirect URIs (don’t hand-type it — paste exactly).

      
🖥️ Back in Certheim, paste the provider’s Discovery URL, Client ID, and Client secret,
        map the email / groups claims, click Save, then use Test login to confirm.

      
Single sign-on is included in Commercial and Government. Map an IdP group to the admin role so
        your administrators land with the right access on first login.

    

    

      
You chose single sign-on with SAML 2.0. Set it up by exchanging metadata both ways.

      
🖥️ Open Admin → Single sign-on and select the SAML 2.0 tab.

      
🖥️ Copy Certheim’s SP details (the ACS URL + Entity ID on that tab) and register them as a new
        Service Provider in your IdP.

      
🖥️ Paste your IdP’s metadata URL or XML into Certheim, map the NameID / attributes to user identity,
        click Save, then run Test login.

      
SAML needs the optional SAML library on the server — the licensed Certheim image already bundles it.
        Single sign-on is a Commercial / Government feature.

    

    
🖥️ Consent banner (gov): in Admin → Authentication pick a
      Login Banner — e.g. DoD — so users must accept the standard notice before signing in. (HIPAA, NSA, or a
      custom banner are also available.)

  


  
  

    
6Turn on automatic signing

    
This lets Certheim issue certificates itself in the web app — through your
      OpenBao PKI backend — instead of you uploading signed files by hand.


    
    

      
⌨️ Add your Vault details to the settings file on the server, then restart. (These live only on the
        server, never in the web app — that’s deliberate.)

      

      
run on your server — your details filled in


sudo tee -a /etc/certinel/certinel.env >/dev/null <<'EOF'
CSR_OPENBAO_ADDR={{OB_ADDR}}
CSR_OPENBAO_PKI_MOUNT={{OB_MOUNT}}
CSR_OPENBAO_ROLE={{OB_ROLE}}
CSR_OPENBAO_ROLE_ID={{OB_RID}}
CSR_OPENBAO_SECRET_ID={{OB_SID}}
CSR_CAP_OPENBAO=1
EOF
sudo systemctl restart certinel-api

      

      
      
    


    
🖥️ In Certheim, open Admin → Signing / CA, choose provider
      OpenBao PKI, fill in the connection details, set it as the default, and click Save & Test.


    
    
Confirm the address / PKI mount / default role you set above, then set it as the default and Save & Test.


    
    

      
Enter these on that page (filled in from your details above):

      
Admin → Signing / CA



      
For HTTP-01 give a reachable webroot; for DNS-01 pick your DNS provider (the API token for it is supplied on the server).

      
AWS credentials come from the server’s environment / instance role — not entered here.

    


    
Save & Test does a real test sign. A green “OK” means you’re fully wired — Certheim can
      now issue certificates on its own.

    
🖥️ Hands-off issuing (optional): on a certificate template, turn on Auto-sign so matching requests
      are issued instantly with no approval click.

    
Need the Vault side built (the PKI role + AppRole)? That’s a one-time job for your Vault admin:
      a policy allowing <mount>/sign/<role> (and, for per-user audit, auth/token/create),
      an AppRole, and its role_id/secret_id.

    
Any secret a backend needs (API token, AppRole secret_id, HSM PIN, AWS keys) lives in the server’s
      environment, never in the app database — this page holds only non-secret connection settings.

  


  
  

    
7Notifications (optional)

    

      
📧 Email. Open Admin → Email and pick your method:
        Company mail relay (SMTP).

      
Enter your relay host and port (often 25) and a From address your relay accepts. Save, then send a test.

      
Enter your Mailgun domain and API key and a From address. Save, then send a test. (Needs outbound internet.)

    

    

      
💬 Chat (Slack). Open Admin → Integrations, add a
        Slack destination, and paste its incoming-webhook URL. Save, then send a test message.

      
A generic webhook POSTs a JSON payload (request id, subject, status, assignee) to any endpoint you control.

      
Choose which events notify — created, issued, expiring, error — per destination.

    

    
Prefer quiet? Leave both at None — Certheim works perfectly without notifications; you just won’t get notices.

  


  
  

    
8Issue your first certificate 🎉

    
🖥️ Create requests → fill in the host name(s) you need a certificate for → submit.
      It appears as a pending request.

    
🖥️ Open the request and click Approve & sign. Certheim signs it through your CA backend
      (OpenBao PKI) and it flips to issued — download the certificate and chain right there.

    
    
That’s the everyday loop your team will use. You’re done setting up!

  


  
  

    
9Confirm everything works

    
🖥️ The app is healthy if the dashboard loads and the top shows your edition. 

    
🖥️ Admin → Signing / CA → Save & Test shows a green OK.

    
⌨️ Quick server health check (should print "ok":true):

    
run on your server


curl -sk https://{{FQDN}}/csr/api/health

    
All green? You’re live. Bookmark https://{{FQDN}}/csr/ and share it with your team.

  


  
  

    
Going further · Templates & auto-renewal

    
Set these up once and routine certificates issue — and renew — themselves.

    
🖥️ Admin → Templates — create a template (key type/size, validity, allowed SANs & usages,
      which signing backend, and delivery). Requesters just pick it; everything else is preset.

    
🖥️ On the template, turn on Auto-sign so matching requests issue instantly with no approval click.

    
🖥️ Turn on Auto-renew (per template, or the global toggle in Admin → Signing / CA) and set a
      lead time — Certheim re-issues before expiry on its own.

    
⌨️ The VM installer enables the renewal timer; confirm it’s active:

    
run on your server


systemctl status certinel-auto-renew.timer

    
Issued certs are also tracked to expiry with warning emails at 30 / 14 / 7 days, so nothing lapses silently.

  


  

    
Going further · Deliver issued certs automatically

    
After issuance, Certheim can push the certificate (and optionally its key) straight to where it’s used — no manual download.

    
🖥️ Admin → Templates → (edit a template) → Delivery — pick a destination and fill in its target:

    
    
      
  • OpenBao / Vault — write to a KV path
    • 
      
  • Kubernetes — create/update a TLS secret (namespace/name)
    • 
      
  • SSH — copy the files to a host and run a reload command
    • 
      
  • F5 BIG-IP / Citrix NetScaler — update the SSL profile
    • 
      
  • CyberArk Conjur — store in a variable
    • 
      
  • Webhook — POST the bundle to your own endpoint
    • 
    

    
Destinations and their credentials are configured in-app / on the server. A retry timer (certinel-deliver.timer)
      re-attempts failed deliveries with backoff and raises an alert if it gives up.

  


  
  

    
Going further · Advanced features (Commercial & Government)

    
Optional capabilities that appear in the admin console once your license is installed — turn on only what you need.

    
🔐 Encrypted keystore. No OpenBao/CyberArk? Keep signing keys in a built-in encrypted store. In
      Admin → Encrypted keystore pick a protection model (passphrase + recovery code, or Shamir N-of-K shares)
      and a cipher (AES-256-GCM recommended), then record the one-time recovery material — it is shown once and never again.
      Route generated keys to it via Admin → Signing / CA → key storage → Encrypted keystore, and export an
      offline backup for safekeeping.

    
📲 Device enrollment (EST & SCEP). Auto-enroll MDM fleets (Intune, Jamf) and network gear. In
      Admin → Enrollment & signing enable EST (set a shared secret) and/or SCEP (click
      Generate RA, optional challenge password). Your reverse proxy must forward /.well-known/est/ and
      /scep to Certheim.

    
🖋️ Code-signing & timestamping. In Admin → Enrollment & signing enable
      code-signing (a signer cert with the codeSigning EKU) to CMS-sign software artifacts, and the
      RFC 3161 timestamp authority (cert with the timeStamping EKU) so signatures stay verifiable after the cert
      expires. Forward /tsa at your proxy.

    
🌐 DNSSEC rollover. Keep DNSSEC-signed zones on Citrix NetScaler/ADC alive. Add zones in
      Admin → DNSSEC; new zones start in dry-run (nothing changes) until you switch them live.

    
These are gated by your license — the panels appear only when your edition is entitled.

  


  
  

    
Good to know — Commercial

    
Commercial covers unlimited domains and certificates — one flat plan, no per-domain limits.
      Need premium support, HSM / PKCS#11, or onboarding help? Those are optional add-ons — ask your vendor, then
      paste the updated license in Admin → License and the new entitlements apply right away.

  

  

    
Good to know — Government

    
Government includes everything plus: CAC / smart-card sign-in, DoD/HIPAA/NSA consent banners,
      and public-sector certificate profiles (DoD, Army, Navy, Air Force, Space Force, Marines, federal civilian) with
      command unit tags. Set the banner and profile in Admin → Authentication and
      Admin → CSR Subject. No domain limit.

  


  
  

    
If something looks wrong

    
The website won’t load. On the server run sudo systemctl status certinel-api;
      if it’s stopped, sudo systemctl restart certinel-api.

    
“Save & Test” for signing fails. Re-check the five CSR_OPENBAO_* lines in
      /etc/certinel/certinel.env (Step 6) and that the server can reach the OpenBao address.

    
Can’t see the Admin menu. You’re not an admin yet — redo Step 2 (first-admin mode), or have an
      existing admin promote you.

    
License says invalid. Copy the blob again with no extra spaces or line breaks, and make sure it’s the
      one issued for this customer.


    
Plain-English glossary

    

      
CSR
“Certificate Signing Request” — a request asking a Certificate Authority to issue a certificate.

      
OpenBao / Vault
A secure system that holds the signing key and actually issues the certificates for you.

      
AppRole (role_id / secret_id)
A username/password pair Certheim uses to talk to OpenBao. Keep the secret_id private.

      
CAC / mTLS
Signing in with a smart card / client certificate instead of a password.

      
OIDC
OpenID Connect — single sign-on against an identity provider (Keycloak, Entra ID, Okta, Google…).

      
SAML 2.0
An older single-sign-on standard; Certheim registers as a Service Provider with your IdP.

      
FQDN
Your server’s full web address, like certinel.example.com.