The Home page

Your domains

The home page presents the list of all the domains managed by happyDomain, whatever their host:

Click one of the domains to start make changes (add a sub-domain, add a service, …).

Your registries and domain hosts

On the right, you can see the list of the different hosting providers for your:

The hosters of your domains](hosters-list.png)

You can add new host by clicking on the + button in the table header.

Clicking on a row in this table will filter the list of domains to show only domains managed by this host.

You will also see, if the host allows you to list the domains that belong to you, the domains that you can add to happyDomain:

To view the entire list again, simply click on the selected host again.

Modify or remove a host

If you find an error or no longer need a hosting provider, click on the … on the line of the host concerned. You will then be able to choose between update information or delete the host:

Note that you will not be able to remove the host as long as domains referring to it exist in the list on the left.

Add a domain

You have a new domain you want to manage in happyDomain? Start by entering its name in the field below the list. You will then be guided to the [to choose the host] screen (/en/pages/domain-new/).

The field does not show when a host is selected on the right. Unless this host does not allow to list:

In this case, validating the field will automatically search for the new domain with the selected host, as indicated by the message just above the field.

Hosting providers

You can access this page by clicking on the the top menu link “The hosts of my domains”.

Your registries and domain hosts

This page shows only the list of registries and domain hosts you have added to your account, and allows you to add more.

You can add a new host by clicking on the “+” button at the top of the page.

By clicking on a row of the table, you will access the parameters used by happyDomain to contact this host. This is where you’ll be able to modify the name you gave to this host, and where you’ll be able to modify the access parameters.

Add a provider

You access this screen by clicking on the “My domain providers” link in the top menu, then by clicking on the “+ Add a new domain host” button.

Compatible registries and domain hosts

When you want to add a domain, the first step is to determine at which host it is located.

In this screen, you will be asked to select the host among the list of compatible hosts where you have your:

Once you have selected it, you are directed to the Host connection settings screen.

More will be added later, if you can’t find yours, contact us!

Hosting provider settings

You access this screen either:

• when you want to add a host, after having selected the provider,
• when you want to change the connection settings between happyDomain and a host, for example on the home page.

Connection name

In order to find you among the different hosts, the first field you are asked for is a name. This name will only be used to allow you to easily identify the host of your domain, if you have several.

Other fields

Each host needs different information to establish a connection with happyDomain. Follow the instructions on each screen.

Add a domain

You reach this screen after having validated on home page the form to add a domain (and you didn’ previously selected a host in the right filter).

Hosting provider selection

You can see on this screen the different hosts you have already configured. If your domain is part of one of the listed accounts, just click on it, it will be added automatically.

If you haven’t added the host yet, you can do it now by following the link “Add now!”.

Your domain

Need help to write this Documentation page

My account

You access this page by clicking on the top menu “My Account” link.

Account Settings

The screen is divided into three parts. The first one will allow you to change the settings related to your account: such as the language of the interface or the way the contextual help is displayed.

Change password

The second part of the screen allows you to change the password.

Change account email address

It is currently not possible to change the email address of your account. We invite you to contact us if you wish to change it.

Delete your account

The last part of the page allows you to delete your happyDomain account.

Once the deletion is validated, your account will no longer be accessible and all data belonging to you will be deleted shortly after, during a regular database cleanup.

From the moment you delete your account, your domains will continue to respond according to the last update you made on happyDomain. The deletion will not affect the distributed data.

Tools: the DNS resolver

Please, help us to write this Documentation page

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.

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

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

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

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 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