Skip to content

Templates

Jump to bottom
Jake Paine edited this page Apr 24, 2026 · 2 revisions

Templates

When you run keyseal add, you can pass --template <name> to seed the new encrypted file with a set of starter keys. All templates produce a kind: env document with placeholder values - they are starting points, not complete configurations.

Available templates

laravel

13 keys covering the most common Laravel application environment variables.

values:
  APP_NAME: ExampleApp
  APP_ENV: production
  APP_KEY: base64:REPLACE_ME
  APP_DEBUG: "false"
  APP_URL: https://example.com
  DB_HOST: 127.0.0.1
  DB_PORT: "3306"
  DB_DATABASE: app
  DB_USERNAME: app
  DB_PASSWORD: REPLACE_ME
  CACHE_STORE: redis
  QUEUE_CONNECTION: redis
  SESSION_DRIVER: redis

Use with:

keyseal add production/platform/app --template laravel

The placeholders (base64:REPLACE_ME, REPLACE_ME) are recognizable to doctor's placeholder check when .sops.yaml is being checked, but not when scanning secret values - doctor only checks .sops.yaml recipients for the REPLACE_ME pattern. You will need to edit these values manually with keyseal edit.

stripe

3 keys for Stripe API credentials.

values:
  STRIPE_SECRET_KEY: sk_live_REPLACE_ME
  STRIPE_WEBHOOK_SECRET: whsec_REPLACE_ME
  STRIPE_CONNECT_CLIENT_ID: ca_REPLACE_ME

Use with:

keyseal add production/platform/stripe --template stripe

mail

6 keys for SMTP mail configuration.

values:
  MAIL_MAILER: smtp
  MAIL_HOST: smtp.example.com
  MAIL_PORT: "587"
  MAIL_USERNAME: mailer
  MAIL_PASSWORD: REPLACE_ME
  MAIL_FROM_ADDRESS: noreply@example.com

Use with:

keyseal add production/platform/mail --template mail

mysql-app

5 keys for a MySQL application user connection.

values:
  DB_HOST: 127.0.0.1
  DB_PORT: "3306"
  DB_DATABASE: app
  DB_USERNAME: app
  DB_PASSWORD: REPLACE_ME

Use with:

keyseal add production/infra/mysql --template mysql-app

No template

If --template is not specified, the starter document contains a single placeholder key:

values:
  EXAMPLE_KEY: REPLACE_ME

This is the minimal starting point. It satisfies validation.require_values (the map is non-empty) and passes key pattern validation. Edit it immediately with keyseal edit to replace the example key with real content.

How templates are applied

templates.Build(logicalName, templateName) constructs an EnvSecretDocument with:

  • Version: 1
  • Kind: "env"
  • Name: <logicalName>
  • Description: "Secrets for <logicalName>"
  • Values: <template map>

The document is validated before encryption, so if the template's default values fail validation for some reason (e.g. you've changed key_pattern to disallow uppercase), add will fail before touching SOPS.

An unknown template name returns an error immediately:

keyseal add production/platform/app --template doesnotexist
# Error: unknown template "doesnotexist"

Treating Templates as Starter Scaffolding

Templates are starter scaffolding, not finished secrets. The laravel template uses 127.0.0.1 for DB_HOST, which is unlikely to be correct for every deployment. The mail template uses smtp.example.com. The stripe template uses sk_live_REPLACE_ME.

After running keyseal add --template <name>, always run keyseal edit <logical> to replace placeholder values with real credentials before the file is deployed or used.

Home

Getting Started

Reference

Operations

Development

Clone this wiki locally