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

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