Secrets

Comentario retrieves sensitive data (secrets), which are part of the static backend configuration, from two main sources:

• A YAML file;
• Environment variables (or files they reference).

If both sources are provided, environment variables take precedence.

This approach simplifies deployments in a Docker container or a Kubernetes cluster.

Secrets file

The secrets file is a regular YAML file, which can be provided with the --secrets command-line option, or $SECRETS_FILE environment variable. There’s a sample secrets.postgres.yaml file in Comentario git repository, which you can use as a starting point for your production configuration.

Environment variables

You can also provide certain values via environment variables (see the table below for variable names). Each value can be set either directly or via a file by using the same variable name with a _FILE suffix.

For example:

• If COMENTARIO_POSTGRES_USERNAME is set, its value is used as the PostgreSQL username.
• If COMENTARIO_POSTGRES_USERNAME_FILE is set, it must point to a readable file. The file’s contents are used as the PostgreSQL username.

Secrets configuration

Below is a summary of the values in the secrets file, with their environment equivalents.

Database

The only mandatory settings in the above table concern database configuration: Comentario requires a database for data storage.

• If postgres.host is specified, PostgreSQL database will be used. Then you’ll also need to provide postgres.database, postgres.username, and postgres.password.
• Otherwise, Comentario will use a local, file-based SQLite3 database: you have to specify a complete file path in sqlite3.file. If the file doesn’t exist, it will be created, but the path must exist and be writable.

Email sending & SMTP server settings

Comentario can optionally send notification emails. In order for this to work, SMTP server settings need to be specified:

• If smtpServer.host is not provided, no emails will be sent.
• If smtpServer.username is not provided, Comentario will try to connect to the SMTP server without authentication.

You may also need to provide a correct SMTP server port number and the encryption used. Comentario will try to guess the encryption from the port number:

• tls (a.k.a. STARTTLS) — if the port is 587 (the default),
• ssl (a.k.a. “implicit TLS”) — if the port is 465,
• or none otherwise.

If unsure, look up the corresponding values in your email service provider’s documentation. Below are a few examples for popular services.

Mailgun:

smtpServer:
  host:     smtp.mailgun.org
  port:     587
  username: '<your username@domain>'
  password: '<your password>'

Mailtrap:

smtpServer:
  host:     live.smtp.mailtrap.io
  port:     587
  username: api
  password: '<your API key>'

PrivateEmail:

smtpServer:
  host:     mail.privateemail.com
  port:     587
  username: '<your username@domain>'
  password: '<your password>'

SendGrid:

smtpServer:
  host:     smtp.sendgrid.net
  port:     587
  username: apikey
  password: '<your API key>'

External identity providers

Comentario supports federated authentication via external identity providers, such as Google and Facebook.

• If no configuration is given for a federated identity provider, this provider will not be available for user authentication.
• If you want to (temporarily) disable a fully-configured identity provider, set its disable flag to true.

You can also configure one or more OpenID Connect (OIDC) identity providers:

• The provider must support the OIDC discovery spec (i.e. serve a discovery document at .well-known/openid-configuration).
• Like other federated identity providers, any OIDC provider can be disabled using the corresponding disable flag.

Extensions

Comentario supports external comment-checking services called extensions.

• If no extension (Akismet, Perspective, etc.) API key is provided, this extension will still be available for users, but they will need to configure the key at the domain level in order to activate it.
• To disable an extension altogether, set its disable flag to true.

XSRF secret

You can provide a value in xsrfSecret, which will be SHA256-hashed and used as an XSRF key for the frontend API calls. If you omit this value, a random key will be generated.

A preconfigured, non-random secret value should be used in setups with multiple Comentario instances serving the same website; it would guarantee an XSRF token issued by one instance is accepted by another. Even in this situation it’s sensible to rotate the secret once in a while, making sure all Comentario instances are restarted afterwards.

Example

SQLite

Here’s an example of a minimal secrets.yaml file to use a local file-based database:

sqlite3:
  file: /tmp/my-comentario.db

PostgreSQL

Another example of a minimal secrets.yaml file for connecting to PostgreSQL:

postgres:
  host:     127.0.0.1
  database: comentario
  username: postgres
  password: postgres

See also

• Login via Facebook
• Login via GitHub
• Login via GitLab
• Login via Google
• Login via Twitter/X