Secrets

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.

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

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