This documentation site is about the unstable (upcoming) Comentario version.  Switch to the stable version »

Secrets

Secrets configuration

Comentario stores its sensitive data in a YAML file called secrets. The secrets file is a part of static backend configuration.

The main reason for choosing this approach was that a separate secrets file can easily be deployed and connected to Comentario running in a Docker container or Kubernetes cluster.

The file is a regular YAML file; it doesn’t necessarily need to be named secrets.yaml, but it’s the default name unless configured otherwise.

Secrets file reference

There’s a sample secrets.postgres.yaml file in Comentario git repository, which you can (and should) use as a starting point for your production configuration.

Below is a summary of the values in the secrets file.

KeyTypeDescriptionDefault value
Database
postgres.hoststringHostname or IP address of PostgreSQL DB
postgres.portintegerPort number of PostgreSQL DB5432
postgres.databasestringName of the PostgreSQL database
postgres.usernamestringUsername to connect to PostgreSQL
postgres.passwordstringPassword to connect to PostgreSQL
postgres.sslmodestringSSL mode for PostgreSQL (disable, allow, prefer, require, verify-ca, verify-full)disable
sqlite3.filestringPath to the SQLite3 database file
SMTP server
smtpServer.hoststringHostname or IP address of SMTP server. Required for emailing to work
smtpServer.portintegerPort number of SMTP server587 (STARTTLS)
smtpServer.usernamestringUsername to connect to SMTP server
smtpServer.passwordstringPassword to connect to SMTP server
smtpServer.encryptionstringEncryption used for sending mails: none, ssl, tlsDerived from port
smtpServer.insecurebooleanWhether to skip SMTP server’s SSL certificate verificationfalse
Identity providers
idp.facebook.disablebooleanWhether to forcefully disable Facebook authentication
idp.facebook.keystringClient ID for Facebook authentication
idp.facebook.secretstringClient secret for Facebook authentication
idp.github.disablebooleanWhether to forcefully disable GitHub authentication
idp.github.keystringClient ID for GitHub authentication
idp.github.secretstringClient secret for GitHub authentication
idp.gitlab.disablebooleanWhether to forcefully disable GitLab authentication
idp.gitlab.keystringClient ID for GitLab authentication
idp.gitlab.secretstringClient secret for GitLab authentication
idp.google.disablebooleanWhether to forcefully disable Google authentication
idp.google.keystringClient ID for Google authentication
idp.google.secretstringClient secret for Google authentication
idp.twitter.disablebooleanWhether to forcefully disable Twitter/X authentication
idp.twitter.keystringClient ID for Twitter/X authentication
idp.twitter.secretstringClient secret for Twitter/X authentication
OIDC identity providers
idp.oidcarrayArray of OIDC provider entries, each element is an object (see below)
idp.oidc.[N].idstringUnique ID of the OIDC provider, consisting of max. 32 lowercase letters, digits, and dashes
idp.oidc.[N].namestringOIDC provider display name
idp.oidc.[N].urlstringOIDC provider server URL
idp.oidc.[N].scopesarrayOIDC scopes to request (array of strings)
idp.oidc.[N].disablebooleanWhether to forcefully disable authentication via this provider
idp.oidc.[N].keystringOIDC client ID
idp.oidc.[N].secretstringOIDC client secret
Extensions
extensions.akismet.disablebooleanWhether to globally disable Akismet API
extensions.akismet.keystringAkismet API key
extensions.perspective.disablebooleanWhether to globally disable Perspective API
extensions.perspective.keystringPerspective API key
extensions.apiLayerSpamChecker.disablebooleanWhether to globally disable APILayer SpamChecker API
extensions.apiLayerSpamChecker.keystringAPILayer SpamChecker API key
Other
xsrfSecretstringRandom string to generate XSRF key from (30 or more chars recommended)Random value

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

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.

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
WARNING: The above is just an example!
In certain systems the /tmp directory gets cleaned on each reboot, so you’ll lose all data.

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