Configuration
happyDomain respects the methodology 12 factor and allows to act on the application configuration in several ways.
How do I configure happyDomain?
It is possible to configure happyDomain in three different ways: configuration file, environment, command line. All options are available for each of these mechanisms.
The precedence, when an option is defined by several mechanisms simultaneously, is that an option present in a configuration file will be overwritten by the environment, which will be overwritten by an option passed on the command line
Configuration by file
When the application is launched, the first configuration file from the following list will be used:
./happydomain.conf$XDG_CONFIG_HOME/happydomain/happydomain.conf/etc/happydomain.conf
Only the first existing file is taken into account. It is not possible to have part of its options in /etc/happydomain.conf and part in ./happydomain.conf, only the latter configuration file will be taken into account.
It is possible to specify a custom path by adding it as an additional parameter to the command line. Thus, to use the configuration file located at /etc/happydomain/config, we would use :
Configuration file format
Comments line has to begin with #, it is not possible to have comments at the end of a line, by appending # followed by a comment.
Place on each line the name of the config option and the expected value, separated by =. For example:
Configuration by the environment
When happyDomain is started, all variables beginning with HAPPYDOMAIN_ are scanned for valid configuration options.
You can do the same thing as in the previous example, with the following environment variables:
You just have to replace dash by underscore.
Command line configuration
Finally, the command line can be used to pass options, according to the usual UNIX format.
To continue the previous example, we can perform the same configuration with the following command line:
or by using the = sign to clearly assign the value.
Configuration items
The complete list of configurable items can be listed by calling happyDomain with the -h or --help option.
Here is a list of the main options:
General parameters
bind- Bind port/socket to use to expose happyDomain.
admin-bind- Bind port/socket to use to expose the administration API.
default-ns- Address and port of the name resolver server to be used by default when name resolution is required.
dev- URL to which all requests related to the graphical interface will be returned.
externalurl- URL of the service, as it should appear in emails and content to the public.
disable-providers-edit- Disallow all actions on provider (add/edit/delete), eg. for demo mode.
Page layout
custom-head-html- String to be placed before the end of the HTML header.
custom-body-html- String to be placed before the end of the HTML body.
hide-feedback-button- Hide the icon on page that permit to give feedback.
msg-header-text- Custom message banner to add at the top of the app.
msg-header-color- Background color class of the banner added at the top of the app (default “danger”, can be primary, secondary, info, success, warning, danger, light, dark, or any bootstrap color class).
Data storage
storage-engine- Allows you to choose the data storage mechanism among all supported mechanisms.
LevelDB (storage-engine=leveldb)
leveldb-path- Path to the folder containing the LevelDB database to use.
E-Mail parameters
We use go-mail as a library to send mails.
mail-from- Defines the name and address of the sender of emails sent by the service. Accepts either a bare address (
info@domain.com) or a display name followed by the address in angle brackets (Domain <info@domain.com>). For example, on the command line:-mail-from "Domain <info@domain.com>"; through the environment:HAPPYDOMAIN_MAIL_FROM="Domain <info@domain.com>".
Note that without the mail-smtp-* options, happyDomain will use the sendmail binary to send mail. This can be coupled with the msmtp or ssmtp packages, for example, to set the parameters for the whole system.
mail-smtp-host- IP or host name of the SMTP server to use.
mail-smtp-port- Port to use on the remote server.
mail-smtp-username- When authentication is required on the remote server, username to use.
mail-smtp-password- When authentication is required on the remote server, password to use.
no-mail- Disables all automatic mails, and skips the email verification step at registration.
Authentication
no-auth- Disables the notion of users and access control. A default account is used.
disable-embedded-login- Disables the internal user/password login in favor of external-auth or OIDC.
disable-registration- Forbids new account creation through public form/API (still allow registration from external services).
external-auth- URL base of the authentication and registration service to be used instead of the embedded login system.
jwt-secret-key- Secret key used to verify JWT tokens.
See also OpenID Connect settings.
Accounts and data
By default (embedded login, no external-auth), every account is created and stored in your own instance’s database, using whichever storage-engine you configured above. Nothing is ever sent to happydomain.org: the project’s hosted instance at app.happydomain.org is just one deployment among others, entirely separate from any instance you run yourself.
The three options above can be combined to shape how registration behaves on your instance:
- Leave everything default: anyone can self-register, and (unless
no-mailis set) must validate their email address before the account is usable. no-mail: registration stays open, but the email verification step is skipped; accounts are usable immediately. Useful when no SMTP relay is configured.disable-registration: no new account can be created through the public form or API; existing accounts still work, and accounts can still be provisioned throughexternal-author OIDC.no-auth: removes the whole notion of accounts; every visitor shares a single default account. Suited for local/single-user or evaluation setups.
Specific to registrars
Some registrars require third-party applications to identify themselves in addition to the user.
Bind
with-bind-provider- Enable the BIND provider, confined to the given directory (not suitable for cloud/shared instance as it’ll access the local file system).
This option expects the absolute path of a directory containing your zone files, it is not a simple on/off switch: there is no way to enable the provider without declaring at least one directory.
Users of the instance can then only point their Bind files/RFC 1035 connector at that directory or at one of its subdirectories. Any other path is refused, both when the connector is saved and every time a zone is listed, read or written, so a connector stored before this restriction existed is neutralized as well.
Symbolic links are resolved before the comparison, so a link placed inside an allowed directory cannot be used to escape it. The allowed directories are expected to belong to the administrator of the instance, not to be writable by its users.
Repeat the option on the command line to allow several directories:
In the environment or in a configuration file, where an option can only appear once, separate the directories with the path list separator (: on UNIX):
OVH
Please refer to this documentation to generate the identifiers.
ovh-application-key- Application key for OVH API.
ovh-application-secret- Secret key for OVH API.