feat: add full Zonemaster stack with Docker and Spanish UI
- 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:
99
zonemaster-backend/docs/Architecture.md
Normal file
99
zonemaster-backend/docs/Architecture.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# Architecture
|
||||
|
||||
The Zonemaster *Backend* is a system for performing domain health checks and
|
||||
keeping records of performed domain health checks.
|
||||
|
||||
A Zonemaster *Backend* system consists of at least three components: a
|
||||
single *Database*, a single *Test Agent* and one or more *RPC API daemons*.
|
||||
|
||||
|
||||
## Components
|
||||
|
||||
### Database
|
||||
|
||||
The *Database* stores health check requests and results. The *Backend*
|
||||
architecture is oriented around a single central *Database*.
|
||||
|
||||
All times in the database are stored in UTC.
|
||||
|
||||
|
||||
### Test Agent
|
||||
|
||||
A Zonemaster *Test Agent* is a daemon that picks up *test* requests from the
|
||||
*Database*, runs them using the *Zonemaster Engine* library, and records the results back
|
||||
to the *Database*. A single *Test Agent* may handle several requests concurrently.
|
||||
The *Backend* architecture supports a single *Test Agent* daemon interacting with a single *Database*.
|
||||
|
||||
>
|
||||
> TODO: List all files these processes read and write.
|
||||
>
|
||||
> TODO: List everything these processes open network connections to.
|
||||
>
|
||||
> TODO: Describe in which order *test* are processed.
|
||||
>
|
||||
> TODO: Describe how concurrency, parallelism and synchronization works within a single *Test Agent*.
|
||||
>
|
||||
> TODO: Describe how synchronization works among parallel *Test Agents*.
|
||||
>
|
||||
|
||||
|
||||
### Web backend
|
||||
|
||||
A Zonemaster *Web backend* is a daemon providing a JSON-RPC interface for
|
||||
recording *test* requests in the *Database* and fetching *test* results from the
|
||||
*Database*. The *Backend* architecture supports multiple *RPC API daemons*
|
||||
interacting with the same *Database*.
|
||||
|
||||
This only needs to be run as root in order to make sure the log file
|
||||
can be opened. The `starman` process will change to the `www-data` user as
|
||||
soon as it can, and all of the real work will be done as that user.
|
||||
|
||||
>
|
||||
> TODO: List all ports these processes listen to.
|
||||
>
|
||||
> TODO: List all files these processes read and write.
|
||||
>
|
||||
> TODO: List everything these processes open network connections to.
|
||||
>
|
||||
|
||||
|
||||
## Glossary
|
||||
|
||||
### Test
|
||||
|
||||
### Batch
|
||||
|
||||
### Test result
|
||||
|
||||
### Test module
|
||||
|
||||
### Message
|
||||
|
||||
### Profile
|
||||
|
||||
A profile is a configuration for Zonemaster Engine; see the [profiles
|
||||
overview] for context.
|
||||
Zonemaster Backend allows administrators to [configure the set of
|
||||
available profiles].
|
||||
|
||||
Each available profile has a [profile name].
|
||||
A profile named `default` is always available.
|
||||
Each available profile is based on the [Zonemaster Engine default profile].
|
||||
Each one (with the possible exception of `default`) has a [profile file]
|
||||
with profile data overriding the Zonemaster Engine default profile.
|
||||
|
||||
The [RPC-API] contains several methods that accept profile name arguments.
|
||||
|
||||
|
||||
### Engine
|
||||
|
||||
The Zonemaster *Engine* is a library for performing *tests*. It's hosted in [its
|
||||
own repository](https://github.com/zonemaster/zonemaster-engine/).
|
||||
|
||||
--------
|
||||
[Configure the set of available profiles]: https://github.com/zonemaster/zonemaster/blob/develop/docs/public/configuration/backend.md#profiles-section
|
||||
[Profile file]: https://metacpan.org/pod/Zonemaster::Engine::Config#PROFILE-DATA
|
||||
[Profile name]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/using/backend/rpcapi-reference.md#profile-name
|
||||
[Profiles overview]: https://github.com/zonemaster/zonemaster/blob/master/docs/internal/design/Profiles.md
|
||||
[RPC-API]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/using/backend/rpcapi-reference.md
|
||||
[Zonemaster Engine default profile]: https://metacpan.org/pod/Zonemaster::Engine::Config#DESCRIPTION
|
||||
28
zonemaster-backend/docs/TypographicConventions.md
Normal file
28
zonemaster-backend/docs/TypographicConventions.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Typographic conventions
|
||||
|
||||
The Zonemaster Backend documentation uses the following typographic conventions:
|
||||
|
||||
*Italic* text is used for:
|
||||
|
||||
* technical terms defined in the [Architecture] document
|
||||
* data types defined in the [API] document
|
||||
|
||||
`Monospace` text is used for:
|
||||
|
||||
* snippets of JSON or sh
|
||||
* JSON-RPC method names
|
||||
* JSON values
|
||||
* single or strings of characters
|
||||
* internet addresses (e.g. domain names and IP addresses)
|
||||
* file names with or without paths (e.g. configuration files and command line
|
||||
tools)
|
||||
* config section names
|
||||
|
||||
>
|
||||
> Block quotes are used for:
|
||||
>
|
||||
> * notes and commentary
|
||||
>
|
||||
|
||||
[API]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/using/backend/rpcapi-reference.md
|
||||
[Architecture]: Architecture.md
|
||||
48
zonemaster-backend/docs/files-description.md
Normal file
48
zonemaster-backend/docs/files-description.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Files Description
|
||||
|
||||
./lib/Zonemaster/Backend/RPCAPI.pm
|
||||
The main module
|
||||
|
||||
./script/zonemaster_backend_rpcapi.psgi
|
||||
The Plack/PSGI module. The main entry module for a Plack/PSGI server (like Starman)
|
||||
|
||||
./lib/Zonemaster/Backend/Config.pm
|
||||
The Configuration file abstraction layer
|
||||
|
||||
./share/backend_config.ini
|
||||
A sample configuration file
|
||||
|
||||
./CodeSnippets/Client.pm
|
||||
./CodeSnippets/client.pl
|
||||
A sample script and library to communicate with the backend.
|
||||
|
||||
./lib/Zonemaster/Backend/DB.pm
|
||||
The Database abstraction layer.
|
||||
|
||||
./lib/Zonemaster/Backend/DB/MySQL.pm
|
||||
The Database abstraction layer MySQL sample backend.
|
||||
|
||||
./lib/Zonemaster/Backend/DB/SQLite.pm
|
||||
The Database abstraction layer SQLite sample backend.
|
||||
|
||||
./lib/Zonemaster/Backend/DB/PostgreSQL.pm
|
||||
The Database abstraction layer PostgreSQL backend.
|
||||
|
||||
./lib/Zonemaster/Backend/Translator.pm
|
||||
The translation module.
|
||||
|
||||
./lib/Zonemaster/Backend/TestAgent.pm
|
||||
The TestAgent main module.
|
||||
|
||||
./script/execute_zonemaster_P10.pl
|
||||
./script/execute_zonemaster_P5.pl
|
||||
The scripts to execute tests with differents priorities (application level priorities).
|
||||
|
||||
./script/execute_tests.pl
|
||||
The main Test Agent entry point to execute from crontab.
|
||||
|
||||
./t/test01.t
|
||||
./t/test_mysql_backend.pl
|
||||
./t/test_postgresql_backend.pl
|
||||
./t/test_validate_syntax.t
|
||||
Test files.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Testing instructions for the Garbage Collection feature of the Zonemaster Backend module
|
||||
|
||||
## Introduction
|
||||
The purpose of this instruction is to serve as a notice for manual testing of the new garbage collection feature at release time.
|
||||
|
||||
## Testing the unfinished tests garbage collection feature
|
||||
|
||||
|
||||
1. Start a test and wait for it to be finished
|
||||
|
||||
```
|
||||
SELECT hash_id, progress FROM test_results LIMIT 1;
|
||||
```
|
||||
Should return:
|
||||
|
||||
```
|
||||
hash_id | progress
|
||||
------------------+----------
|
||||
3f7a604683efaf93 | 100
|
||||
(1 row)
|
||||
```
|
||||
|
||||
2. Simulate a crashed test
|
||||
```
|
||||
UPDATE test_results SET progress = 50, test_start_time = '2020-01-01' WHERE hash_id = '3f7a604683efaf93';
|
||||
```
|
||||
|
||||
3. Check that the backend finishes the test with a result stating it was unfinished
|
||||
|
||||
```
|
||||
SELECT hash_id, progress FROM test_results WHERE hash_id = '3f7a604683efaf93';
|
||||
```
|
||||
Should return a finished result:
|
||||
```
|
||||
hash_id | progress
|
||||
------------------+----------
|
||||
3f7a604683efaf93 | 100
|
||||
(1 row)
|
||||
```
|
||||
|
||||
4. Ensure the test result contains the backend generated critical message:
|
||||
```
|
||||
{"tag":"UNABLE_TO_FINISH_TEST","level":"CRITICAL","timestamp":"300","module":"BACKEND_TEST_AGENT"}
|
||||
```
|
||||
|
||||
```
|
||||
SELECT hash_id, progress FROM test_results WHERE hash_id = '3f7a604683efaf93' AND results::text like '%UNABLE_TO_FINISH_TEST%';
|
||||
```
|
||||
_Remark: for MySQL queries remove the `::text` from all queries_
|
||||
|
||||
Should return:
|
||||
```
|
||||
hash_id | progress
|
||||
------------------+----------
|
||||
3f7a604683efaf93 | 100
|
||||
(1 row)
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user