Testing or local single-user environment

Follow this installation guide if you want to use happyDomain directly on your machine, as simply as possible, without user management.

This is a simple configuration, suitable for evaluating happyDomain or for using it without authentication on your own machine, or with authentication provided by a reverse proxy.

You can deploy it using Docker or by downloading one of the available executables. Both methods are described below.

Via Docker/podman

If you are familiar with Docker (or podman), you can have happyDomain up and running in seconds with the following command:

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

If you want to make the data persistent, you need to add a volume:

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

Whatever your choice, go to http://localhost:8081 to start using happyDomain.

Via the executable

1. Start by downloading the executable matching your processor architecture from: https://get.happydomain.org/master/. The darwin versions are for macOS, while the linux versions are for GNU/Linux. All distributed versions are static and should work regardless of your libc (GNU libc in most cases, musl for Alpine, …).

2. Make the binary you downloaded executable: chmod +x happydomain-OS-ARCH.

3. Run the binary: HAPPYDOMAIN_NO_AUTH=1 ./happydomain-OS-ARCH.

4. Go to http://localhost:8081/ to start using happyDomain.

What do these options do?

The HAPPYDOMAIN_NO_AUTH=1 option is a parameter that tells happyDomain not to require authentication: domains are shared among all incoming connections. In practice, this automatically creates a default user and disables all login, account registration, and related features.

Can I expose it on the Internet like this?

No! It is essential that you do not expose your happyDomain instance on the Internet without authentication. Without it, all its content would be accessible to anyone, and they could take control of your domain(s).

Always use a reverse proxy such as nginx, Apache, HAproxy, Traefik, … adding a filtering or basic authentication step.

For example, you can filter the IPs that can access the service. Here is a sample nginx configuration filtering IPs (using the allow directive):

server {
    listen 80;
    listen [::]:80;

    server_name happydomain.example.com;

    location / {
        allow 42.42.42.42;
        deny all;

        proxy_pass	http://localhost:8081;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
    }

}

You can also add basic password authentication.

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.

Writing a happyDomain Plugin

happyDomain supports external test plugins — shared libraries (.so files) that add domain or service health checks to a running instance. Plugins are loaded at startup without recompiling the server; the operator simply drops a .so file into a configured directory.

How it works

A plugin receives a set of options assembled from several configuration scopes, runs a check (HTTP call, DNS query, …), and returns a result with a status level and an optional detailed report. Results are stored and displayed in the happyDomain UI alongside the domain or service they concern.

When happyDomain starts it scans every directory listed in the plugins-directories configuration option. For each file it finds, it:

1. Opens the shared library.
2. Looks up the exported symbol NewTestPlugin.
3. Calls NewTestPlugin() to obtain a plugin value.
4. Registers the plugin under each name returned by PluginEnvName().

If the file is not a valid Go plugin, if NewTestPlugin is missing, or if it returns an error, a warning is logged and the file is skipped. The server always starts regardless of individual plugin load failures.

The TestPlugin interface

Every plugin must implement four methods:

type TestPlugin interface {
    PluginEnvName() []string
    Version()          PluginVersionInfo
    AvailableOptions() PluginOptionsDocumentation
    RunTest(PluginOptions, map[string]string) (*PluginResult, error)
}

Project structure

A plugin is a standalone Go module compiled with -buildmode=plugin. It must be in package main and export exactly one symbol:

func NewTestPlugin() (happydns.TestPlugin, error)

Recommended layout:

myplugin/
├── go.mod
├── Makefile
└── plugin.go       # (or split across multiple .go files)

go.mod

module git.happydns.org/happyDomain/plugins/myplugin

go 1.25

require git.happydns.org/happyDomain v0.0.0
replace git.happydns.org/happyDomain => ../../

The replace directive points to your local happyDomain checkout, ensuring the plugin is compiled against the exact same types as the server.

Entry point

package main

import "git.happydns.org/happyDomain/model"

func NewTestPlugin() (happydns.TestPlugin, error) {
    return &MyPlugin{}, nil
}

The constructor is a good place to perform one-time initialisation (open config files, create an HTTP client, …). Return an error if the plugin cannot function.

Naming — PluginEnvName()

Returns one or more short, lowercase identifiers. These names are used to look up the plugin via the API and to key its stored configuration.

func (p *MyPlugin) PluginEnvName() []string {
    return []string{"myplugin"}
}

Choose names that are unlikely to collide (e.g. "zonemaster", "matrixim") and keep them stable across versions because they are persisted alongside user configuration. If two loaded plugins claim the same name, the second one is skipped and a conflict is logged.

Version and availability — Version()

Describes the plugin and controls where it appears in the UI:

func (p *MyPlugin) Version() happydns.PluginVersionInfo {
    return happydns.PluginVersionInfo{
        Name:    "My Plugin",
        Version: "1.0",
        AvailableOn: happydns.PluginAvailability{
            ApplyToDomain:    true,
            ApplyToService:   false,
            LimitToProviders: nil,  // nil or empty = all providers
            LimitToServices:  []string{"abstract.MatrixIM"},
        },
    }
}

Both ApplyToDomain and ApplyToService may be true simultaneously.

Options — AvailableOptions()

Options are key/value pairs (map[string]any) that configure each test run. They are declared grouped by scope, i.e. who sets them and how long they persist:

func (p *MyPlugin) AvailableOptions() happydns.PluginOptionsDocumentation {
    return happydns.PluginOptionsDocumentation{
        RunOpts:     []happydns.PluginOptionDocumentation{ /* … */ },
        ServiceOpts: []happydns.PluginOptionDocumentation{ /* … */ },
        DomainOpts:  []happydns.PluginOptionDocumentation{ /* … */ },
        UserOpts:    []happydns.PluginOptionDocumentation{ /* … */ },
        AdminOpts:   []happydns.PluginOptionDocumentation{ /* … */ },
    }
}

Option scopes

Before RunTest is called, happyDomain merges all scoped values from least specific (admin) to most specific (run-time). More-specific values silently override less-specific ones. RunTest always receives a single flat map and does not need to know which scope each value came from.

Option fields

Each option is a PluginOptionDocumentation (an alias for Field):

Auto-fill

When AutoFill is set, happyDomain populates the field from the test context; the user is not prompted:

{
    Id:       "domainName",
    Type:     "string",
    Label:    "Domain name",
    AutoFill: happydns.AutoFillDomainName,
    Required: true,
}

Running the check — RunTest()

RunTest receives the merged option map and a metadata map (reserved for future use), performs the check, and returns a PluginResult.

Always assert option values to a concrete type before use — the map holds any:

func (p *MyPlugin) RunTest(opts happydns.PluginOptions, _ map[string]string) (*happydns.PluginResult, error) {
    domain, ok := opts["domainName"].(string)
    if !ok || domain == "" {
        return nil, fmt.Errorf("domainName option is required")
    }

    // … perform the check …

    return &happydns.PluginResult{
        Status:     happydns.PluginResultStatusOK,
        StatusLine: "All good",
        Report:     myStructuredReport,
    }, nil
}

Return a non-nil error only for unexpected failures (network errors, invalid configuration). For expected check failures — the monitored service is down, DNS records are wrong — return a PluginResult with an appropriate status and a human-readable StatusLine.

Result fields

Status levels (worst → best)

Building

go build -buildmode=plugin -o happydomain-plugin-test-myplugin.so \
    git.happydns.org/happyDomain/plugins/myplugin

Minimal Makefile:

PLUGIN_NAME=myplugin
TARGET=../happydomain-plugin-test-$(PLUGIN_NAME).so

all: $(TARGET)

$(TARGET): *.go
	go build -buildmode=plugin -o $@ git.happydns.org/happyDomain/plugins/$(PLUGIN_NAME)

The prefix happydomain-plugin-test- is a convention; happyDomain loads every file in the plugin directories regardless of its name.

Deployment

1. Copy the .so file

cp happydomain-plugin-test-myplugin.so /usr/lib/happydomain/plugins/

2. Point happyDomain at the directory

happydomain.conf:

plugins-directories=/usr/lib/happydomain/plugins

Environment variable:

HAPPYDOMAIN_PLUGINS_DIRECTORIES=/usr/lib/happydomain/plugins

Multiple directories may be listed as a comma-separated value.

3. Check the logs

On a successful load:

Plugin My Plugin loaded (version 1.0)

On a name conflict or load error a warning is logged with the filename and reason.

Reference implementations

Two plugins are bundled in this directory:

• matrix/ — queries the Matrix federation tester API. Demonstrates ApplyToService with LimitToServices and AdminOpts for the backend URL.
• zonemaster/ — drives the Zonemaster JSON-RPC API, polls for completion, and maps results to severity levels. Demonstrates AutoFillDomainName, UserOpts for language selection, and multi-level status mapping.