Using Docker

happyDomain is sponsored by Docker. You’ll find the official container image on the Docker Hub.

This image will run happyDomain as a single process, with a LevelDB database (similarly to sqlite, LevelDB is stored on disk, no need to configure anything).

Supported tags and architectures

All tags are build for amd64, arm64 and arm/v7 and are based on alpine.

Currently, available tags are:

• latest: this is a the most up to date version, corresponding to the master branch.

Using this image

For testing purpose

You can test happyDomain or use it for your own usage, with the option HAPPYDOMAIN_NO_AUTH=1: this will automatically creates a default account, and disable all features related to the user management (signup, login, …).

docker run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain

Data are stored in /data directory. If you want to keep your settings from one run to another, you’ll need to attach this directory to a Docker managed volume or to a directory on your host:

docker volume create happydomain_data
docker run -e HAPPYDOMAIN_NO_AUTH=1 -v happydomain_data:/data -p 8081:8081 happydomain/happydomain

In production

happyDomain needs to send e-mail, in order to verify addresses and doing password recovery, so you need basically to configure a SMTP relay. Use the options HAPPYDOMAIN_MAIL_SMTP_HOST, HAPPYDOMAIN_MAIL_SMTP_PORT (default 25), HAPPYDOMAIN_MAIL_SMTP_USERNAME and HAPPYDOMAIN_MAIL_SMTP_PASSWORD for this purpose:

docker run -e HAPPYDOMAIN_MAIL_SMTP_HOST=smtp.yourcompany.com -e HAPPYDOMAIN_MAIL_SMTP_USERNAME=happydomain -e HAPPYDOMAIN_MAIL_SMTP_PASSWORD=secret -v /var/lib/happydomain:/data -p 8081:8081 happydomain/happydomain

If you prefer using a configuration file, you can place it either in /data/happydomain.conf to use the volume, or bind your file to /etc/happydomain.conf:

docker run -v happydomain.conf:/etc/happydomain.conf -p 8081:8081 happydomain/happydomain

Extend the base image

By default, happyDomain uses sendmail, if you prefer, you can create you own image with the package ssmtp:

FROM happydomain/happydomain
RUN apk --no-cache add ssmtp
COPY my_ssmtp.conf /etc/ssmtp/ssmtp.conf

Admin Interface

happyDomain exposes some administration command through a unix socket. The docker container contains a script to access this admin part: hadmin.

You can use it this way:

docker exec my_container hadmin /api/users
docker exec my_container hadmin /api/users/0123456789/send_validation_email -X POST

This is in fact a wrapper above curl, but you have to start by the URL, and place options after it.

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 :

./happydomain /etc/happydomain/config

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:

storage-engine=leveldb
leveldb-path=/var/lib/happydomain/db/

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:

HAPPYDOMAIN_STORAGE_ENGINE=leveldb
HAPPYDOMAIN_LEVELDB_PATH=/var/lib/happydomain/db/

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:

./happydomain -storage-engine leveldb -leveldb-path /var/lib/happydomain/db/

or by using the = sign to clearly assign the value.

./happydomain -storage-engine=leveldb -leveldb-path=/var/lib/happydomain/db/

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.

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.

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.

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 (not suitable for cloud/shared instance as it’ll access the local file system).

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.

OpenID Connect

happyDomain supports user authentication via the OpenID Connect protocol. If you have an authentication provider (Auth0, Okta, …) or Identity Provider (IdP) software such as Keycloak, Authentik, Authelia, … you can use it with happyDomain, and possibly dispense with the embedded registration and authentication system.

Configuration

To enable OpenID Connect, you’ll need to set the following options:

HAPPYDOMAIN_OIDC_PROVIDER_URL=https://auth.example.com/
HAPPYDOMAIN_OIDC_CLIENT_ID=youClientId
HAPPYDOMAIN_OIDC_CLIENT_SECRET=0a1b2c3d4e6f7A8B9C0D

The PROVIDER_URL setting should be defined to the base URL of your authentication service. The service should expose a settings discovery endpoint (at /.well-known/openid-configuration).

OpenID Connect provider settings

You’ll need to setup a new application in your authentication provider, with the following settings:

• Provider type: OIDC ou OAuth2
• Grant type: Authorization Code
• Application type: Web ou PWA
• Client type: private
• Scopes: openid, profile, email

Also define the allowed callback URL to:

• https://yourHappyDomain.example.com/auth/callback

Connect to a remote BIND server

BIND is an authoritative and recursive DNS server developed by the Internet Systems Consortium.

It is possible to use it with happyDomain through Dynamic DNS (RFC 2136).

This documentation will guide you through configuring BIND to enable Dynamic DNS and connect your domains to happyDomain.

Configure BIND to enable Dynamic DNS

First, you need to edit the main BIND configuration file (usually /etc/named.conf or /etc/bind/named.conf depending on your distribution) to add a secret that will be shared between happyDomain and BIND to authenticate the changes. Then you must indicate which domains will be managed by happyDomain.

Adding a Shared Secret

Under the main key section of your configuration, add the following key:

key "happydomain" {
    algorithm hmac-sha512;
    secret "<SOME_SECRET>";
};

Replace <SOME_SECRET> with a string obtained using openssl rand -base64 48.

Creating an Authorization Rule for happyDomain

In addition to the key, you must specify how the key can be used by defining an ACL and allowing updates from it.

Add the following ACL to your configuration:

acl "happydomain_acl" {
    key happydomain;
};

Allowing Updates for Each Zone

Now that you have created a rule allowing the happydomain key to make changes, you need to indicate to which zones this rule applies.

For each zone, you must add an update-policy statement referencing the happydomain_acl ACL:

For example, for an existing happydomain.org zone, add the update-policy statement as follows:

zone "happydomain.org" {
    type master;
    file "/var/named/happydomain.org.db";
    update-policy {
        grant happydomain_acl name happydomain.org. ANY;
    };
};

The update-policy statement is a list, so you may already have other policies in this list. In this case, just add the grant statement for happydomain_acl.

Allowing Updates for All Zones

If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, you can use a global update-policy in the options section:

options {
    update-policy {
        grant happydomain_acl zonesub ANY;
    };
};

This will apply the update-policy to all zones, allowing the happydomain_acl to update any record.

Apply the Configuration

After modifying the configuration file, reload the BIND service to apply the changes:

rndc reload

Link happyDomain and BIND

Once BIND is well configured, you can link it to happyDomain using the Dynamic DNS connector :

Follow these steps:

1. Navigate to the Dynamic DNS connector on the host selection page in happyDomain.
2. Fill in the form with the address where your BIND server is accessible.
3. Fill in the Key fields with the information from the key section in the BIND configuration:
   • Key Name: corresponds to the key name in BIND’s configuration (e.g., happydomain).
   • Key Algorithm: corresponds to the algorithm (e.g., hmac-sha512).
   • Secret Key: corresponds to the secret.

Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.

By following these steps, you will have configured BIND to work with happyDomain using Dynamic DNS, ensuring secure and authenticated DNS updates.

Connect to a local knot

Knot is an authoritative DNS server developed by the cz.nic association.

It is possible to use it with happyDomain through Dynamic DNS (RFC 2136).

Configure Knot to enable Dynamic DNS

First, you have to edit the main knot configuration file (usually /etc/knot/knot.conf) to add a secret that will be shared between happyDomain and knot to authenticate the changes. Then you have to indicate which domains will be managed by happyDomain.

Adding a shared secret

Under the main key section of your configuration, add the following key:

key:
  [...]
  - id: happydomain
    algorithm: hmac-sha512
    secret: "<SOME_SECRET>"

Obviously replace <SOME_SECRET> with a string as obtained with openssl rand -base64 48.

Creating an authorization rule for happyDomain

In addition to the key, you must specify in the configuration how the key can be used.

To do this, under the main acl section, we add:

acl:
  [...]
  - id: acl_happydomain
    key: happydomain
    action: transfer
    action: update

This associates the key defined just before with the actions transfer and update, respectively to allow retrieving the zone and to update records.

Associate the authorization to each zone

Now that you have created a rule allowing the happydomain key to make changes, you need to indicate to which zones this rule applies.

For each zone, you must add an acl element referencing the acl_happydomain rule:

For example, for an existing happydomain.org zone, we will add the acl line as follows:

zone:
  [...]
  - domain: happydomain.org
    acl:
      - acl_happydomain
    [...]

The acl element is a list, so you may already have other acl elements in this list. In this case you just need to add the acl_happydomain element to the already existing list.

You have to add this acl element for each zone, unless you use the following trick.

Associate the authorization to all zones

If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, instead of the previous section, we will modify the default template:

template:
  - id: default
    acl:
      - acl_happydomain
  [...]

The default template is applied to all zones by default. By doing so, all zones will inherit the acl_happydomain rule.

Apply the configuration

Now that the configuration file has been modified, tell knotd to reload its configuration:

knotc reload

Link happyDomain and knot

Once knot well configured, you can link it to happyDomain using the Dynamic DNS connector :

Then fill in the form with the address where your knot server is accessible, then fill in the different Key fields with the information from the knot’s key section:

• Key Name : corresponds to id in knot’s configuration ;
• Key Algorithm : corresponds to algorithm ;
• Secret Key : corresponds to secret.

Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.

OVH API configuration

In order to manage domains hosted by OVH, an additional configuration step is required.

Authentication to the OVH API works in 2 stages:

1. First, you need to register an application (e.g. happyDomain). An application has an identifier and a secret that must be entered as a happyDomain parameter.
2. For each OVH account you wish to manage, the happyDomain interface redirects you to the OVH page for creating the Consumer key.

The application must be created from an existing OVH account, regardless of whether it has domains or not; it is a matter of identifying the person responsible for implementing the designated application. Access to account data, and in particular to the domains they manage, is via the Consumer key.

For more information, see this page: https://docs.ovh.com/gb/en/api/api-rights-delegation/#application-registration

Register your happyDomain instance with OVH

1. Go to https://api.ovh.com/createApp/.
2. Fill in the form with a name and description that reflects the name and use of your application, e.g. happyDomain.

Once the form has been validated, you’ll get a key and a secret. This information must be specified in the happyDomain configuration:

ovh-application-key

Application key pour l’API d’OVH

ovh-application-secret

Clef secrète pour l’API d’OVH

SOA (Start Of Authority)

The Start of Authority-SOA is the first record of a zone.

TXT

Please, help us to write this Documentation screen

E-Mail

The E-Mail service allows you to define an e-mail server on the zone, as well as the zone settings for sending/receiving e-mails.