CloudHost/zonemaster.es
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add full Zonemaster stack with Docker and Spanish UI

Browse Source 
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI)
- Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend
- Dockerfile.gui: Astro static build served via nginx
- docker-compose.yml: backend (internal) + frontend (port 5353)
- nginx.conf: root redirects to /es/, /api/ proxied to backend
- zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Malin
2026-04-21 08:19:24 +02:00
commit 8d4eaa1489
1567 changed files with 204155 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
zonemaster/docs/public/configuration/README.md Normal file
View File

@@ -0,0 +1,17 @@
# Configuration
This section contains information about configuration of the different components
of Zonemaster:
* Setting up or modifying the [profile] in Zonemaster-Engine.
* Enabling the Zonemaster-Engine [global cache] feature.
* Configuring Zonemaster-Backend in the [Backend configuration file].
* Using [environment variables] for Zonemaster-Backend.
* Configuring Zonemaster-GUI in the [GUI configuration section].
[profile]: profiles.md
[global cache]: global-cache.md
[Backend configuration file]: backend.md
[environment variables]: backend-environment-variables.md
[GUI configuration section]: gui/README.md

35
zonemaster/docs/public/configuration/backend-environment-variables.md Normal file
View File

@@ -0,0 +1,35 @@
# Environment variables
## Variable used by both RPCAPI daemon and Test Agent daemon
* `ZONEMASTER_BACKEND_CONFIG_FILE`: Set a custom path for the backend
configuration file.
## Variables used by RPCAPI daemon only
* `ZM_BACKEND_RPCAPI_LOGLEVEL`: Configure the log level, `trace` by default.
Accepted values are:
* `trace`
* `debug`
* `info` (also accepted: `inform`)
* `notice`
* `warning` (also accepted: `warn`)
* `error` (also accepted: `err`)
* `critical` (also accepted: `crit`, `fatal`)
* `alert`
* `emergency`
* `ZM_BACKEND_RPCAPI_LOGJSON`: Setting it to any thruthy value (non-empty
string or non-zero number) will configure the logger to log in JSON format,
undefined by default.
## Variables used by unit test scripts
* `TARGET`: Set the database to use. If empty or undefined, "SQLite" will be
assumed. Accepted values are:
* `SQLite`
* `PostgreSQL`
* `MySQL`
* `ZONEMASTER_RECORD`: Setting it to any thruthy value (non-empty string or
non-zero number) will record the data from the test to a file. Otherwise the
data is loaded from a file.

415
zonemaster/docs/public/configuration/backend.md Normal file
View File

@@ -0,0 +1,415 @@
# Configuration
## Table of contents
* [Introduction](#introduction)
* [RPCAPI section](#rpcapi-section)
* [enable_batch_create](#enable_batch_create)
* [enable_user_create](#enable_user_create)
* [enable_add_batch_job](#enable_add_batch_job)
* [enable_add_api_user](#enable_add_api_user)
* [DB section](#db-section)
* [engine](#engine)
* [polling_interval](#polling_interval)
* [MYSQL section](#mysql-section)
* [host](#host)
* [port](#port)
* [user](#user)
* [password](#password)
* [database](#database)
* [POSTGRESQL section](#postgresql-section)
* [host](#host-1)
* [port](#port-1)
* [user](#user-1)
* [password](#password-1)
* [database](#database-1)
* [SQLITE section](#sqlite-section)
* [database_file](#database_file)
* [LANGUAGE section](#language-section)
* [locale](#locale)
* [METRICS section](#metrics-section)
* [statsd_host](#statsd_host)
* [statsd_port](#statsd_port)
* [PUBLIC PROFILES and PRIVATE PROFILES sections](#public-profiles-and-private-profiles-sections)
* [ZONEMASTER section](#zonemaster-section)
* [max_zonemaster_execution_time](#max_zonemaster_execution_time)
* [number_of_processes_for_frontend_testing](#number_of_processes_for_frontend_testing)
* [number_of_processes_for_batch_testing](#number_of_processes_for_batch_testing)
* [lock_on_queue](#lock_on_queue)
* [age_reuse_previous_test](#age_reuse_previous_test)
## Introduction
Zonemaster *Backend* is configured in
`/etc/zonemaster/backend_config.ini` (Linux) or
`/usr/local/etc/zonemaster/backend_config.ini` (FreeBSD). Following
[Installation instructions] will create the file with factory settings.
Restart the `zm-rpcapi` and `zm-testagent` daemons to load the changes
made to the `backend_config.ini` file.
The `backend_config.ini` file uses a file format in the INI family that is
described in detail [here][File format].
Repeating a key name in one section is forbidden.
Each section in `backend_config.ini` is documented below.
In addition to the configuration file, some settings can configured using
[environment variables][Environment Variables].
## RPCAPI section
Available keys: `enable_batch_create`, `enable_user_create`,
`enable_add_batch_job`, `enable_add_api_user`.
### enable_add_batch_job
Boolean value to enable the `add_batch_job` and `batch_create` methods of the API.
Accepted values: `true` or `false` (or `yes` or `no`),
default to `true` (enabled).
**Deprecated:** The `yes`/`no` values are deprecated and will be rejected in
v2026.2.
Use `true`/`false` instead.
### enable_add_api_user
Boolean value to enable the `add_api_user` and `user_create` method of the API.
Accepted values: `true` or `false` (or `yes` or `no`),
default to `false` (disabled).
**Deprecated:** The `yes`/`no` values are deprecated and will be rejected in
v2026.2.
Use `true`/`false` instead.
### enable_batch_create
An experimental alias for [enable_add_batch_job][RPCAPI.enable_add_batch_job].
### enable_user_create
An experimental alias for [enable_add_api_user][RPCAPI.enable_add_api_user].
## DB section
Available keys : `engine`, `user`, `password`, `database_name`,
`database_host`, `polling_interval`.
### engine
Specifies what database engine to use.
The value must be one of the following, case-insensitively: `MySQL`,
`PostgreSQL` and `SQLite`.
This table declares what value to use for each supported database engine.
Database Engine | Value
------------------|------
MariaDB | `MySQL`
MySQL | `MySQL`
PostgreSQL | `PostgreSQL`
SQLite | `SQLite`
### polling_interval
A strictly positive decimal number. Max 5 and 3 digits in the integer and fraction
components respectively.
Time in seconds between database lookups by Test Agent.
Default value: `0.5`.
## MYSQL section
Available keys : `host`, `port`, `user`, `password`, `database`.
### host
An [LDH domain name] or IP address.
The host name of the machine on which the MySQL server is running.
### port
The port the MySQL server is listening on.
Default value: `3306`.
If [MYSQL.host] is set to `localhost` (but neither `127.0.0.1` nor `::1`),
then the value of the [MYSQL.port] property is discarded as the driver
connects using a UNIX socket (see the [DBD::mysql documentation]).
### user
An ASCII-only [MariaDB unquoted identifier].
Max length [80 characters][MariaDB identifier max lengths].
The name of the user with sufficient permission to access the database.
### password
A string of [US ASCII printable characters].
The first character must be neither space nor `<`.
Max length 100 characters.
The password of the configured user.
### database
A US ASCII-only [MariaDB unquoted identifier].
Max length [64 characters][MariaDB identifier max lengths].
The name of the database to use.
## POSTGRESQL section
Available keys : `host`, `port`, `user`, `password`, `database`.
### host
An [LDH domain name] or IP address.
The host name of the machine on which the PostgreSQL server is running.
### port
The port the PostgreSQL server is listening on.
Default value: `5432`.
### user
A US ASCII-only [PostgreSQL identifier]. Max length 63 characters.
The name of the user with sufficient permission to access the database.
### password
A string of [US ASCII printable characters].
The first character must be neither space nor `<`.
Max length 100 characters.
The password of the configured user.
### database
A US ASCII-only [PostgreSQL identifier]. Max length 63 characters.
The name of the database to use.
## SQLITE section
Available keys : `database_file`.
### database_file
An absolute path.
The full path to the SQLite main database file.
## LANGUAGE section
The LANGUAGE section has one key, `locale`.
### locale
A string representing a space-separated list of one or more `locale tags`.
Each tag consists of a two-lowercase-letter language code, an underscore
character, and a two-uppercase-letter country code (i.e. it matches the regular
expression `/^[a-z]{2}_[A-Z]{2}$/`).
Each `locale tag` must have a unique language code.
Default value: `en_US`.
#### Design
The language code of a `locale tag` is intended to be an [ISO 639-1] code.
The country code is intended to be an [ISO 3166-1 alpha-2] code.
A `locale tag` is a locale setting for the available translation
of messages without ".UTF-8", which is implied.
#### Usage
Removing a language from the configuration file just blocks that
language from being allowed.
English is the Zonemaster default language, but it can be blocked
from being allowed by RPC-API by including some `locale tag` in the
configuration, but none starting with language code for English ("en").
#### Out-of-the-box support
The default installation and configuration supports the
following languages.
Language | Locale tag value | Language code | Locale value used
---------|------------------|---------------|------------------
Danish | da_DK | da | da_DK.UTF-8
English | en_US | en | en_US.UTF-8
Spanish | es_ES | es | es_ES.UTF-8
Finnish | fi_FI | fi | fi_FI.UTF-8
French | fr_FR | fr | fr_FR.UTF-8
Norwegian| nb_NO | nb | nb_NO.UTF-8
Slovenian| sl_SI | sl | sl_SI.UTF-8
Swedish | sv_SE | sv | sv_SE.UTF-8
Setting in the default configuration file:
```
locale = da_DK en_US es_ES fi_FI fr_FR nb_NO sl_SI sv_SE
```
#### Installation considerations
If a new `locale tag` is added to the configuration then the equivalent
MO file should be added to Zonemaster-Engine at the correct place so
that gettext can retrieve it, or else the added `locale tag` will not
add any actual language support. The MO file should be created for the
`language code` of the `locale tag` (see the table above), not the entire
`locale tag`. E.g. if the `locale` configuration key includes "sv_SE" then
a MO file for "sv" should be included in the installation.
Use of MO files based on the entire `locale tag` is *deprecated*.
See the [Zonemaster-Engine share directory] for the existing PO files that are
converted to MO files during installation. (Here we should have a link
to documentation instead.)
Each locale set in the configuration file, including the implied
".UTF-8", must also be installed or activate on the system
running the RPCAPI daemon for the translation to work correctly.
## METRICS section
### statsd_host
An [LDH domain name] or IP address.
The host name of the machine on which the StatsD receiver is running.
Leave unspecified to disable the metrics.
Note that this feature requires the `Net::Statsd` module to be installed.
### statsd_port
The port the StatsD receiver is listening on.
Default value: `8125`.
## PUBLIC PROFILES and PRIVATE PROFILES sections
The PUBLIC PROFILES and PRIVATE PROFILES sections together define the available [profiles].
Keys in both sections are `profile names`, and values are absolute file system
paths to [profile JSON files]. The key must conform to the character limitation
specified for `profile name` as specified in the API document
[Profile name section]. Keys that only differ in case are considered to be equal.
Keys must not be duplicated between or within the sections, and the key
`default` must not be present in the PRIVATE PROFILES section.
There is a `default` profile that is special. It is always available even
if not specified. If it is not explicitly mapped to a profile JSON file, it is implicitly
mapped to the [Zonemaster Engine default profile].
Each profile JSON file contains a (possibly empty) set of overrides to
the *Zonemaster Engine default profile*. Specifying a profile JSON file
that contains a complete set of profile data is equivalent to specifying
a profile JSON file with only the parts that differ from the *Zonemaster
Engine default profile*.
Specifying a profile JSON file that contains no profile data is equivalent
to specifying a profile JSON file containing the entire
*Zonemaster Engine default profile*.
## ZONEMASTER section
The ZONEMASTER section has several keys :
* max_zonemaster_execution_time
* number_of_processes_for_frontend_testing
* number_of_processes_for_batch_testing
* lock_on_queue
* age_reuse_previous_test
### max_zonemaster_execution_time
A strictly positive integer. Max length 5 digits.
Time in seconds before reporting an unfinished test as failed.
Default value: `600`.
### number_of_processes_for_frontend_testing
A strictly positive integer. Max length 5 digits.
Number of processes allowed to run in parallel (added with
`number_of_processes_for_batch_testing`).
Default value: `20`.
Despite its name, this key does not limit the number of process used by the
frontend, but is used in combination of
`number_of_processes_for_batch_testing`.
### number_of_processes_for_batch_testing
A non-negative integer. Max length 5 digits.
Number of processes allowed to run in parallel (added with
`number_of_processes_for_frontend_testing`).
Default value: `20`.
Despite its name, this key does not limit the number of process used by any
batch pool of tests, but is used in combination of
`number_of_processes_for_frontend_testing`.
### lock_on_queue
A non-negative integer. Max length 5 digits.
A label to associate a test to a specific Test Agent.
Default value: `0`.
### age_reuse_previous_test
A strictly positive integer. Max length 5 digits.
The shelf life of a test in seconds after its creation.
Default value: `600`.
If a new test is requested for the same zone name and parameters within the
shelf life of a previous test result, that test result is reused.
Otherwise a new test request is enqueued.
[API documentation]: ../using/backend/api.md
[DBD::mysql documentation]: https://metacpan.org/pod/DBD::mysql#host
[Default JSON profile file]: https://github.com/zonemaster/zonemaster-engine/blob/master/share/profile.json
[Environment Variables]: backend-environment-variables.md
[File format]: https://metacpan.org/pod/Config::IniFiles#FILE-FORMAT
[ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
[ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1
[Installation instructions]: ../installation/zonemaster-backend.md
[Language tag]: ../using/backend/api.md#language-tag
[LDH domain name]: https://datatracker.ietf.org/doc/html/rfc3696#section-2
[MariaDB identifier max lengths]: https://mariadb.com/kb/en/identifier-names/#maximum-length
[MariaDB unquoted identifier]: https://mariadb.com/kb/en/identifier-names/#unquoted
[MYSQL.host]: #host
[MYSQL.port]: #port
[PostgreSQL identifier]: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
[Profile JSON files]: profiles.md
[Profile name section]: ../using/backend/rpcapi-reference.md#profile-name
[Profiles]: https://github.com/zonemaster/zonemaster-backend/blob/master/docs/Architecture.md#profile
[RPCAPI.enable_add_api_user]: #enable_add_api_user
[RPCAPI.enable_add_batch_job]: #enable_add_batch_job
[RPCAPI.enable_batch_create]: #enable_batch_create
[RPCAPI.enable_user_create]: #enable_user_create
[SQLITE.database_file]: #database_file
[US ASCII printable characters]: https://en.wikipedia.org/wiki/ASCII#Printable_characters
[Zonemaster-Engine share directory]: https://github.com/zonemaster/zonemaster-engine/tree/master/share
[Zonemaster::Engine::Profile]: https://metacpan.org/pod/Zonemaster::Engine::Profile#PROFILE-PROPERTIES
[Zonemaster Engine default profile]: profiles.md#default-profile

123
zonemaster/docs/public/configuration/global-cache.md Normal file
View File

@@ -0,0 +1,123 @@
# Configuration: Global cache in Zonemaster-Engine
## Table of contents
* [Introduction](#introduction)
* [Prerequisites](#prerequisites)
* [Installation for global cache](#installation-for-global-cache)
* [Create directory for custom profile](#create-directory-for-custom-profile)
* [Enable global cache](#enable-global-cache)
* [Using global cache](#using-global-cache)
## Introduction
Global cache is a feature that can increase performance when many tests are run
within a short time frame, especially when they share some data such as using the
same name server names. The global cache is meant for batch testing rather than
single tests through the GUI. In the latter case it is desirable that Zonemaster
checks again since the zone may have been corrected due to the report in a very
recent test.
The global cache improves the caching function by making the DNS lookups from
one test to be available for further tests. The cache is stored in `Redis`, a
cache service running in a separate daemon.
To enable global caching, additional software has to be installed and custom
profile has to be created, where global caching is enabled.
## Prerequisites
Before installing or enabling global cache you must follow the
[Zonemaster::Engine installation] first. The feature is available from version
`v5.0.0` of Zonemaster-Engine.
For installation on FreeBSD being user root is assumed.
## Installation for global cache
Install the `Redis` daemon and needed Perl library. And then start the `Redis`
daemon. It will listen to localhost and default port.
### Rocky Linux
```
sudo dnf --assumeyes install redis perl-Redis perl-Data-MessagePack
sudo systemctl enable redis
sudo systemctl start redis
```
### Debian and Ubuntu
```
sudo apt install redis libredis-perl libdata-messagepack-perl
sudo systemctl enable redis
sudo systemctl start redis
```
### FreeBSD
```
pkg install -y redis p5-Redis p5-Data-MessagePack
sysrc redis_enable="YES"
service redis start
```
## Create directory for custom profile
Create a directory to be used for a custom profile, which is here the same
directory as used by Zonemaster-Backend. And then copy the default profile
to this directory.
### Rocky Linux, Debian and Ubuntu
```
test -d /etc/zonemaster || sudo mkdir -v /etc/zonemaster
perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . | sudo tee /etc/zonemaster/profile.json > /dev/null
```
### FreeBSD
```
test -d /usr/local/etc/zonemaster || mkdir -v /usr/local/etc/zonemaster
perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . > /usr/local/etc/zonemaster/profile.json
```
## Enable global cache
If there is no `profile.json` in `/etc/zonemaster/` (or `/usr/local/etc/zonemaster/`
for FreeBSD), create it by extracting the default profile using the command in the
[profile documentation].
Update `/etc/zonemaster/profile.json` (or `/usr/local/etc/zonemaster/profile.json`
for FreeBSD) by adding a cache section. If the profile already has an empty cache
section (i.e. `"cache": {}`) then it must be removed. Add the following section,
```
"cache": {
"redis": {
"server": "127.0.0.1:6379",
"expire": 7200
}
},
```
The `expire` value can be increased or decreased to increase or decrease the time
in seconds that `Redis` will cache the data. Caching of specific DNS data is
never longer than the normal DNS TTL value.
## Using global cache
If [Zonemaster-CLI][Zonemaster::CLI installation] has been installed, then
run `zonemaster-cli` with `--profile /etc/zonemaster/profile.json`
(or `--profile /usr/local/etc/zonemaster/profile.json` for FreeBSD) to use the
global cache. Caching will persist between test unless it has expired.
See `man zonemaster-cli` and look for `cli.args` for how to make it the custom
profile being the default profile for `zonemaster-cli`.
See [Zonemaster::Backend configuration] for how to make the custom profile being
used for Zonemaster-Backend and Zonemaster-GUI.
For more documentation on profiles, see [profile documentation].
[profile documentation]: profiles.md
[Zonemaster::Backend configuration]: backend.md
[Zonemaster::CLI installation]: ../installation/zonemaster-cli.md
[Zonemaster::Engine installation]: ../installation/zonemaster-engine.md

20
zonemaster/docs/public/configuration/gui/README.md Normal file
View File

@@ -0,0 +1,20 @@
# GUI Configuration
This section contains information about configuration of the GUI component.
* [Run-time configuring Zonemaster-GUI using "config.json"] is currently limited
to creating or updating a message banner.
* [Simple build-time configuring Zonemaster-GUI using "config.ts"] lists
basic configuration options of Zonemaster-GUI.
* [Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"] can
change the look-and-feel of Zonemaster-GUI.
* [Configuring Zonemaster-GUI using Theming] gives further instructions for how
to customize Zonemaster-GUI.
* [Build a custom Zonemaster-GUI installation package]
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]: configuring-using-tsconfig-json.md
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Configuring Zonemaster-GUI using Theming]: configuring-using-theming.md
[Run-time configuring Zonemaster-GUI using "config.json"]: configuring-using-config-json.md
[Simple build-time configuring Zonemaster-GUI using "config.ts"]: configuring-using-config-ts.md

173
zonemaster/docs/public/configuration/gui/building-custom-gui.md Normal file
View File

@@ -0,0 +1,173 @@
# Build a custom Zonemaster-GUI installation package
## Background
If you follow the [Zonemaster-GUI installation instructions] you can install an
official package, and skip the instructions in this document.
However, if you have created a custom [config.ts], done theme settings in
[tsconfig.json] or done some [theme updates] then you must create a custom
installation package for your custom installation. That can be achieved by
following the steps below.
It is also important to state that even though the installation package is
created on Ubuntu 22.04 below, the resulting installation package can be
installed on at least all OSs supported in the
[Zonemaster-GUI installation instructions].
## Prepare build environment
Start by creating a build environment. Here we assume and base it on
[Ubuntu] version 22.04. The instructions will probably work with other versions
of Ubuntu, or with other Linux distributions or other OSs, but then you might
need to adapt some of the commands. Note however that it is important that the
system fully supports [npm].
### Install toolchain
1. Make a clean installation of Ubuntu 22.04.
2. Update the package database and install Curl and Git.
```sh
sudo apt-get update
sudo apt-get install curl git
```
3. Install Node.js by using [NVM], a node version manager.
```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
```
4. After installation, log out and log in again to handle [known issue], or just:
```sh
source ~/.bashrc
```
5. Install the supported Node.js version
```sh
nvm install 24
```
6. Switch to the previously installed version
```sh
nvm use 24
```
## Check out source code
You need to checkout the source code of Zonemaster-GUI. In the usual case
you will start with the `master` branch latest Zonemaster-GUI release as
shown below.
```sh
git clone -b master https://github.com/zonemaster/zonemaster-gui.git
cd zonemaster-gui
```
If you already have a clone, make sure that you start from an up-to-date `master`
branch.
```sh
git checkout master
git fetch --all
git pull
```
## Add customization
From there, you can start to do your own customization. The simplest case only
requires an update to [config.ts]. See the [GUI Configuration][README] overview
for more details.
You should then save any changed file by doing the following steps (see
[Git tutorial]).
```sh
git checkout -b MY-BRANCH
git add FILE
git commit -m 'What did I do?'
```
## Build installation package
When building you should have a clean repository. Clean means that all temporary
(i.e. non-versioned) files are removed.
1. List all files and changes that will be removed with next step.
```sh
git status --ignored
```
2. Remove all files and changes not included in a Git branch (listed in
previous step).
```sh
git clean -dfx
git reset --hard
```
3. Install [npm] libraries in the repository.
```sh
npm install
```
4. Build the Zonemaster-GUI.
```sh
npm run build
```
5. If building fails, go back to the "[Install toolchain]" section and repeat the
two `nvm` commands and restart building.
6. Build a Zonemaster-GUI installation package (a zip file).
```sh
npm run release
```
If all steps worked well, there will be a zip file in the current repository that
can be used for installation, i.e. by replacing the official installation package
(zip file) with this new zip file in the [Zonemaster-GUI installation instructions].
If the build step above fails, go back to a safe branch and add your updates one
by one, and repeating steps 1-5.
## Testing the Build Locally
To test the static build locally, it must be served from the root path (/). You
can use any static server. Here are two common options, and note that
additional software has to be installed for those:
```sh
python3 -m http.server 8000 --directory ./public
```
```sh
php -S localhost:8000 -t ./public
```
Ensure you're serving the ./public directory (or your build output folder) as
the root for all assets and routing to work correctly.
[Git tutorial]: https://git-scm.com/docs/gittutorial
[Known issue]: https://github.com/nvm-sh/nvm#troubleshooting-on-linux
[NPM]: https://www.npmjs.com/
[NVM]: https://github.com/nvm-sh/nvm
[Node.js]: https://nodejs.org/en
[README]: README.md
[Ubuntu]: https://ubuntu.com/
[Zonemaster-GUI installation instructions]: ../../installation/zonemaster-gui.md
[config.ts]: configuring-using-config-ts.md
[tsconfig.json]: configuring-using-tsconfig-json.md
[theme updates]: configuring-using-theming.md
[Install toolchain]: #install-toolchain

66
zonemaster/docs/public/configuration/gui/configuring-using-config-json.md Normal file
View File

@@ -0,0 +1,66 @@
# Run-time configuring Zonemaster-GUI using "config.json"
The `config.json` configuration file can be used for *run-time* settings of the
Zonemaster-GUI, i.e. no rebuild of the installation package is needed.
Currently, the only supported setting is creating, updating or removing a message
banner. Other types of configuration require a rebuild of the GUI, and are covered
in sibling documents of this document.
## Finding "config.json"
In the source tree the file is found as `static/config.json` relative to the
root of the Git tree.
In a default installation, the file is found as
`/var/www/html/zonemaster-web-gui/dist/config.json`.
## Reloading GUI after update
When the Web browser reloads the GUI, e.g. after running a new test, the
changes are displayed by the GUI.
## Default "config.json" file
The `config.json` file contains configuration that is loaded at runtime.
Currently, it includes settings for displaying banner messages in different
languages:
```json
{
"msgBanner": {
"en": "",
"sv": "",
"da": "",
"es": "",
"fi": "",
"fr": "",
"nb": ""
}
}
```
### Configuration Options
* **msgBanner**: An object containing message banner text for each supported
language. These messages can be used to display important announcements or
notifications to users in their preferred language.
The message banner is shown just below the top menu on all pages.
The string is set for each language, and may contain HTML code such as `<br>` or
even `<a href>` if necessary. Take note not to break quoting as JSON requires
quoting with `""` around the string.
To display a message banner, simply add the message text to the corresponding
language key. E.g.:
```json
{
"msgBanner": {
"en": "Scheduled system maintenance on 2025-12-09 from 10:00 to 12:00 UTC.",
"sv": "Planerat systemunderhåll den 9 december 2025 kl. 10.00–12.00 UTC."
}
}
```

117
zonemaster/docs/public/configuration/gui/configuring-using-config-ts.md Normal file
View File

@@ -0,0 +1,117 @@
# Simple build-time configuring Zonemaster-GUI using "config.ts"
The `config.ts` configuration file can be used for *build-time* settings of
the Zonemaster-GUI. Any changes to this file require a rebuild of the
installation package.
## Finding "config.ts"
In the source tree the file is found as `config.ts` relative to the root of
the Git tree. The installed GUI does not ship with this file, because the
values defined in this file are baked in the GUI’s HTML and JavaScript files.
## Rebuilding Zonemaster-GUI after update
When `config.ts` is updated, Zonemaster-GUI has to be rebuilt. See
[Build a custom Zonemaster-GUI installation package] for how to get the source
tree and building a custom installation package.
## Default "config.ts" file
The `config.ts` file is the central configuration file for the Zonemaster-GUI
application. It defines various settings that control the behavior and appearance
of the application.
```typescript
import type { Config } from '@/types.ts';
import packageJson from './package.json';
const config: Config = {
defaultLanguage: 'en',
enabledLanguages: ['da', 'en', 'es', 'fi', 'fr', 'nb', 'sv', 'sl'],
baseUrl: import.meta.env.PUBLIC_BASE_URL || '/',
apiBaseUrl: import.meta.env.PUBLIC_API_URL || '/api',
pollingInterval: import.meta.env.PUBLIC_POLLING_INTERVAL || 5000,
clientInfo: {
version: packageJson.version,
id: 'Zonemaster-GUI',
},
siteInfo: {
email: 'contact@zonemaster.net',
siteName: '',
},
setTitle(title: string) {
return `${title} – Zonemaster`;
}
};
export default config;
```
## "config.ts" configuration options
* **defaultLanguage**: The default language to use when no language is specified.
* The default language must be one of the enabled languages.
* The default value is "en".
* If this option is updated see [Updating Apache configuration] for required
matching update of the Apache configuration.
* **enabledLanguages**: An array of language codes that are supported by the
application.
* The array should match the list of language codes in the [Locale setting] in
the Backend configuration.
* The array must only include language codes also included in
`project.inlang/settings.json`, but it may be fewer. To add new languages,
see [Translating Zonemaster-GUI]. `project.inlang/settings.json` must only be
updated in that process.
* **baseUrl**: The base path Zonemaster-GUI is served on. By default it is "/".
* For example, if Zonemaster-GUI is served at
`http://domaintest.xa/zonemaster`, instead of just
`http://domaintest.xa/`, then this option must be set to `/zonemaster`.
* If this option is updated see [Updating Apache configuration] for required
matching update of the Apache configuration.
* **apiBaseUrl**: The base URL for API requests. The default value is `/api`
and must be kept so if `baseUrl` has its default value.
* If `baseUrl` is updated, then this option must also be updated so that this
option is equal to `baseUrl` + '/api', i.e. '/zonemaster/api' in the
example above.
* **pollingInterval**: The interval (in milliseconds) for polling the API. This
is taken from the `PUBLIC_POLLING_INTERVAL` environment variable (default
empty) or defaults to 5000 ms.
* **clientInfo**: Information about the client application. These details are
included in every API request to start tests as (spoofable) indications of
origin. Both are best left as default.
* **version**: The version of the application, taken from package.json.
* **id**: The identifier for the client application.
* **siteInfo**: Information about the site.
* **email**: The contact email address. To be set in the footer in a mailto
URL, if non-empty.
- **siteName**: The name of the site. To be set in the header if non-empty.
## Updating Apache configuration
Preferably do the updates to the `zonemaster.conf-example` file before building
the installation package. If done so the normal installation instruction can be
followed using the custom installation package.
### Finding "zonemaster.conf-example"
In the source tree the file is found as `zonemaster.conf-example` relative to the
root of the Git tree. It is included in the installation package and is installed
as `zonemaster.conf` in a default installation.
### defaultLanguage
If `defaultLanguage` has been updated in `config.ts` the "DEFAULT_LANGUAGE"
variable must be updated in `zonemaster.conf-example`. The same language code
must be used.
### baseUrl
If `baseUrl` has been set to a non-default value in `config.ts` the "BASE_URL"
variable must be defined with the same value. By default the variable is
undefined (`baseUrl` equal to "/").
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Locale setting]: ../backend.md#locale
[Translating Zonemaster-GUI]: ../../translation/Translating-GUI.md
[Updating Apache configuration]: #updating-apache-configuration

169
zonemaster/docs/public/configuration/gui/configuring-using-theming.md Normal file
View File

@@ -0,0 +1,169 @@
# Configuring Zonemaster-GUI using Theming
## Background
The Zonemaster-GUI is built to be cloned and customized. You have full control
over the styling and layout. That said, to avoid troubles when syncing with
the original repository, we recommend following a few simple guidelines:
- Start by customizing the **theme variables** — this is enough for most use cases.
- If that's not enough, apply **custom CSS** targeting specific elements.
- For large framework changes, **create a new theme** and update `tsconfig.json`.
- For interactive components, **keep changes minimal** to avoid breaking functionality.
- Use **headless mode** for major customizations or when building your own GUI.
## Related documents
For how to use `tsconfig.json` in connection to theming, see
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]. Theming
requires rebuilding Zonemaster-GUI, see
[Build a custom Zonemaster-GUI installation package].
## Basic customization
The Zonemaster-GUI is built around a global theme based on CSS variables
(`./src/themes/default/styles/theme.css`). The easiest way to make your own theme
is to override theme variables in the `./src/themes/default/styles/custom.css` file.
You can tweak colors, fonts, spacing, and more. You'll get surprisingly far by
just updating the theme variables. All class names are prefixed with `zm-` to
avoid conflicts with other styles. This makes it easy to apply custom CSS on top
of the theme to target specific elements.
### Available theme variables
The theme includes variables for:
- **Font sizes and families**: `--font-xxs` through
`--font-supersize`, `--font-body-family`, etc.
- **Spacing**: `--spacing-xxs` through `--spacing-xxl`
- **Colors**: Various color palettes including main, secondary, black, danger,
success, info, warning, and error
- **GUI elements**: Background, text, borders, etc.
- **Buttons**: Size, color, padding
- **Layout**: Width, gaps, header height
- **Breakpoints**: For responsive design
### Example customization
Here's a simple example of customizing the main color and font in `custom.css`:
```css
:root {
/* Change the primary color */
--color-palette-main-50: #4285f4;
--color-palette-main-70: #1a73e8;
/* Change the font */
--font-body-family: 'Roboto', sans-serif;
}
```
### CSS loading order
The CSS files are loaded in the following order (defined in `styles.css`):
1. theme.css (base theme variables)
2. foundation.css and other core styles
3. Component-specific CSS files
4. custom.css (your customizations)
This ensures that your custom styles will override the default styles.
## Modifying structure and layout
There are two layers of the GUI.
### Framework
The framework is the foundation of the GUI and is built with [Astro]. These
files are located under `./src/themes/default`. ' The starting point for these
imports are pages. Pages are simple: they consist of a single component wrapped
inside a layout. *We suggest not modifying the page files*. Instead, create your
own theme, for example `./src/themes/my-theme`. You can still reuse components
from the original theme in your new theme and mix and match the imports from your
custom theme.
Then update tsconfig.json:
```diff
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
- "@theme/*": ["./src/themes/default/*"]
+ "@theme/*": ["./src/themes/my-theme/*"]
}
}
}
```
### Interactive components
All interactive components are built with [Svelte]. These files are located under
`./src/lib/components`. These are referenced from Astro components. Although care
was taken to make the components as self-contained as possible, some
components may depend on others. In most cases you won't need to modify these
files. A better approach is to modify the CSS.
If you absolutely need to modify these, the suggested method is to create new
components in `./src/lib/components/my-theme` and reference them from the
Astro components. These interactive components contain important functionality
that needs to be carefully considered when modifying.
You might be better off creating a new component from scratch and integrate it
with the RPCAPI yourself.
## Headless mode
For major customizations or when you need complete control over the GUI, you can
use the "headless mode" approach. This involves using the Zonemaster API client
directly without the GUI components.
For detailed information about headless mode, please refer to the [UI.md]
documentation.
## Testing and troubleshooting
### Testing your theme changes
When making theme changes, it's important to test them across different pages and
components to ensure consistency. Here are some tips:
1. **Test on different screen sizes**: Use your browser's developer tools to test
responsive behavior.
2. **Check all interactive states**: Verify hover, focus, active, and disabled
states for interactive elements.
3. **Test with different content**: Make sure your theme works well with both
short and long content.
4. **Verify accessibility**: Ensure sufficient color contrast and that focus
states are visible.
### Common issues and solutions
- **Changes not appearing**: Make sure your `custom.css` file is being loaded.
Check the browser's developer tools to verify.
- **Specificity issues**: If your styles aren't overriding the defaults, you
might need to increase specificity or use `!important` (sparingly).
- **Responsive issues**: Check that your customizations work well at all
breakpoints.
- **Component styling conflicts**: If styling a specific component, target the
component's class directly rather than modifying global variables.
### Development workflow
For a smoother development experience:
1. Start the development server with `npm run dev`
2. Make changes to your `custom.css` file
3. The changes will be applied immediately thanks to hot module reloading
4. Use browser developer tools to inspect elements and test different values
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]: configuring-using-tsconfig-json.md
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Astro]: https://astro.build/
[Configuration of GUI]: https://doc.zonemaster.net/latest/configuration/gui/README.html
[Svelte]: https://svelte.dev/
[UI.md]: https://github.com/zonemaster/zonemaster-gui/blob/master/docs/UI.md#headless-mode

81
zonemaster/docs/public/configuration/gui/configuring-using-tsconfig-json.md Normal file
View File

@@ -0,0 +1,81 @@
# Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"
The `tsconfig.json` configuration file can be used for *build-time* settings of
Zonemaster-GUI. Any changes to this file require a rebuild of the installation
package.
## Finding "tsconfig.json"
In the source tree the file is found as `tsconfig.json` relative to the root of
the Git tree. It does not exist in the installed Zonemaster-GUI, as the values
have been built-in.
## Rebuilding Zonemaster-GUI after update
When `tsconfig.json` has been updated, Zonemaster-GUI has to be rebuilt. See
[building installation package] for how to get the source tree and building a new
installation package.
## Default "tsconfig`.json"
The `tsconfig.json` file is a TypeScript configuration file that includes path
aliases like `@theme/*` to simplify imports and make theming more manageable.
```json
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@theme/*": ["./src/themes/default/*"]
},
"resolveJsonModule": true,
"esModuleInterop": true
}
}
```
## @theme/* Alias in "tsconfig.json"
The path alias configuration allows importing from the default theme directory
using the `@theme` prefix, which makes it possible to create a customize the
look-and-feel of the Zonemaster-GUI, e.g. set other colors and type faces.
```json
{
"paths": {
"@/*": ["./src/*"],
"@theme/*": ["./src/themes/default/*"]
}
}
```
This alias makes it easier to import theme-specific components and styles
in your code. For example, instead of writing:
```typescript
import Button from '../../themes/default/components/Button';
```
You can use:
```typescript
import Button from '@theme/components/Button';
```
This approach simplifies imports and makes it easier to switch between different
themes by changing the alias path.
## Theming
In the [Theming Zonemaster-GUI] document you will find instructions how to add
custom theming to Zonemaster-GUI.
[Building installation package]: building-custom-gui.md
[Theming Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui/blob/master/docs/theming-zonemaster-gui.md

30
zonemaster/docs/public/configuration/profiles.md Normal file
View File

@@ -0,0 +1,30 @@
# Profiles
## Default profile
The default profile is documented in the [profile properties] section
of the Zonemaster::Engine::Profile module.
The default profile can be extracted from Zonemaster-Engine to a file using this command.
```sh
perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . > profile.json
```
## Creating profiles
Some properties are empty by default such as `logfilter` and
`test_cases_vars`. Those properties are not present in the default
profile. For an example of their usage, refer to the additional file,
[profile_additional_properties.json].
The content of the two files, as-is or modified, can be merged into a custom
profile file that can be loaded by Zonemaster-Engine. Both Zonemaster-CLI and
Zonemaster-Backend have direct options for loading a custom profile file.
A custom profile file only has to contain those [properties][profile properties]
that it should override.
[profile_additional_properties.json]: https://github.com/zonemaster/zonemaster-engine/blob/master/share/profile_additional_properties.json
[Profile properties]: https://metacpan.org/pod/Zonemaster::Engine::Profile#PROFILE-PROPERTIES