Costa Sano MediaWiki - User contributions [en]

ICT:MWC/FinalConfig-Chapter

2026-04-13T09:01:02Z

Mngr: Mngr moved page ICT:MWC - FinalConfig-Chapter to ICT:MWC/FinalConfig-Chapter without leaving a redirect

= Final Configuration for the Chapter Entity =

Document revision: {{#time:Y-m-d|{{REVISIONTIMESTAMP}}}} by {{REVISIONUSER}}

The aim is to create an interface without MediaWiki clutter and well protected to avoid confusing users with unnecessary elements on the page.
The Cargo template follows what has been decided in the DBML and is fully aligned with the reference entities Place and Organisation.

The Chapter entity is structurally simple:
- it is recursive (parent chapter)
- it has no foreign keys to other entities

This entity serves as the reference for the simplest recursive pattern in the system.

This configuration deliberately favors explicit behavior and robustness over visual polish or implicit framework behavior, in order to ensure long-term maintainability.

= Cargo Table: =
Template:Chapter
<pre>
<noinclude>
Chapter data template
</noinclude>

{{#cargo_declare:
|_table=Chapters
|Code=Page
|Label=String
|Parent=Page
|Sequence=Integer
|Description=Text
|StartDate=Date
|EndDate=Date
|Notes=Text
}}

{{#cargo_store:
|Code={{FULLPAGENAME}}
|Label={{{Label|}}}
|Parent={{{Parent|}}}
|Sequence={{{Sequence|}}}
|Description={{{Description|}}}
|StartDate={{{StartDate|}}}
|EndDate={{{EndDate|}}}
|Notes={{{Notes|}}}
}}

== {{{Label|}}} ==
{{DISPLAYTITLE:{{{Label}}}}}

{{#if:{{{Parent|}}}|
'''Parent chapter:''' [[{{{Parent}}}]]
}}

'''Notes:'''
{{{Notes|}}}
</pre>

Once the template is created, the Cargo table must be created manually.
If modifications are made to the table structure, the table must be recreated and the temporary table swapped via the Cargo administration interface.

The field Code stores the full page name (including namespace) to ensure unambiguous identification.

Important conventions:
- Field names start with a capital letter
- Code is the page name and acts as the technical identifier
- Label is the human-readable name and is mandatory for all entities
- Parent is stored as a Page field
- The field name Label must not be renamed, as it is relied upon by shared JavaScript validation logic

Special lines at the bottom of the template:
<pre>
== {{{Label|}}} ==
{{DISPLAYTITLE:{{{Label}}}}}

{{#if:{{{Parent|}}}|
'''Parent chapter:''' [[{{{Parent}}}]]
}}

'''Notes:'''
{{{Notes|}}}
</pre>

These lines ensure that the human-readable name (Label) is consistently used as the visible page title, while the actual page name remains the stable technical identifier (Code).

This decoupling allows renaming the label without breaking Cargo relations or dashboards.

= Page Form: =
Form:Chapter
<pre>
<noinclude>
Form for creating and editing Chapter pages.
</noinclude>

{{{info
|no summary
|no preview
|no minor edit
|no watch
|no footer
}}}
''Fields marked with (*) are required.''

{{{for template|Chapter}}}

{| class="formtable"

! Code
| {{PAGENAME}}
|-

! Name (*)
| {{{field|Label}}}
|-

! Parent chapter
| {{{field|Parent
|input type=combobox
|values from namespace=Chapter
|placeholder=Top level (no parent)
}}}
|-

! Sequence
| {{{field|Sequence}}}
|-

! Description
| {{{field|Description|input type=textarea}}}
|-

! Start date
| {{{field|StartDate|input type=datepicker|year range=1800:2100|show year dropdown|show month dropdown}}}
|-

! End date
| {{{field|EndDate|input type=datepicker|year range=1800:2100|show year dropdown|show month dropdown}}}
|-

! Notes
| {{{field|Notes|input type=textarea}}}

|}

{{{standard input|save}}}

{{{end template}}}
</pre>

The first section avoids MediaWiki edit clutter.
<pre>
{{{info
|no summary
|no preview
|no minor edit
|no watch
|no footer
}}}
</pre>

The field Label (displayed to the user as “Name”) is mandatory for all entities.
This requirement is not implemented using the Page Forms |mandatory option, as this produces unusable white error boxes in the dark Vector-2022 environment.

Instead:
- the requirement is communicated via text and (*)
- enforcement is handled via JavaScript at save time

= Dashboard page =
Dashboard:Chapter
<pre>
= 📘 Costa Sano Research CHAPTER Dashboard =

📖 [[Dashboard:Chapter/Help|Need Help?]]

{| class="wikitable sortable"
! Code !! Name !! Parent
{{#cargo_query:
tables=Chapters
|fields=_pageName,_pageTitle,Label,Parent
|where=_pageNamespace=3004
|order by=_pageTitle
|format=template
|template=ChapterRow
|named args=yes
|cache=no
}}
|}

Choose your chapter code corresponding to above table and respecting the naming conventions.

{{#forminput:
form=Chapter
|namespace=Chapter
|button text=➕ New chapter
|returnto=Dashboard:Chapter
}}

<div style="text-align:right; font-size:90%;">
Last updated: {{CURRENTDAY}} {{CURRENTMONTHNAME}} {{CURRENTYEAR}} – {{CURRENTTIME}} UTC
</div>
</pre>

IMPORTANT:
Dashboard tables are positional.
The number and order of:
- table headers
- Cargo query fields
- row template cells
MUST match exactly.

Only the first column (Code) is clickable and leads to the edit form.
All other columns are displayed as plain text to prevent navigation to record pages.

= Row transclusion Template =
Template:ChapterRow
<pre>
<includeonly>
|-
| {{#formlink:
form=Chapter
|target={{{_pageName}}}
|link text={{{_pageTitle}}}
|returnto=Dashboard:Chapter
}}
| {{{Label}}}
| {{#if:{{{Parent|}}}|{{#titleparts:{{{Parent}}}|1}}|—}}
</includeonly>
</pre>

Parent values are displayed as plain text (not links) to prevent users from navigating directly to record pages. All record editing is performed via forms accessed from the dashboard.

= Javascript =

The Chapter entity reuses the same shared JavaScript infrastructure as Place and Organisation:
- dashboard auto-purge
- save-time mandatory field enforcement (Label)
- no Page Forms |mandatory usage

No Chapter-specific JavaScript is required.

All Chapter pages are stored in the Chapter namespace with the page name acting as the Code.

Example:
<pre>
{{Chapter
|Label=In the beginning
|Description=Chapter describing what happened before Berck-sur-Mer...
|StartDate=1800-01
|EndDate=1849-12
|Notes=NIHIL
}}
</pre>

Such pages are configuration pages and must be accessed via the dashboard, not directly.

== References: ==

* [[mediawikiwiki:Extension:Cargo/Storing_data|Cargo table explanation]]
* [[mediawikiwiki:Extension:Page_Forms|Page Forms explained]]

[[Category:FinalConfig]]

ICT:MWC

2026-04-13T09:00:32Z

Mngr: Created page with "= Section for MediaWiki Cargo application = This application got stuck on the automatic numbering of the assests. Her the interesting pages about this application are collected."

= Section for MediaWiki Cargo application =

This application got stuck on the automatic numbering of the assests.

Her the interesting pages about this application are collected.

ICT:MWC/FinalConfig-Chapter

2026-04-13T08:43:33Z

Mngr: Mngr moved page ICT:FinalConfig-Chapter to ICT:MWC - FinalConfig-Chapter without leaving a redirect

ICT:Clean URLs for MW 1.45

2026-04-11T16:30:01Z

Mngr: Created page with "== MediaWiki 1.45.2 Clean URL Configuration for kb.costasano.club == This document outlines the "Short URL" configuration for the wiki migration to version 1.45.2 on AlmaLinux 10. === Architecture Overview === * **Domain:** <code>https://costasano.club</code> * **Frontend (Reverse Proxy):** Nginx on AlmaLinux 10 (Handling SSL/HTTPS). * **Backend (Web Server):** Apache on AlmaLinux 10 (Handling PHP/MediaWiki). * **Document Root:** <code>/var/www/mw145</code> (index.php..."

== MediaWiki 1.45.2 Clean URL Configuration for kb.costasano.club ==

This document outlines the "Short URL" configuration for the wiki migration to version 1.45.2 on AlmaLinux 10.

=== Architecture Overview ===
* **Domain:** <code>https://costasano.club</code>
* **Frontend (Reverse Proxy):** Nginx on AlmaLinux 10 (Handling SSL/HTTPS).
* **Backend (Web Server):** Apache on AlmaLinux 10 (Handling PHP/MediaWiki).
* **Document Root:** <code>/var/www/mw145</code> (index.php is located here).
* **URL Strategy:** Using the <code>/wiki/</code> virtual prefix to simplify the Apache configuration and avoid the complex "exclusion lists" used in version 1.43.

=== Step 1: Nginx Proxy Configuration (The Bridge) ===
The Nginx proxy is configured as a "transparent bridge." It does '''not''' handle rewrites; it simply passes the <code>/wiki/</code> path through to the Apache backend.

<syntaxhighlight lang="nginx">
server {
listen 443 ssl;
server_name kb.costasano.club;

# SSL Certs (Managed at Nginx layer)
ssl_certificate /etc/letsencrypt/live/kb.costasano.club/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/kb.costasano.club/privkey.pem;

location / {
proxy_pass http://[BACKEND_IP_OR_HOSTNAME];
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https; # Tells MediaWiki the user is on HTTPS
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
</syntaxhighlight>

=== Step 2: Apache Configuration (The Logic) ===
Apache handles the translation of the "clean" URL into a format PHP understands.

==== 2.1 Enable Overrides ====
Ensure <code>/etc/httpd/conf/httpd.conf</code> (or your specific Vhost file) allows the <code>.htaccess</code> file to function:
<syntaxhighlight lang="apache">
<Directory "/var/www/mw145">
AllowOverride All
Require all granted
</Directory>
</syntaxhighlight>

==== 2.2 Create .htaccess ====
Place this file at <code>/var/www/mw145/.htaccess</code>. It maps the virtual <code>/wiki/</code> path to the physical <code>index.php</code>.
<syntaxhighlight lang="apache">
RewriteEngine On

# 1. Map the virtual /wiki/ path to index.php
RewriteRule ^wiki/(.*)$ /index.php?title=$1 [PT,L,QSA]

# 2. Redirect root domain (kb.costasano.club/) to the Main Page
RewriteRule ^$ /wiki/ [R,L]
</syntaxhighlight>

=== Step 3: MediaWiki LocalSettings.php ===
Update <code>/var/www/mw145/LocalSettings.php</code> to define the identity of the wiki and trust the Nginx header.

<syntaxhighlight lang="php">
## URL Settings
$wgServer = "https://costasano.club";
$wgScriptPath = ""; // Files are directly in /var/www/mw145
$wgArticlePath = "/wiki/$1"; // Users see this path

## Reverse Proxy / HTTPS Handling
# Ensures MediaWiki knows it is served over HTTPS even if Apache is HTTP
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
$_SERVER['HTTPS'] = 'on';
}

# Trust the internal IP of your Nginx Proxy
$wgUsePrivateIPs = true;
$wgCdnServersNoPurge = [ '127.0.0.1', '[IP_OF_NGINX_PROXY]' ];
</syntaxhighlight>

=== Why we use the "/wiki/" prefix ===
* '''Simplicity:''' Unlike the version 1.43 setup, we no longer need a massive list of exclusions (RewriteCond) for every folder (skins, images, resources, etc.).
* '''Stability:''' It prevents "Path Collisions" where a wiki page name might conflict with a real folder on the disk.
* '''Performance:''' Reduces the processing load on Apache for every request.

[[Category:Server Documentation]]

IC:MW Talk Namespaces

2026-04-06T11:53:32Z

Mngr: Created page with "= Custom Talk Namespaces in MediaWiki = This document explains the purpose of Talk namespaces in MediaWiki, how custom Talk namespaces are defined, and why they only appear in the namespace list after specific configuration steps. == 1. Purpose of Talk Namespaces == MediaWiki separates *content* from *discussion* using paired namespaces: * Even-numbered namespace → content (e.g. <code>Network</code>) * Odd-numbered namespace → talk/discussion (e.g. <code>Network_Ta..."

= Custom Talk Namespaces in MediaWiki =
This document explains the purpose of Talk namespaces in MediaWiki, how custom Talk namespaces are defined, and why they only appear in the namespace list after specific configuration steps.

== 1. Purpose of Talk Namespaces ==
MediaWiki separates *content* from *discussion* using paired namespaces:

* Even-numbered namespace → content (e.g. <code>Network</code>)
* Odd-numbered namespace → talk/discussion (e.g. <code>Network_Talk</code>)

Talk namespaces serve several purposes:
* Keep content pages clean and factual.
* Provide a dedicated space for questions, decisions, and editorial notes.
* Preserve decision history for future maintainers.
* Support structured workflows (templates, categories, archiving).
* Allow experimentation and discussion without altering the main content.

Every content namespace should have a corresponding Talk namespace for long-term maintainability.

== 2. Why MediaWiki Does Not Auto‑Create Talk Namespaces ==
MediaWiki automatically creates Talk namespaces only for its built‑in namespaces (Main, File, Help, etc.).

For custom namespaces, MediaWiki does *not* assume a Talk namespace exists.
It will only register a Talk namespace when:

# A numeric ID is defined.
# A name is assigned in <code>$wgExtraNamespaces</code>.
# The ID is an odd number paired with the content namespace.

Until these conditions are met, the Talk namespace will not appear in:
* Special:SpecialPages → “Namespaces”
* Special:AllPages namespace dropdown
* API namespace lists

== 3. Defining a Custom Namespace Pair ==
A correct custom namespace definition looks like this:

<pre>
# --- Custom namespace: Network ---
define("NS_NETWORK", 3000);
define("NS_NETWORK_TALK", 3001);

$wgExtraNamespaces[NS_NETWORK] = "Network";
$wgExtraNamespaces[NS_NETWORK_TALK] = "Network_Talk";

# Optional: namespace shortcuts
$wgNamespaceAliases['N'] = NS_NETWORK;
$wgNamespaceAliases['N_Talk'] = NS_NETWORK_TALK;

# Optional: enable subpages
$wgNamespaceWithSubpage[NS_NETWORK] = true;
</pre>

=== Required elements ===
* <code>define("NS_NETWORK", 3000);</code>
* <code>define("NS_NETWORK_TALK", 3001);</code>
* <code>$wgExtraNamespaces[...]</code> entries for both

=== Optional but recommended ===
* namespace aliases
* subpage support

== 4. Why the Talk Namespace Appears Only After Full Definition ==
MediaWiki registers namespaces early during startup.
A Talk namespace will only appear when:

* Both the content and talk IDs are defined.
* Both names are assigned in <code>$wgExtraNamespaces</code>.
* The definitions are placed early enough in <code>LocalSettings.php</code>.

If the Talk namespace is defined later in the file, or after extensions that query namespaces, it may not appear until the next reload.

=== Rule of thumb ===
Place all custom namespace definitions **at the top of LocalSettings.php**, before loading extensions.

== 5. Namespace ID Pairing (Even/Odd Rule) ==
MediaWiki uses numeric pairing to link content and talk namespaces:

* Even ID → content namespace
* Odd ID → talk namespace
* The talk namespace must immediately follow the content namespace

Example:
* <code>3000 → Network</code>
* <code>3001 → Network_Talk</code>

If the pairing is broken, MediaWiki will not recognize the Talk namespace correctly.

== 6. Summary ==
* Talk namespaces store discussion, decisions, and editorial notes separate from content.
* MediaWiki does not auto-create Talk namespaces for custom namespaces.
* A Talk namespace appears only after proper definition (ID + name + pairing).
* Namespace definitions must be placed early in <code>LocalSettings.php</code>.
* Even/odd numeric pairing is essential for correct behavior.

This structure ensures clean content pages, clear editorial history, and a successor‑friendly wiki architecture.

ICT:MW Installation procedure 1.43 LTS -v2

2026-04-04T16:11:05Z

Mngr:

= Installation Procedure for a New MediaWiki Instance (MediaWiki 1.43 LTS) =
This document describes the clean, reproducible workflow for deploying a new MediaWiki instance on the existing 3‑VM infrastructure.

The installation is intentionally split into two phases:

* '''Phase 1:''' Local installation and testing on VM1 (Apache on port 8080)
* '''Phase 2:''' Public exposure through VM3 (nginx reverse‑proxy + HTTPS)

This staged approach ensures safe testing before the wiki becomes accessible from the internet.

== VM Overview ==
* '''VM1 (Web Layer):''' 192.168.33.231
* '''VM2 (Database Layer):''' 192.168.33.232
* '''VM3 (Reverse‑Proxy Layer):''' 192.168.33.233
* '''DB user host address (VM1 → VM2):''' 10.10.10.1

----

= 1. Create the Database (VM2 – MariaDB) =
All commands in this section run on VM2 (192.168.33.232).

=== 1.1 Connect to MariaDB ===
<pre>
mysql -u root -p
</pre>

=== 1.2 Create the database ===
<pre>
CREATE DATABASE newwiki
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
</pre>

=== 1.3 Create the database user ===
VM1 connects to MariaDB using its internal DB‑facing address: '''10.10.10.1'''.

<pre>
CREATE USER 'newwikiuser'@'10.10.10.1' IDENTIFIED BY 'strongpassword';
</pre>

=== 1.4 Grant privileges ===
<pre>
GRANT ALL PRIVILEGES ON newwiki.* TO 'newwikiuser'@'10.10.10.1';
FLUSH PRIVILEGES;
</pre>

=== 1.5 Exit ===
<pre>
EXIT;
</pre>

----

= 2. Prepare the Installation Directory (VM1 – Web Layer) =
All commands below run on VM1 (192.168.33.231).

=== 2.1 Create the target directory ===
<pre>
mkdir /var/www/newMW
</pre>

=== 2.2 Move into /var/www ===
<pre>
cd /var/www
</pre>

----

= 3. Download MediaWiki =
Example: MediaWiki 1.43.8 LTS.

<pre>
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.8.tar.gz
</pre>

----

= 4. Extract MediaWiki =
<pre>
tar -xvzf mediawiki-1.43.8.tar.gz
</pre>

----

= 5. Move Extracted Files into newMW =
<pre>
mv mediawiki-1.43.8/* newMW/
mv mediawiki-1.43.8/.* newMW/ 2>/dev/null
rmdir mediawiki-1.43.8
rm mediawiki-1.43.8.tar.gz
</pre>

----

= 6. Ownership and Permissions =
Allows editing via VS Code while keeping Apache functional.

=== 6.1 Set owner and group ===
<pre>
chown -R mngr:apache /var/www/newMW
</pre>

=== 6.2 Ensure group write permissions ===
<pre>
chmod -R g+w /var/www/newMW
</pre>

=== 6.3 Directory/file permissions ===
<pre>
find /var/www/newMW -type d -exec chmod 775 {} \;
find /var/www/newMW -type f -exec chmod 664 {} \;
</pre>

=== 6.4 Enable group inheritance (setgid) ===
<pre>
chmod g+s /var/www/newMW
</pre>

----

= 7. Apache Configuration on VM1 (Port 8080) =

== 7.1 Enable Apache to listen on port 8080 ==
Edit:
<pre>
/etc/httpd/conf/httpd.conf
</pre>

Add:
<pre>
Listen 8080
</pre>

== 7.2 Validate and restart ==
<pre>
apachectl configtest
systemctl restart httpd
</pre>

== 7.3 Verify Apache is listening ==
<pre>
ss -tlnp | grep httpd
</pre>

Expected:
<pre>
0.0.0.0:80
0.0.0.0:8080
</pre>

== 7.4 Firewall rule (VM1) ==
Allow port 8080:

<pre>
firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload
</pre>

== 7.5 Local‑only Apache VirtualHost ==
<pre>
<VirtualHost *:8080>
ServerName newmw.local
DocumentRoot /var/www/newMW

<Directory /var/www/newMW>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newmw-local-error.log
CustomLog /var/log/httpd/newmw-local-access.log combined
</VirtualHost>
</pre>

Restart Apache:
<pre>
systemctl restart httpd
</pre>

----

= 8. Run the Installer Locally =
Access:

* <code>http://192.168.33.231:8080</code>
* <code>http://newmw.local:8080</code> (if added to /etc/hosts)

== Internal DB Network Logic (10.10.10.x) ==
The internal network between VM1 and VM2 uses dedicated addresses:

* VM1 (Web Layer): '''10.10.10.1'''
* VM2 (Database Layer): '''10.10.10.2'''

When MediaWiki (running on VM1) connects to MariaDB on VM2, the connection originates from VM1’s internal NIC.
Therefore:

* VM1 connects **to** MariaDB at:
<code>10.10.10.2</code>

* VM2 sees VM1 **coming from**:
<code>10.10.10.1</code>

Because MariaDB authorizes users based on the client’s source address, database users must be created as:

<pre>
'wikiuser'@'10.10.10.1'
</pre>

This is why all MediaWiki instances on VM1 use the same host restriction.
It ensures that only VM1 can authenticate to MariaDB over the internal network.

== Result after installation flow ==

Installer will generate:
<pre>
$wgServer = "http://192.168.33.231:8080";
</pre>

Place <code>LocalSettings.php</code> in:
<pre>
/var/www/newMW/LocalSettings.php
</pre>

----

= 9. Local Testing =
Verify:

* Page creation
* Editing
* File uploads
* User accounts
* Extensions
* Permissions
* Logging

Only proceed when everything works locally.

----

= 10. Public Exposure via VM3 (Reverse‑Proxy Layer) =

== 10.1 Create minimal HTTP‑only nginx config (VM3) ==
File:
<code>/etc/nginx/conf.d/kb.costasano.club.conf</code>

<syntaxhighlight lang="nginx">
# ============================================
# Reverse proxy (HTTP only)
# kb.costasano.club
# ============================================

server {
listen 80;
listen [::]:80;
server_name kb.costasano.club;

location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

location / {
proxy_pass http://192.168.33.231:8080;

proxy_set_header Host kb.costasano.club;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto http;
}
}
</syntaxhighlight>

Reload nginx:
<syntaxhighlight lang="bash">
sudo nginx -t
sudo systemctl reload nginx
</syntaxhighlight>

----

= 11. Issue the Certificate (VM3) =
Use the nginx plugin:

<syntaxhighlight lang="bash">
sudo certbot --nginx -d kb.costasano.club
</syntaxhighlight>

Certbot will:

* inject temporary ACME config
* validate the domain
* obtain the certificate
* install it
* register it for renewal

----

= 12. Replace with Full HTTPS Reverse‑Proxy (VM3) =
<syntaxhighlight lang="nginx">
# ============================================
# Reverse proxy (HTTPS)
# kb.costasano.club
# ============================================

# --- HTTP (redirect + ACME) ---
server {
listen 80;
listen [::]:80;
server_name kb.costasano.club;

location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

return 301 https://$host$request_uri;
}

# --- HTTPS ---
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;

server_name kb.costasano.club;

ssl_certificate /etc/letsencrypt/live/kb.costasano.club/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/kb.costasano.club/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

location / {
proxy_pass http://192.168.33.231:8080;

proxy_set_header Host kb.costasano.club;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;

proxy_buffering on;
proxy_buffers 16 16k;
proxy_buffer_size 16k;

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}
</syntaxhighlight>

Reload nginx:
<syntaxhighlight lang="bash">
sudo nginx -t
sudo systemctl reload nginx
</syntaxhighlight>

----

= 13. Update LocalSettings.php for Public Access =
Change:
<pre>
$wgServer = "https://kb.costasano.club";
</pre>

Optional:
<pre>
$wgCanonicalServer = "https://kb.costasano.club";
</pre>

----

= 14. Final Verification =
* <code>curl -I https://kb.costasano.club</code> returns 200 or 301
* Browser loads the wiki
* Editing works
* Uploads work
* No rewrite errors
* nginx proxies correctly
* MariaDB connections succeed

----

= 15. Login Issues After Changing LocalSettings.php =
MediaWiki is very sensitive to stale cookies and cached sessions, especially
after changing settings such as:

* $wgServer
* $wgCookieSecure
* $wgCookieSameSite
* $wgUseReverseProxy
* $wgUseCdn

If login suddenly fails or a Captcha appears even though no Captcha extension
is enabled, the cause is usually old browser cookies.

'''Fix:''' open the wiki in a private/incognito window or clear cookies for the
domain. This forces MediaWiki to create a fresh session and resolves the issue.

=== Differences Between MediaWiki 1.43 and 1.45 (Login, Captcha, Reverse‑Proxy) ===
MediaWiki 1.43 and 1.45 behave differently when installed behind a reverse‑proxy
such as nginx. This affects login, session cookies, and the appearance of the
“phantom Captcha” (a throttle challenge that cannot be solved).

==== MediaWiki 1.45 (more tolerant) ====
MediaWiki 1.45 includes improved session and cookie handling. It automatically:

* detects HTTPS behind a reverse‑proxy
* regenerates session cookies when needed
* accepts SameSite=None cookies more reliably
* avoids triggering login throttling on fresh installs

As a result, MediaWiki 1.45 usually works immediately behind nginx without
showing any Captcha or blocking logins.

==== MediaWiki 1.43 (stricter behaviour) ====
MediaWiki 1.43 uses older, stricter session logic. If any of the following are
misconfigured:

* $wgServer
* $wgCookieSecure
* $wgCookieSameSite
* $wgUseReverseProxy
* $wgUseCdn
* missing $wgCdnServers entry

…MediaWiki may fail to create a valid login session. When this happens, it
displays a Captcha-like box even though no Captcha extension is enabled. This is
not a real Captcha but the built‑in login throttle, and it always fails.

==== Why this did not happen on the previous install ====
The earlier wiki was installed on MediaWiki 1.45, which is more forgiving of
reverse‑proxy setups. MediaWiki 1.43 requires explicit configuration to trust
the proxy and accept secure cookies.

==== Fix ====
Add the following lines to LocalSettings.php:

<pre>
$wgUseCdn = true;
$wgUseReverseProxy = true;
$wgCdnServers = [ "192.168.33.233" ]; # nginx reverse-proxy
$wgCookieSecure = true;
$wgCookieSameSite = "None";
</pre>

If login still fails, clear browser cookies or open the wiki in a private window
to force a fresh session.

= 16. Summary =
This procedure installs MediaWiki in two safe phases:

* '''Phase 1:''' Local installation and validation on VM1
* '''Phase 2:''' Public exposure through VM3 with HTTPS

This ensures a clean, reproducible, low‑risk deployment workflow.

== Apache fails to start after adding a new Listen port (SELinux) ==

When adding a new Apache <code>Listen</code> directive on AlmaLinux (e.g. <code>Listen 8081</code> or <code>Listen 8888</code>),
<code>httpd</code> may refuse to start even though <code>apachectl configtest</code> reports <code>Syntax OK</code>.

Typical symptoms:
* <code>httpd</code> does not restart after adding a new port
* <code>configtest</code> shows no errors
* <code>journalctl -xe</code> or <code>/var/log/audit/audit.log</code> contains an AVC denial similar to:

<pre>
type=AVC msg=audit(...): avc: denied { name_bind } for pid=XXXX comm="httpd" \
scontext=system_u:system_r:httpd_t:s0 \
tcontext=system_u:object_r:unreserved_port_t:s0 \
tclass=tcp_socket permissive=0
</pre>

=== Cause ===
SELinux only allows Apache (<code>httpd_t</code>) to bind to ports labeled as <code>http_port_t</code>.
By default, this includes ports such as 80, 443, 8008, 8009, 8443, and sometimes 8080.

Any new port (e.g. 8081, 8888) is labeled as <code>unreserved_port_t</code> and is therefore blocked by SELinux.
Apache reports this as a binding failure, often misleadingly shown as:

<pre>
No such device or address
</pre>

=== Check which ports Apache is allowed to use ===
<pre>
semanage port -l | grep http_port_t
</pre>

=== Fix: allow Apache to bind to the new port ===
Add the port to the SELinux <code>http_port_t</code> type:

<pre>
sudo semanage port -a -t http_port_t -p tcp 8081
sudo semanage port -a -t http_port_t -p tcp 8888
</pre>

If the port already exists under a different SELinux type, modify it instead:

<pre>
sudo semanage port -m -t http_port_t -p tcp 8081
</pre>

=== Restart Apache ===
<pre>
sudo systemctl restart httpd
</pre>

Apache will now start normally and bind to the newly added port.

=== Notes for maintainers ===
* This behaviour is normal on RHEL/AlmaLinux systems with SELinux in enforcing mode.
* Always document newly opened ports in the infrastructure notes to avoid confusion for successors.
* Avoid disabling SELinux; adjusting port labels is the correct and safe approach.

ICT:MW upgrade 1.43.8 to 1.46 LTS

2026-04-04T13:59:08Z

Mngr: Created page with "= MediaWiki Upgrade Procedure — 1.43.8 → 1.46 LTS = '''Document version:''' 2025‑04‑04 '''Author:''' Martin '''Purpose:''' Clean, reproducible, successor‑friendly upgrade to MediaWiki 1.46 LTS using a parallel installation in <code>/var/www/mw146</code> and a reverse‑proxy switch. This procedure ensures: * Zero downtime * Instant rollback * No leftover files from old versions * Clean, maintainable, successor‑friendly architecture The upgrade i..."

= MediaWiki Upgrade Procedure — 1.43.8 → 1.46 LTS =
'''Document version:''' 2025‑04‑04
'''Author:''' Martin
'''Purpose:''' Clean, reproducible, successor‑friendly upgrade to MediaWiki 1.46 LTS using a parallel installation in <code>/var/www/mw146</code> and a reverse‑proxy switch.

This procedure ensures:
* Zero downtime
* Instant rollback
* No leftover files from old versions
* Clean, maintainable, successor‑friendly architecture

The upgrade is executed on the '''web VM''' with a final switch on the '''reverse‑proxy VM'''.

----

== Preconditions ==
* Working MediaWiki '''1.43.8 LTS''' installation
* Database VM reachable and healthy
* PHP '''8.1 or 8.2'''
* Reverse proxy currently pointing to <code>/var/www/mw143</code>
* VM snapshot taken before starting
* SSH access to web VM and reverse‑proxy VM

----

== Step 1: Prepare new directory ==
On the '''web VM''':

<pre>
cd /var/www
mkdir mw146
</pre>

Download and extract MediaWiki 1.46 LTS:

<pre>
wget https://releases.wikimedia.org/mediawiki/1.46/mediawiki-1.46.0.tar.gz
tar -xzf mediawiki-1.46.0.tar.gz --strip-components=1 -C mw146
</pre>

Resulting structure:

<pre>
/var/www/mw146
</pre>

----

== Step 2: Copy required files from old installation ==
From the existing 1.43 installation (example path <code>/var/www/mw143</code>):

=== Copy LocalSettings.php ===
<pre>
cp /var/www/mw143/LocalSettings.php /var/www/mw146/
</pre>

=== Copy images directory ===
<pre>
cp -R /var/www/mw143/images /var/www/mw146/
</pre>

=== Copy custom logos (if stored outside images) ===
<pre>
cp /var/www/mw143/resources/assets/*logo* /var/www/mw146/resources/assets/
</pre>

Do '''not''' copy extensions yet.

----

== Step 3: Install or update extensions ==
MediaWiki 1.46 requires updated extensions.

For each extension used in 1.43:

# Download the '''1.46‑compatible''' version
# Place it in <code>/var/www/mw146/extensions/</code>
# Keep the same configuration lines in <code>LocalSettings.php</code>

Vector‑2022 is bundled in 1.46 → no action needed.

----

== Step 4: Run the database upgrade ==
On the web VM:

<pre>
cd /var/www/mw146
php maintenance/update.php
</pre>

This upgrades the schema '''in place'''.
No data is lost.
No new database is created.

----

== Step 5: Local testing before switching reverse proxy ==
Access the new installation directly via the web VM’s IP:

<pre>
http://<web-vm-ip>/mw146/
</pre>

Verify:

* Login
* Namespaces and subpages
* Uploads
* SMTP
* Dark mode
* Vector‑2022 behaviour
* Special pages (filter box present)
* Search
* Logo

Proceed only when everything is correct.

----

== Step 6: Switch reverse proxy ==
On the '''reverse‑proxy VM''', update the root path.

Example (Nginx):

<pre>
root /var/www/mw146;
</pre>

Reload:

<pre>
systemctl reload nginx
</pre>

The wiki now runs on '''1.46 LTS'''.

Rollback is instant: point back to <code>/var/www/mw143</code>.

----

== Step 7: Post‑upgrade checks ==
* Check error logs on web VM
* Check reverse‑proxy logs
* Verify job queue
* Verify uploads
* Verify Special pages
* Verify dark mode
* Verify email notifications

----

== Step 8: Cleanup ==
After several days of stable operation:

<pre>
rm -rf /var/www/mw143
</pre>

Or archive it for long‑term reference.

----

== Rollback Procedure ==
If any issue occurs after switching:

# Edit reverse‑proxy config
# Point root back to <code>/var/www/mw143</code>
# Reload proxy
# Wiki is instantly restored

Database remains compatible.

----

== Notes ==
* MediaWiki 1.46 includes native dark mode
* Vector‑2022 settings may be simplified
* The Special pages filter box is available in 1.46
* No database recreation is required for upgrades

ICT:MW Installation procedure 1.43 LTS -v2

2026-04-03T16:56:35Z

Mngr:

ICT:MW Installation procedure 1.43 LTS -v2

2026-04-03T16:44:41Z

Mngr:

ICT:MW Installation procedure 1.43 LTS -v2

2026-04-03T16:13:08Z

Mngr:

ICT:MW Installation procedure 1.43 LTS -v2

2026-04-03T16:04:05Z

Mngr: Created page with "= Installation Procedure for a New MediaWiki Instance (MediaWiki 1.43 LTS) = This document describes the clean, reproducible workflow for deploying a new MediaWiki instance on the existing 3‑VM infrastructure. The installation is intentionally split into two phases: * '''Phase 1:''' Local installation and testing on VM1 (Apache on port 8080) * '''Phase 2:''' Public exposure through VM3 (nginx reverse‑proxy + HTTPS) This staged approach ensures safe testing before..."

ICT:MW Installation procedure 1.43 LTS

2026-04-03T15:50:58Z

Mngr:

= Installation Procedure for newMW (MediaWiki 1.43 LTS) =
This document describes the clean, reproducible installation workflow for
deploying a new MediaWiki instance (newMW) on the existing 3‑VM infrastructure.
The installation is intentionally split into two phases:

* Phase 1: Local installation and testing on VM1 (no reverse‑proxy required)
* Phase 2: Public exposure through VM3 (nginx reverse‑proxy)

This staged approach allows safe testing before the wiki becomes accessible
from the internet.

== 1. Create the newwiki Database (VM2 – Database Layer) ==
All commands in this section are executed on VM2.

=== 1.1 Connect to MariaDB ===
<pre>
mysql -u root -p
</pre>

=== 1.2 Create the database ===
<pre>
CREATE DATABASE newwiki
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
</pre>

=== 1.3 Create the database user ===
Replace <code>VM1-IP</code> with the internal Hyper‑V IP of the web server.

<pre>
CREATE USER 'newwikiuser'@'VM1-IP' IDENTIFIED BY 'strongpassword';
</pre>

=== 1.4 Grant privileges ===
<pre>
GRANT ALL PRIVILEGES ON newwiki.* TO 'newwikiuser'@'VM1-IP';
FLUSH PRIVILEGES;
</pre>

=== 1.5 Exit MariaDB ===
<pre>
EXIT;
</pre>

== 2. Prepare the Installation Directory (VM1 – Web Layer) ==
All commands below are executed on VM1.

=== 2.1 Create the target directory ===
<pre>
mkdir /var/www/newMW
</pre>

=== 2.2 Move into the working directory ===
<pre>
cd /var/www
</pre>

== 3. Download MediaWiki ==
Download the latest LTS tarball (example: 1.43.8):

<pre>
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.8.tar.gz
</pre>

== 4. Extract MediaWiki ==
Extract the archive. This creates a directory such as <code>mediawiki-1.43.8/</code>.

<pre>
tar -xvzf mediawiki-1.43.8.tar.gz
</pre>

== 5. Move Extracted Files into newMW ==
Move normal files:

<pre>
mv mediawiki-1.43.8/* newMW/
</pre>

Move hidden files (e.g. <code>.htaccess</code>):

<pre>
mv mediawiki-1.43.8/.* newMW/ 2>/dev/null
</pre>

Remove the now‑empty extraction directory:

<pre>
rmdir mediawiki-1.43.8
</pre>

Remove the tarball:

<pre>
rm mediawiki-1.43.8.tar.gz
</pre>

== 6. Ownership and Permissions ==
Use the preferred ownership model to allow editing via VS Code while keeping
Apache fully functional.

=== 6.1 Set owner and group ===
<pre>
chown -R mngr:apache /var/www/newMW
</pre>

=== 6.2 Ensure group write permissions ===
<pre>
chmod -R g+w /var/www/newMW
</pre>

=== 6.3 Apply clean directory/file permissions ===
Directories:

<pre>
find /var/www/newMW -type d -exec chmod 775 {} \;
</pre>

Files:

<pre>
find /var/www/newMW -type f -exec chmod 664 {} \;
</pre>

=== 6.4 Enable group inheritance (setgid) ===
Ensures new files created inside inherit the <code>apache</code> group.

<pre>
chmod g+s /var/www/newMW
</pre>

== 7. Enable Apache to Listen on Port 8080 (VM1) & Virtual Host file ==
Apache does not automatically listen on new ports defined in VirtualHost
blocks. The port must be explicitly enabled in the main configuration.

=== 7.1 Edit the main Apache configuration ===
Open the file:

<pre>
/etc/httpd/conf/httpd.conf
</pre>

Locate the existing Listen directive:

<pre>
Listen 80
</pre>

Add the following line directly below it:

<pre>
Listen 8080
</pre>

=== 7.2 Validate the configuration ===
<pre>
apachectl configtest
</pre>

Expected output:

<pre>
Syntax OK
</pre>

=== 7.3 Restart Apache ===
<pre>
systemctl restart httpd
</pre>

=== 7.4 Verify Apache is listening on port 8080 ===
<pre>
ss -tlnp | grep httpd
</pre>

Expected result:

<pre>
0.0.0.0:80
0.0.0.0:8080
</pre>

Apache is now ready to serve the temporary local-only vhost on port 8080.

=== 7.5 Local‑Only Apache Virtual Host (VM1) ===
This vhost allows installation and testing without involving the reverse‑proxy.

<pre>
<VirtualHost *:8080>
ServerName newmw.local
DocumentRoot /var/www/newMW

<Directory /var/www/newMW>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newmw-local-error.log
CustomLog /var/log/httpd/newmw-local-access.log combined
</VirtualHost>
</pre>

Restart Apache:

<pre>
systemctl restart httpd
</pre>

== 8. Run the Installer Locally ==
Access the installer using one of:

* <code>http://VM1-IP:8080</code>
* <code>http://newmw.local:8080</code> (if added to /etc/hosts)

Complete the installation.

The installer will generate a <code>LocalSettings.php</code> with:

<pre>
$wgServer = "http://VM1-IP:8080";
</pre>

Place the file in:

<pre>
/var/www/newMW/LocalSettings.php
</pre>

== 9. Local Testing ==
Before exposing the wiki publicly, verify:

* Page creation
* Editing
* File uploads (if enabled)
* User accounts
* Extensions
* Permissions
* Logging

This phase is isolated and safe.

== 10. Prepare for Public Access (VM3 – Reverse‑Proxy Layer) ==
Only after local testing is complete, add the nginx server block:

<pre>
server {
listen 80;
server_name newwiki.example.com;

location / {
proxy_pass http://VM1-IP:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
</pre>

Reload nginx:

<pre>
systemctl reload nginx
</pre>

== 11. Update LocalSettings.php for Public Access ==
Change:

<pre>
$wgServer = "https://newwiki.example.com";
</pre>

Optionally:

<pre>
$wgCanonicalServer = "https://newwiki.example.com";
</pre>

== 12. Final Verification ==
* Public URL loads correctly
* <code>/wiki/Main_Page</code> resolves
* Editing works
* Uploads work
* No rewrite errors in Apache logs
* nginx proxies correctly
* MariaDB connections succeed

== 13. Summary ==
This procedure installs MediaWiki in two safe phases:

* Phase 1: Local installation and validation on VM1
* Phase 2: Public exposure through VM3

This staged approach avoids dependency on the reverse‑proxy during installation
and allows controlled, low‑risk rollout.

= Addendum =

== Adding a New Domain + Certificate on VM3 (nginx + Certbot) ==
This procedure is used when onboarding a new subdomain to the reverse‑proxy layer on VM3.
It avoids the nginx/Certbot “missing certificate” failure by always starting with a minimal HTTP‑only configuration, issuing the certificate, and then enabling HTTPS.

=== 1. Create a minimal HTTP‑only reverse‑proxy config ===
Create <code>/etc/nginx/conf.d/<domain>.conf</code> with:

<syntaxhighlight lang="nginx">
# ============================================
# Reverse proxy (HTTP only)
# <domain>
# ============================================

server {
listen 80;
listen [::]:80;
server_name <domain>;

# ACME challenge (Certbot uses this)
location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

# Temporary: no HTTPS redirect until certificate exists
location / {
proxy_pass http://<backend-ip>:<backend-port>;

proxy_set_header Host <domain>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto http;
}
}
</syntaxhighlight>

Reload nginx:

<syntaxhighlight lang="bash">
sudo nginx -t
sudo systemctl reload nginx
</syntaxhighlight>

At this point the domain resolves over HTTP and Certbot can validate it.

=== 2. Issue the certificate using the nginx plugin ===
Run:

<syntaxhighlight lang="bash">
sudo certbot --nginx -d <domain>
</syntaxhighlight>

Certbot will:
* inject a temporary ACME location
* validate the domain
* obtain the certificate
* install it
* register it for automatic renewal

This step only works if nginx is running without SSL errors.

=== 3. Replace the config with the full HTTPS reverse‑proxy ===
After the certificate exists, replace the file with:

<syntaxhighlight lang="nginx">
# ============================================
# Reverse proxy (HTTPS)
# <domain>
# ============================================

# --- HTTP (redirect + ACME) ---
server {
listen 80;
listen [::]:80;
server_name <domain>;

location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

return 301 https://$host$request_uri;
}

# --- HTTPS ---
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;

server_name <domain>;

ssl_certificate /etc/letsencrypt/live/<domain>/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<domain>/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

location /.well-known/acme-challenge/ {
root /usr/share/nginx/html;
}

location / {
proxy_pass http://<backend-ip>:<backend-port>;

proxy_set_header Host <domain>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;

proxy_buffering on;
proxy_buffers 16 16k;
proxy_buffer_size 16k;

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}
</syntaxhighlight>

Reload nginx again:

<syntaxhighlight lang="bash">
sudo nginx -t
sudo systemctl reload nginx
</syntaxhighlight>

=== 4. Verification checklist ===
* <code>curl -I https://<domain></code> returns <code>200</code> or <code>301</code>
* Browser loads the site over HTTPS
* Login works
* File uploads work
* Optional: <code>certbot renew --dry-run</code>

ICT:MW Installation procedure 1.43 LTS

2026-04-03T14:38:58Z

Mngr:

ICT:MW Installation procedure 1.43 LTS

2026-04-03T13:36:33Z

Mngr:

ICT:MW Installation procedure 1.43 LTS

2026-04-03T13:31:41Z

Mngr:

= Installation Procedure for newMW (MediaWiki 1.43 LTS) =
This document describes the clean, reproducible installation workflow for
deploying a new MediaWiki instance (newMW) on the existing 3‑VM infrastructure.
It includes directory preparation, file extraction, permissions, database
creation, and the preferred ownership model for VS Code access.

== 1. Create the newwiki Database (VM2 – Database Layer) ==
All commands in this section are executed on VM2.

=== 1.1 Connect to MariaDB ===
<pre>
mysql -u root -p
</pre>

=== 1.2 Create the database ===
<pre>
CREATE DATABASE newwiki
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
</pre>

=== 1.3 Create the database user ===
Replace <code>VM1-IP</code> with the internal Hyper‑V IP of the web server.

<pre>
CREATE USER 'newwikiuser'@'VM1-IP' IDENTIFIED BY 'strongpassword';
</pre>

=== 1.4 Grant privileges ===
<pre>
GRANT ALL PRIVILEGES ON newwiki.* TO 'newwikiuser'@'VM1-IP';
FLUSH PRIVILEGES;
</pre>

=== 1.5 Exit MariaDB ===
<pre>
EXIT;
</pre>

== 2. Prepare the Installation Directory (VM1 – Web Layer) ==
All commands below are executed on VM1.

=== 2.1 Create the target directory ===
<pre>
mkdir /var/www/newMW
</pre>

=== 2.2 Move into the working directory ===
<pre>
cd /var/www
</pre>

== 3. Download MediaWiki ==
Download the latest LTS tarball (example: 1.43.8):

<pre>
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.8.tar.gz
</pre>

== 4. Extract MediaWiki ==
Extract the archive. This creates a directory such as <code>mediawiki-1.43.8/</code>.

<pre>
tar -xvzf mediawiki-1.43.8.tar.gz
</pre>

== 5. Move Extracted Files into newMW ==
Move normal files:

<pre>
mv mediawiki-1.43.8/* newMW/
</pre>

Move hidden files (e.g. <code>.htaccess</code>):

<pre>
mv mediawiki-1.43.8/.* newMW/ 2>/dev/null
</pre>

Remove the now‑empty extraction directory:

<pre>
rmdir mediawiki-1.43.8
</pre>

Remove the tarball:

<pre>
rm mediawiki-1.43.8.tar.gz
</pre>

== 6. Ownership and Permissions ==
Use the preferred ownership model to allow editing via VS Code while keeping
Apache fully functional.

=== 6.1 Set owner and group ===
<pre>
chown -R mngr:apache /var/www/newMW
</pre>

=== 6.2 Ensure group write permissions ===
<pre>
chmod -R g+w /var/www/newMW
</pre>

=== 6.3 Apply clean directory/file permissions ===
Directories:

<pre>
find /var/www/newMW -type d -exec chmod 775 {} \;
</pre>

Files:

<pre>
find /var/www/newMW -type f -exec chmod 664 {} \;
</pre>

=== 6.4 Enable group inheritance (setgid) ===
Ensures new files created inside inherit the <code>apache</code> group.

<pre>
chmod g+s /var/www/newMW
</pre>

== 7. Apache Virtual Host (VM1) ==
Create a vhost:

<pre>
<VirtualHost *:8080>
ServerName newwiki.example.com
DocumentRoot /var/www/newMW

<Directory /var/www/newMW>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newwiki-error.log
CustomLog /var/log/httpd/newwiki-access.log combined
</VirtualHost>
</pre>

Restart Apache:

<pre>
systemctl restart httpd
</pre>

== 8. nginx Reverse‑Proxy (VM3) ==
Add a server block:

<pre>
server {
listen 80;
server_name newwiki.example.com;

location / {
proxy_pass http://VM1-IP:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
</pre>

Reload nginx:

<pre>
systemctl reload nginx
</pre>

== 9. Run the MediaWiki Installer ==
Navigate to:

<pre>
https://newwiki.example.com
</pre>

Provide:
* Database: <code>newwiki</code>
* User: <code>newwikiuser</code>
* Password: (as created on VM2)
* Site name
* Admin account

Download <code>LocalSettings.php</code> and place it in:

<pre>
/var/www/newMW/LocalSettings.php
</pre>

== 10. Minimal Post‑Install Configuration ==
Add or verify:

<pre>
$wgServer = "https://newwiki.example.com";
$wgScriptPath = "";
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;
</pre>

Enable uploads (optional):

<pre>
$wgEnableUploads = true;
</pre>

Enable SyntaxHighlight:

<pre>
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
</pre>

== 11. Verification Checklist ==
* Site loads correctly
* <code>/wiki/Main_Page</code> resolves
* Editing works
* File uploads work (if enabled)
* No rewrite errors in Apache logs
* nginx proxies correctly
* MariaDB connections succeed

== 12. Summary ==
This procedure provides a clean, repeatable installation workflow for MediaWiki
1.43 LTS using the preferred ownership model (<code>mngr:apache</code>) and the
existing 3‑VM architecture. It ensures clarity, maintainability, and
successor‑friendly operation.

ICT:MW Installation procedure 1.43 LTS

2026-04-03T13:29:43Z

Mngr: Created page with "= Installation Procedure for newMW (MediaWiki 1.43 LTS) = This document describes the clean, reproducible installation workflow for deploying a new MediaWiki instance (newMW) on the existing 3‑VM infrastructure. It includes directory preparation, file extraction, permissions, and the preferred ownership model for VS Code access. == 1. Preparation == All commands are executed on VM1 (Web Layer). === 1.1 Create the target directory === <pre> mkdir /var/www/newMW </pre>..."

= Installation Procedure for newMW (MediaWiki 1.43 LTS) =
This document describes the clean, reproducible installation workflow for
deploying a new MediaWiki instance (newMW) on the existing 3‑VM infrastructure.
It includes directory preparation, file extraction, permissions, and the
preferred ownership model for VS Code access.

== 1. Preparation ==
All commands are executed on VM1 (Web Layer).

=== 1.1 Create the target directory ===
<pre>
mkdir /var/www/newMW
</pre>

=== 1.2 Move into the working directory ===
<pre>
cd /var/www
</pre>

== 2. Download MediaWiki ==
Download the latest LTS tarball (example: 1.43.8):

<pre>
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.8.tar.gz
</pre>

== 3. Extract MediaWiki ==
Extract the archive. This creates a directory such as <code>mediawiki-1.43.8/</code>.

<pre>
tar -xvzf mediawiki-1.43.8.tar.gz
</pre>

== 4. Move Extracted Files into newMW ==
Move normal files:

<pre>
mv mediawiki-1.43.8/* newMW/
</pre>

Move hidden files (e.g. <code>.htaccess</code>):

<pre>
mv mediawiki-1.43.8/.* newMW/ 2>/dev/null
</pre>

Remove the now‑empty extraction directory:

<pre>
rmdir mediawiki-1.43.8
</pre>

Remove the tarball:

<pre>
rm mediawiki-1.43.8.tar.gz
</pre>

== 5. Ownership and Permissions ==
Use the preferred ownership model to allow editing via VS Code while keeping
Apache fully functional.

=== 5.1 Set owner and group ===
<pre>
chown -R mngr:apache /var/www/newMW
</pre>

=== 5.2 Ensure group write permissions ===
<pre>
chmod -R g+w /var/www/newMW
</pre>

=== 5.3 Apply clean directory/file permissions ===
Directories:

<pre>
find /var/www/newMW -type d -exec chmod 775 {} \;
</pre>

Files:

<pre>
find /var/www/newMW -type f -exec chmod 664 {} \;
</pre>

=== 5.4 Enable group inheritance (setgid) ===
Ensures new files created inside inherit the <code>apache</code> group.

<pre>
chmod g+s /var/www/newMW
</pre>

== 6. Apache Virtual Host ==
Create a vhost on VM1:

<pre>
<VirtualHost *:8080>
ServerName newwiki.example.com
DocumentRoot /var/www/newMW

<Directory /var/www/newMW>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newwiki-error.log
CustomLog /var/log/httpd/newwiki-access.log combined
</VirtualHost>
</pre>

Restart Apache:

<pre>
systemctl restart httpd
</pre>

== 7. nginx Reverse‑Proxy (VM3) ==
Add a server block:

<pre>
server {
listen 80;
server_name newwiki.example.com;

location / {
proxy_pass http://VM1-IP:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
</pre>

Reload nginx:

<pre>
systemctl reload nginx
</pre>

== 8. Run the MediaWiki Installer ==
Navigate to:

<pre>
https://newwiki.example.com
</pre>

Provide:
* Database: <code>newwiki</code>
* User: <code>newwikiuser</code>
* Password: (as created on VM2)
* Site name
* Admin account

Download <code>LocalSettings.php</code> and place it in:

<pre>
/var/www/newMW/LocalSettings.php
</pre>

== 9. Minimal Post‑Install Configuration ==
Add or verify:

<pre>
$wgServer = "https://newwiki.example.com";
$wgScriptPath = "";
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;
</pre>

Enable uploads (optional):

<pre>
$wgEnableUploads = true;
</pre>

Enable SyntaxHighlight:

<pre>
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
</pre>

== 10. Verification Checklist ==
* Site loads correctly
* <code>/wiki/Main_Page</code> resolves
* Editing works
* File uploads work (if enabled)
* No rewrite errors in Apache logs
* nginx proxies correctly
* MariaDB connections succeed

== 11. Summary ==
This procedure provides a clean, repeatable installation workflow for MediaWiki
1.43 LTS using the preferred ownership model (<code>mngr:apache</code>) and the
existing 3‑VM architecture. It ensures clarity, maintainability, and
successor‑friendly operation.

ICT:MW Clean installation checklist version 1.43 LTS

2026-04-03T11:37:52Z

Mngr: Mngr moved page ICT:MW Clean installaiton checklist version 1.43 LTS to ICT:MW Clean installation checklist version 1.43 LTS without leaving a redirect

= Installation Checklist – MediaWiki 1.43 LTS =
This document provides a clean, reproducible installation procedure for
MediaWiki 1.43 LTS on AlmaLinux with Apache, PHP, MariaDB, and an nginx
reverse-proxy. It is designed for long-term stability and successor-friendly
maintenance.

== 1. Preparation ==
Before installing MediaWiki, ensure the server environment is ready.

=== 1.1 System Requirements ===
* AlmaLinux (or compatible RHEL-based system)
* Apache (httpd)
* PHP 8.1 or later
* MariaDB 10.5 or later
* nginx reverse-proxy (optional but recommended)
* SELinux/AppArmor configured or disabled as needed

=== 1.2 Install Required Packages ===
Install PHP and required extensions:
<pre>
dnf install php php-mbstring php-xml php-intl php-mysqlnd php-gd php-json php-cli php-opcache php-apcu
</pre>

Install Apache and MariaDB:
<pre>
dnf install httpd mariadb-server
</pre>

Enable and start services:
<pre>
systemctl enable --now httpd mariadb
</pre>

== 2. Database Setup ==
Create a clean database for the new wiki.

=== 2.1 Secure MariaDB ===
<pre>
mysql_secure_installation
</pre>

=== 2.2 Create Database and User ===
<pre>
CREATE DATABASE newwiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'newwikiuser'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON newwiki.* TO 'newwikiuser'@'localhost';
FLUSH PRIVILEGES;
</pre>

== 3. Download MediaWiki 1.43 LTS ==
Download and extract the LTS release.

<pre>
cd /var/www
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.0.tar.gz
tar -xvzf mediawiki-1.43.0.tar.gz
mv mediawiki-1.43.0 newwiki
</pre>

Set permissions:
<pre>
chown -R apache:apache /var/www/newwiki
</pre>

== 4. Apache Virtual Host ==
Create a dedicated vhost for the new wiki.

<pre>
<VirtualHost *:8080>
ServerName newwiki.example.com
DocumentRoot /var/www/newwiki

<Directory /var/www/newwiki>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newwiki-error.log
CustomLog /var/log/httpd/newwiki-access.log combined
</VirtualHost>
</pre>

Enable the site and restart Apache:
<pre>
systemctl restart httpd
</pre>

== 5. nginx Reverse-Proxy ==
Duplicate the working configuration from the old wiki.

Only change:
* <code>server_name</code>
* <code>proxy_pass</code> target
* SSL certificate paths

Example:
<pre>
server {
listen 80;
server_name newwiki.example.com;

location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
</pre>

Reload nginx:
<pre>
systemctl reload nginx
</pre>

== 6. Run the MediaWiki Installer ==
Navigate to:
<pre>
https://newwiki.example.com
</pre>

Provide:
* Database name: <code>newwiki</code>
* Database user: <code>newwikiuser</code>
* Database password
* Site name
* Admin account

Download the generated <code>LocalSettings.php</code> and place it in:
<pre>
/var/www/newwiki/LocalSettings.php
</pre>

== 7. Minimal Post-Install Configuration ==
Add only the essential customizations.

=== 7.1 URL Structure ===
Ensure these lines exist:
<pre>
$wgServer = "https://newwiki.example.com";
$wgScriptPath = "";
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;
</pre>

=== 7.2 Enable File Uploads (optional) ===
<pre>
$wgEnableUploads = true;
</pre>

=== 7.3 Install SyntaxHighlight (recommended) ===
<pre>
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
</pre>

=== 7.4 Create Custom Namespaces (optional) ===
<pre>
define("NS_TECH", 3000);
define("NS_TECH_TALK", 3001);
$wgExtraNamespaces[NS_TECH] = "Tech";
$wgNamespacesWithSubpages[NS_TECH] = true;
</pre>

== 8. Testing Checklist ==
Verify:
* <code>/wiki/Main_Page</code> loads correctly
* Editing works
* File uploads work (if enabled)
* Categories work
* Subpages work in custom namespaces
* Reverse-proxy preserves Host header
* No rewrite errors in Apache logs

== 9. Backup Checklist ==
Create a backup routine for:
* <code>/var/www/newwiki</code>
* <code>LocalSettings.php</code>
* MariaDB database <code>newwiki</code>

== 10. Maintenance Notes ==
* MediaWiki 1.43 is LTS until December 2027.
* Apply security updates within the 1.43 branch.
* Avoid unnecessary extensions to keep the system stable.

ICT:MW new MediaWiki Blueprint

2026-04-03T11:31:56Z

Mngr: Mngr moved page ICT:MW new MediaWIki Blueprint to ICT:MW new MediaWiki Blueprint without leaving a redirect

= Blueprint for Organising the New MediaWiki Instance =
This document provides a structured approach for building a clean, maintainable,
successor-friendly MediaWiki installation dedicated to documenting the Drupal
platform, the server environment, and operational procedures.

The goal is to replace the experimental, Cargo-based wiki with a new,
purpose-built documentation system that is clear, predictable, and easy to
maintain.

== 1. Purpose of the New Wiki ==
The new MediaWiki instance will serve as:
* A technical maintenance manual for Drupal
* A user documentation space for historians and editors
* A server operations manual (AlmaLinux, MariaDB, reverse proxy)
* A stable, structured knowledge base for long-term stewardship

It replaces the experimental wiki, which accumulated Cargo, PageForms,
temporary namespaces, and unstructured pages.

== 2. High-Level Structure ==
The new wiki is organised around three pillars:

=== 2.1 Technical Documentation (System Internals) ===
Covers:
* Drupal configuration
* Views, fields, display modes
* Custom modules and CSS overrides
* Multilingual configuration
* Asset architecture
* Maintenance workflows

=== 2.2 User Documentation (Functional Use) ===
Covers:
* How historians use the system
* How to add/edit content
* How to attach assets
* How to use the publisher view
* How to navigate multilingual content

=== 2.3 Server Documentation (Infrastructure) ===
Covers:
* AlmaLinux installation and updates
* MariaDB backup/restore
* Reverse proxy configuration
* Web server layout
* Deployment procedures

== 3. Namespaces ==
Namespaces provide top-level grouping. Suggested namespaces:

* '''Tech:''' – Technical implementation documentation
* '''Guide:''' – User-facing documentation
* '''Server:''' – Server and infrastructure documentation
* '''Admin:''' – Operational procedures, backups, deployments

These names are placeholders; choose names that fit your style.

== 4. Subpage Hierarchy (Pseudo-Folders) ==
Subpages create a clear, navigable hierarchy.

=== 4.1 Technical Documentation ===
<pre>
Tech/Overview
Tech/ContentTypes/Places
Tech/ContentTypes/Objects
Tech/Views/RecordView
Tech/Views/AssetChain
Tech/Modules/CustomWidgets
Tech/CSS/Overrides
Tech/Multilingual/Configuration
Tech/Permissions/Roles
</pre>

=== 4.2 User Documentation ===
<pre>
Guide/Overview
Guide/Editing/AddingRecords
Guide/Editing/Assets
Guide/Editing/Translations
Guide/Publishing/RecordView
</pre>

=== 4.3 Server Documentation ===
<pre>
Server/AlmaLinux/Installation
Server/AlmaLinux/Updates
Server/MariaDB/Backup
Server/MariaDB/Restore
Server/ReverseProxy/Configuration
Server/Web/DirectoryLayout
</pre>

=== 4.4 Admin Procedures ===
<pre>
Admin/Backup/Drupal
Admin/Backup/MediaWiki
Admin/Deployment/Drupal
Admin/Deployment/Server
Admin/Monitoring/Checks
</pre>

== 5. Categories ==
Categories allow cross-cutting grouping across namespaces.

Suggested categories:
* [[Category:Drupal]]
* [[Category:Views]]
* [[Category:Content Types]]
* [[Category:Server]]
* [[Category:Maintenance]]
* [[Category:User Guide]]

Pages can belong to multiple categories.

== 6. Page Template for Consistency ==
Use a standard template for all technical pages:

<pre>
= [Page Title] =
== Purpose ==
== Where Implemented ==
== Configuration Summary ==
== Dependencies ==
== Interaction With Other Subsystems ==
== Known Quirks ==
== How to Modify Safely ==
== How to Debug ==
</pre>

This ensures clarity and successor-friendliness.

== 7. Migration Strategy ==
The old wiki remains online as an archive.

Migration steps:
# Identify important pages worth keeping.
# Copy/paste them into the new wiki.
# Rewrite them using the new structure and template.
# Discard Cargo/PageForms-specific content.
# Delete or ignore experimental pages in the old wiki.

This avoids contamination of the new clean structure.

== 8. Extensions to Install ==
Keep the new wiki minimal.

Recommended:
* SyntaxHighlight (for code/config snippets)
* CategoryTree (optional)
* VisualEditor (optional)

Avoid:
* Cargo
* PageForms
* Semantic extensions

== 9. Benefits of This Approach ==
* Clean, predictable structure
* Easy navigation via namespaces and subpages
* Clear separation between technical, user, and server documentation
* No legacy noise from early experiments
* Easy onboarding for future maintainers
* Documentation grows in a controlled, organised way

== 10. Conclusion ==
This blueprint provides a structured foundation for building a new, clean,
long-term MediaWiki documentation system. It supports the survival of the
Drupal platform, the server environment, and the operational knowledge needed
to maintain them.

ICT:PL Adding new MediaWiki website

2026-04-03T11:29:59Z

Mngr: Mngr moved page ICT:PL Adding new MediaWIki website to ICT:PL Adding new MediaWiki website without leaving a redirect

= Infrastructure Overview and Procedure for Adding a New MediaWiki Instance =
This document describes the current three‑VM infrastructure used for hosting
Drupal, MediaWiki, and related services. It also explains how to add a new
MediaWiki instance (newMW) to the existing environment in a clean,
reproducible, and low‑risk manner.

== 1. High-Level Architecture ==
The system is composed of three virtual machines running on Hyper‑V. Each VM
has a clearly defined responsibility, forming a layered, production‑grade
architecture.

=== 1.1 VM1 – Web Layer (AlmaLinux) ===
* Runs Apache (httpd)
* Runs PHP
* Hosts:
** Drupal website
** oldMW (existing MediaWiki instance)
** newMW (to be added)
* Contains all Apache vhosts
* Contains all rewrite rules (important: rewrites are NOT in nginx)
* Receives traffic only from VM3 (reverse‑proxy)

=== 1.2 VM2 – Database Layer (AlmaLinux) ===
* Runs MariaDB
* Hosts multiple independent databases:
** drupal
** oldwiki
** newwiki (to be created)
* Accessible only from VM1 (internal Hyper‑V network)

=== 1.3 VM3 – Reverse‑Proxy Layer (AlmaLinux) ===
* Runs nginx
* Public-facing entry point
* Terminates HTTPS
* Routes incoming requests to VM1 based on domain name
* Does NOT perform URL rewriting
* Forwards Host header and client IP

== 2. Traffic Flow ==
# Client connects to VM3 (nginx) using HTTPS.
# nginx selects the correct server block based on the domain.
# nginx forwards the request to VM1 (Apache) using proxy_pass.
# Apache selects the correct vhost based on ServerName.
# Apache applies rewrite rules and serves the application.
# Application (Drupal or MediaWiki) connects to VM2 (MariaDB) as needed.

This separation ensures stability, clarity, and easy maintenance.

== 3. Why This Architecture Works Well ==
* Each VM has a single responsibility.
* nginx handles routing and SSL termination.
* Apache handles application logic and rewrites.
* MariaDB is isolated and easy to back up.
* Adding new sites is predictable and low-risk.
* No component needs to be modified outside its domain.

== 4. Adding a New MediaWiki Instance (newMW) ==
Adding newMW requires changes on all three VMs, but each change is small,
isolated, and predictable.

=== 4.1 Step 1 – Create the Database on VM2 (MariaDB) ===
Connect to MariaDB and create a new database and user:

<pre>
CREATE DATABASE newwiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'newwikiuser'@'VM1-IP' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON newwiki.* TO 'newwikiuser'@'VM1-IP';
FLUSH PRIVILEGES;
</pre>

Replace <code>VM1-IP</code> with the internal Hyper‑V IP of the web server.

=== 4.2 Step 2 – Install MediaWiki on VM1 (Web Layer) ===
Download and extract MediaWiki 1.43 LTS:

<pre>
cd /var/www
wget https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.0.tar.gz
tar -xvzf mediawiki-1.43.0.tar.gz
mv mediawiki-1.43.0 newMW
chown -R apache:apache /var/www/newMW
</pre>

=== 4.3 Step 3 – Create an Apache vhost on VM1 ===
Create a new vhost file:

<pre>
<VirtualHost *:8080>
ServerName newwiki.example.com
DocumentRoot /var/www/newMW

<Directory /var/www/newMW>
AllowOverride All
Require all granted
</Directory>

ErrorLog /var/log/httpd/newwiki-error.log
CustomLog /var/log/httpd/newwiki-access.log combined
</VirtualHost>
</pre>

Restart Apache:
<pre>
systemctl restart httpd
</pre>

=== 4.4 Step 4 – Add a Reverse‑Proxy Entry on VM3 (nginx) ===
Duplicate an existing server block and adjust only the domain and proxy target:

<pre>
server {
listen 80;
server_name newwiki.example.com;

location / {
proxy_pass http://VM1-IP:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
</pre>

Reload nginx:
<pre>
systemctl reload nginx
</pre>

=== 4.5 Step 5 – Run the MediaWiki Installer ===
Navigate to:
<pre>
https://newwiki.example.com
</pre>

Provide:
* Database: <code>newwiki</code>
* User: <code>newwikiuser</code>
* Password: (as created)
* Site name
* Admin account

Download <code>LocalSettings.php</code> and place it in:
<pre>
/var/www/newMW/LocalSettings.php
</pre>

=== 4.6 Step 6 – Minimal Configuration in LocalSettings.php ===
Add or verify:

<pre>
$wgServer = "https://newwiki.example.com";
$wgScriptPath = "";
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;
</pre>

Enable uploads if needed:
<pre>
$wgEnableUploads = true;
</pre>

Install SyntaxHighlight:
<pre>
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
</pre>

== 5. Verification Checklist ==
* <code>https://newwiki.example.com</code> loads correctly.
* <code>/wiki/Main_Page</code> resolves without errors.
* Editing works.
* File uploads work (if enabled).
* No rewrite errors in Apache logs.
* nginx logs show correct proxying.
* MariaDB logs show successful connections from VM1.

== 6. Summary ==
Adding a new MediaWiki instance is straightforward because:
* nginx handles only routing.
* Apache handles rewrites and vhosts.
* MariaDB handles isolated databases.
* Each VM has a clear, stable role.
* The existing configuration already supports multi‑site operation.

This document provides a reproducible procedure for extending the system
without reintroducing the complexity or debugging effort experienced during
the initial setup.

ICT:PL Adding new MediaWiki website

2026-04-03T11:14:42Z

Mngr: Created page with "= Infrastructure Overview and Procedure for Adding a New MediaWiki Instance = This document describes the current three‑VM infrastructure used for hosting Drupal, MediaWiki, and related services. It also explains how to add a new MediaWiki instance (newMW) to the existing environment in a clean, reproducible, and low‑risk manner. == 1. High-Level Architecture == The system is composed of three virtual machines running on Hyper‑V. Each VM has a clearly defined resp..."

ICT:MW Clean installation checklist version 1.43 LTS

2026-04-03T11:07:58Z

Mngr: Created page with "= Installation Checklist – MediaWiki 1.43 LTS = This document provides a clean, reproducible installation procedure for MediaWiki 1.43 LTS on AlmaLinux with Apache, PHP, MariaDB, and an nginx reverse-proxy. It is designed for long-term stability and successor-friendly maintenance. == 1. Preparation == Before installing MediaWiki, ensure the server environment is ready. === 1.1 System Requirements === * AlmaLinux (or compatible RHEL-based system) * Apache (httpd) * PH..."

ICT:MW new MediaWiki Blueprint

2026-04-03T10:40:33Z

Mngr: Created page with "= Blueprint for Organising the New MediaWiki Instance = This document provides a structured approach for building a clean, maintainable, successor-friendly MediaWiki installation dedicated to documenting the Drupal platform, the server environment, and operational procedures. The goal is to replace the experimental, Cargo-based wiki with a new, purpose-built documentation system that is clear, predictable, and easy to maintain. == 1. Purpose of the New Wiki == The new..."

ICT:D Maintanance - WHAT to document

2026-04-03T10:18:59Z

Mngr: Created page with "= What to Document in the Drupal Implementation and Why = This document explains what should be documented in the technical wiki and why it is essential for long-term maintenance, debugging, and successor friendliness. == 1. Why Documentation Is Needed == As the system grows, it becomes impossible to remember: * which View controls which output * which field is translatable * which form mode hides which fields * which CSS hides which buttons * which custom module alters..."

= What to Document in the Drupal Implementation and Why =
This document explains what should be documented in the technical wiki and
why it is essential for long-term maintenance, debugging, and successor
friendliness.

== 1. Why Documentation Is Needed ==
As the system grows, it becomes impossible to remember:
* which View controls which output
* which field is translatable
* which form mode hides which fields
* which CSS hides which buttons
* which custom module alters which form
* which display mode is used where

Without documentation, debugging becomes guesswork.

== 2. What Must Be Documented ==
The following categories cover the entire Drupal implementation.

=== 2.1 Content Types ===
For each content type:
* Fields (name, type, translatability)
* Form display (widgets, hidden fields)
* Display modes (default, teaser, publisher view)
* Special behaviors (auto-generated values, computed fields)

=== 2.2 Views ===
Create a master index listing:
* View name
* Purpose
* Displays (page, block, feed)
* Contextual filters
* Relationships
* Where it is used (menu, block, link)

Each View gets its own technical page using the template.

=== 2.3 Custom Modules ===
Document:
* What each module does
* Which hooks it implements
* Which forms it alters
* Which fields it touches
* Which Views it interacts with

This prevents “mystery behavior”.

=== 2.4 CSS Overrides ===
List:
* File name
* Selectors used
* Purpose of each rule

CSS is easy to forget and hard to debug.

=== 2.5 Multilingual Configuration ===
Document:
* Which fields are translatable
* Which are shared
* How translation workflow works
* Which tabs are hidden
* Language negotiation settings

This prevents multilingual chaos.

=== 2.6 Permissions and Roles ===
Document:
* Which role can edit what
* Which role can translate
* Which role can see publisher view
* Which role can manage assets

Permissions often explain “why something is missing”.

=== 2.7 Asset Architecture ===
Document:
* How assets are linked to records
* Which View displays them
* How the asset-chain works
* How the modal behaves (if any)

=== 2.8 UI Customizations ===
Document:
* Hidden buttons
* Hidden tabs
* Custom form modes
* Custom display modes

These are easy to forget and hard to rediscover.

== 3. How to Organize the Documentation ==
Recommended structure:

* /Technical/Content Types/
* /Technical/Views/
* /Technical/Modules/
* /Technical/CSS/
* /Technical/Multilingual/
* /Technical/Permissions/
* /Technical/Assets/
* /Technical/Record View/

Each page uses the same template for consistency.

== 4. When to Document ==
Document immediately after implementing a feature:
* not the design
* not the intention
* but the actual implementation

This prevents forgetting crucial details.

== 5. Benefits ==
* Faster debugging
* Clear overview of system behavior
* Successor-friendly architecture
* Reduced risk of breaking workflows
* Confidence when making changes

ICT:D - Maintenance TEMPLATE

2026-04-03T10:17:37Z

Mngr: Created page with "= [Subsystem Name] – Technical Implementation Documentation = This page documents the *actual implementation* of this subsystem in Drupal. It is not about design intentions, but about how the system is configured, where it lives, and how to maintain or debug it. == 1. Purpose == Describe in 2–3 lines what this subsystem is supposed to do. Example: * Provides a read-only publisher view of a record. * Displays the asset table for the selected node. == 2. Where It Is..."

= [Subsystem Name] – Technical Implementation Documentation =
This page documents the *actual implementation* of this subsystem in Drupal.
It is not about design intentions, but about how the system is configured,
where it lives, and how to maintain or debug it.

== 1. Purpose ==
Describe in 2–3 lines what this subsystem is supposed to do.
Example:
* Provides a read-only publisher view of a record.
* Displays the asset table for the selected node.

== 2. Where It Is Implemented ==
List exact Drupal UI locations and file paths.

=== 2.1 Drupal UI Locations ===
* Content type: <code>[Content Type Name]</code>
* Manage fields: <code>[Field Name]</code>
* Manage form display: <code>[Form Mode]</code>
* Manage display: <code>[View Mode]</code>
* View: <code>[View Name] → [Display Name]</code>
* Block placement: <code>[Theme] → [Region]</code>

=== 2.2 Custom Code Locations (if any) ===
* Module: <code>custom_[module_name]</code>
* File: <code>src/Plugin/.../...</code>
* Hook: <code>hook_form_alter()</code> or similar

=== 2.3 CSS Overrides (if any) ===
* File: <code>themes/custom/[theme]/css/[file].css</code>
* Selectors used:
* <code>.some-selector { display: none; }</code>

== 3. Configuration Summary ==
Bullet list of the important settings.

Example:
* Field <code>field_assets</code> is NOT translatable.
* View uses contextual filter <code>Content: Nid</code>.
* Display mode “Publisher view” hides metadata fields.

== 4. Dependencies ==
List modules, fields, or other subsystems this depends on.

Example:
* Depends on: Views, Media, Asset-chain View.
* Requires field <code>field_assets</code> to exist.

== 5. Interaction With Other Subsystems ==
Explain how this subsystem connects to others.

Example:
* The asset table is embedded using the Asset-chain View.
* The admin listing links to this view via a custom URL.

== 6. Known Quirks ==
Document anything Drupal does that is “special”.

Example:
* Contextual filter fails if node is unpublished.
* Translation tab appears even though no fields are translatable.

== 7. How to Modify It Safely ==
Step-by-step instructions for future changes.

Example:
# Edit the View “Record View – Places”.
# Do NOT change the contextual filter.
# Add new fields only at the bottom of the field list.

== 8. How to Debug ==
Where to look when something goes wrong.

Example:
* If assets do not appear → check relationship in the View.
* If the page is empty → check contextual filter.
* If translation behaves oddly → check field translatability.

ICT:D Publish ready view of a record

2026-04-03T10:01:55Z

Mngr: Created page with "= Publisher-Ready Single Record View (Drupal UI Only) = This document describes how to create a clean, read-only “record view” for any content type. The goal is to provide publishers with a page that shows: * The most important fields of the record * A full description text * A table of attached assets * Links to the asset-chain view * No edit buttons, no tabs, no clutter All steps use Drupal UI only. No custom code is required. == 1. Create a New View for Single-..."

= Publisher-Ready Single Record View (Drupal UI Only) =
This document describes how to create a clean, read-only “record view” for any
content type. The goal is to provide publishers with a page that shows:

* The most important fields of the record
* A full description text
* A table of attached assets
* Links to the asset-chain view
* No edit buttons, no tabs, no clutter

All steps use Drupal UI only. No custom code is required.

== 1. Create a New View for Single-Record Display ==
Navigate to:
<pre>
Structure → Views → Add view
</pre>

Configure the new View:

* '''View name:''' Record View – [Your Content Type]
* '''Show:''' Content
* '''Of type:''' Your content type
* '''Create a page:''' Yes
* '''Page path:''' <code>/record-view/%</code>
* '''Page display:''' Unformatted list (or Fields)
* '''Items per page:''' 1
* '''Menu:''' None
* '''Pager:''' None

This creates a page that will display exactly one record.

== 2. Add a Contextual Filter to Load the Correct Record ==
In the View:

1. Add contextual filter: '''Content: Nid'''
2. Configure it as follows:

<pre>
When the filter value is NOT in the URL → Display nothing
When the filter value IS in the URL → Load the corresponding record
</pre>

This makes the View show the record whose node ID appears in the URL.

Example:
<pre>
/record-view/123
</pre>
shows record 123.

== 3. Choose Which Fields to Display ==
Remove all default fields.

Add only the fields you want publishers to see, for example:

* Title
* Description (full text)
* Summary
* Key metadata fields
* Location
* Dates
* Any other important fields

Arrange them in a logical order.

This creates a clean, read-only presentation.

== 4. Add the Attached Assets Table ==
There are two possible methods.

=== 4.1 Method A: Using a Relationship (if assets are referenced directly) ===
If your content type has a media reference field:

1. Add relationship: '''Content → [Your Media Field]'''
2. Add fields from the Media entity:
* Media name
* Media type
* File URL
* Thumbnail
3. Set the View format to '''Table'''
4. Group or sort as needed

This produces a table of assets under the record.

=== 4.2 Method B: Embedding Your Existing Asset-Chain View ===
If you already have a View that lists assets for a record:

1. Add a new field: '''View field'''
2. Select your asset-chain View
3. Pass the node ID as contextual filter:
* Use token: <code>{{ nid }}</code>

This embeds the asset-chain table directly into the record view.

== 5. Add a Link from the Content Overview Table ==
Navigate to:
<pre>
Structure → Views → Content
</pre>

This is the admin listing of all records.

Add a new field:

* '''Global: Custom text'''

Configure it:

1. Enable “Rewrite results”
2. Use custom text such as:
<pre>
<a href="/record-view/{{ nid }}">View</a>
</pre>
3. Enable “Use replacement tokens”
4. Insert the token for node ID

This adds a “View” link next to each record.

== 6. Optional: Show the View Link Only for Completed Records ==
If you have a boolean field “Completed”:

1. Add the field to the admin View
2. In the “View” link field:
* Enable “Rewrite results”
* Add a condition:
<pre>
{% if completed == '1' %}
<a href="/record-view/{{ nid }}">View</a>
{% endif %}
</pre>

This ensures only finished records show the publisher view link.

== 7. Result ==
You now have:

* A clean, read-only page for each record
* A full description field
* A table of attached assets
* Links to the asset-chain
* A link from the admin table to this page
* No edit buttons, no tabs, no clutter
* A publisher-ready output suitable for drafting publications or website pages

== 8. Notes ==
* This solution uses only Drupal UI.
* No custom code, no theming, no templates.
* Works for multilingual sites.
* Works for all content types.
* Fully successor-friendly.

ICT:D Multilingual aspect

2026-04-03T09:48:54Z

Mngr: Created page with "= Drupal Multilingual Architecture: What Appears, What Is Possible, and How Translation Works = This document summarizes the changes that appear after enabling multilingual support in Drupal, and explains how both *foreground* (content) and *background* (configuration/UI) translation works. It also identifies the source of new interface clutter and what can be simplified later. == 1. What Appears After Enabling Multilingual == Enabling multilingual introduces several n..."

= Drupal Multilingual Architecture: What Appears, What Is Possible, and How Translation Works =

This document summarizes the changes that appear after enabling multilingual
support in Drupal, and explains how both *foreground* (content) and *background*
(configuration/UI) translation works. It also identifies the source of new
interface clutter and what can be simplified later.

== 1. What Appears After Enabling Multilingual ==
Enabling multilingual introduces several new subsystems:

=== 1.1 Language Negotiation ===
Drupal determines the language of each page using:
* URL prefix (e.g., /en, /nl)
* User preference
* Browser preference
* Session
* Default site language

This affects how content is displayed and which translations are loaded.

=== 1.2 Translatable Fields ===
Every field can be marked as:
* Translatable
* Not translatable

If a field is translatable, Drupal creates a separate value per language.

This causes:
* Additional language selectors
* Additional translation tabs
* Duplicate fieldsets in the edit form

=== 1.3 Translation Tabs on Nodes ===
Each node now shows:
* '''Edit'''
* '''Translate'''
* '''Revisions'''
* Language-specific edit pages (e.g., “Edit (Dutch)”)

This is normal but creates visual clutter.

=== 1.4 Interface Translation (UI Strings) ===
Drupal adds:
* A new “Translate Interface” screen
* A new “Languages” configuration page
* Automatic import of .po files for core and modules

This handles translation of system text, labels, and UI strings.

== 2. What Is Possible in Multilingual Drupal ==
Drupal supports two major translation domains:

=== 2.1 Foreground Translation (Content Translation) ===
This includes:
* Node titles
* Body text
* Field values
* Media fields
* Taxonomy terms (if enabled)
* Custom entities (if enabled)

Each language gets its own version of the content.

=== 2.2 Background Translation (Configuration Translation) ===
This includes:
* Field labels
* View labels
* Menu items
* Block titles
* Interface strings
* System messages

These translations are stored in configuration, not in content.

=== 2.3 Mixed Translation (Shared vs. Per-Language Fields) ===
Fields can be configured as:
* '''Translatable''' → separate value per language
* '''Non-translatable''' → shared across all languages

Choosing correctly reduces clutter.

== 3. How Foreground (Content) Translation Works ==
Content translation creates a separate “translation set” for each node.

=== 3.1 Workflow ===
1. Create the node in the default language.
2. Click “Translate”.
3. Add a translation (e.g., Dutch).
4. Only translatable fields appear for translation.
5. Non-translatable fields are shared.

=== 3.2 Storage Model ===
Each translation is stored as:
* A separate revision
* A separate language entry
* Linked to the same node ID

=== 3.3 Editor Experience ===
Editors see:
* A language selector
* A “Translate” tab
* Additional vertical tabs for language settings

== 4. How Background (Configuration/UI) Translation Works ==
Configuration translation handles:
* Field labels
* View labels
* Block titles
* Menu items
* Interface strings

=== 4.1 Where It Happens ===
Go to:
<pre>
Configuration → Regional and Language → Configuration translation
</pre>

=== 4.2 How It Works ===
Drupal extracts all translatable strings from:
* YAML configuration
* Module-provided strings
* Theme templates

You translate them once; they apply everywhere.

== 5. Why the Edit Form Now Looks Cluttered ==
Multilingual mode adds:
* A “Language” vertical tab
* A “Translate” tab
* A language selector on the edit form
* Duplicate fieldsets for translatable fields
* Additional metadata fields per language
* Extra tabs for each translation

This is normal but overwhelming.

== 6. What Can Be Simplified Later ==
After understanding the behavior, you can safely:

=== 6.1 Hide Unneeded Tabs ===
Using:
* Form modes
* Permissions
* hook_form_alter()

Examples:
* Hide “Authoring information”
* Hide “Promotion options”
* Hide “URL alias”
* Hide “Menu settings”

=== 6.2 Make Only a Few Fields Translatable ===
This reduces 70% of the clutter.

Typical fields to translate:
* Title
* Body
* Summary
* A few descriptive fields

Fields that usually stay shared:
* Images
* Dates
* Geolocation
* Internal metadata

=== 6.3 Simplify the Translation Workflow ===
Options:
* Remove the “Translate” tab
* Use inline translation only
* Limit languages per content type

== 7. Summary ==
Enabling multilingual introduces:
* New tabs
* New field behaviors
* New translation workflows
* More UI elements

This is expected. Once the behavior is understood, the interface can be
cleaned up significantly by:
* Reducing translatable fields
* Hiding unnecessary tabs
* Simplifying the translation workflow

This results in a clean, historian-friendly interface with minimal clutter.

ICT:D Multilingual Setup

2026-04-02T16:29:42Z

Mngr: Created page with "= Drupal Multilingual Setup Workflow (English → Dutch) = == Overview == This guide explains how to safely add Dutch to an existing English Drupal site. Steps: # Add Dutch language # Enable translation modules # Make content translatable # Configure fields # Add language switcher # Test with real content ---- == Step 1 — Add Dutch language == Go to: Configuration → Regional and language → Languages * Click '''Add language''' * Select: '''Dutch (Nederlands)'..."

= Drupal Multilingual Setup Workflow (English → Dutch) =

== Overview ==
This guide explains how to safely add Dutch to an existing English Drupal site.

Steps:
# Add Dutch language
# Enable translation modules
# Make content translatable
# Configure fields
# Add language switcher
# Test with real content

----

== Step 1 — Add Dutch language ==

Go to:
Configuration → Regional and language → Languages

* Click '''Add language'''
* Select: '''Dutch (Nederlands)'''
* Save

Drupal will automatically download translations.

----

== Step 2 — Enable required modules ==

Enable the following core modules:

* Language
* Content Translation
* Interface Translation

(Optional but recommended):
* Configuration Translation

----

== Step 3 — Enable translation for content type ==

Go to:
Structure → Content types → YOUR CONTENT TYPE → Edit

* Open '''Language settings'''
* Enable:
* ✔ Make this content type translatable

Save.

----

== Step 4 — Configure translatable fields ==

Go to:
Structure → Content types → YOUR CONTENT TYPE → Manage fields

For each field:

=== Make translatable ===
* Description
* Note
* Link (especially link title)

=== Usually NOT translatable ===
* IDs
* Technical/system fields

Rule of thumb:
* If humans read it → translatable
* If system uses it → not translatable

----

== Step 5 — Configure language settings ==

Go to:
Configuration → Regional → Content language

* Enable translation for your content type
* Set default language:
* English

Save configuration.

----

== Step 6 — Add language switcher ==

Go to:
Structure → Block layout

* Add block:
* Language switcher
* Place it in:
* Header or sidebar

Save block placement.

----

== Step 7 — Test with one content item ==

* Open an existing node
* Click the '''Translate''' tab
* Add Dutch translation
* Fill in translated fields:
* Description (NL)
* Note (NL)

Save.

----

== Step 8 — Translate interface elements ==

Go to:
Configuration → Regional → Translate interface

Translate:
* Field labels
* Help texts
* UI elements if needed

----

== How it works ==

Each content item becomes:

* English version (default)
* Dutch version (translation)

Users can switch language using the language switcher.

----

== Important notes ==

* If no Dutch translation exists:
* Drupal may show English (fallback)
* If translation exists:
* Drupal shows translated content

----

== Recommended approach ==

* Keep English as default language
* Add Dutch as translation
* Test with a few nodes before full rollout

----

== Editorial workflow ==

# Create content (English or Dutch)
# Click '''Translate'''
# Add second language
# Save

----

== Summary ==

* Drupal multilingual is stable and powerful
* Always translate entire content items (not separate fields per language)
* Start simple and expand gradually

ICT:D JSON based Multi-Link Field

2026-04-02T15:02:28Z

Mngr: Created page with "= JSON-Based Multi-Link Field Architecture = This document summarizes a proposed architecture for storing and managing 0…N website links per record in Drupal, using a single text field containing JSON and a modal-based custom widget. The goal is: * A clean edit form (one line only) * A modal to manage multiple links * Deterministic behavior (no handler surprises) * Easy rendering in Views and Twig * Reusable across all content types == 1. Overview == Instead of using..."

= JSON-Based Multi-Link Field Architecture =
This document summarizes a proposed architecture for storing and managing
0…N website links per record in Drupal, using a single text field containing
JSON and a modal-based custom widget.

The goal is:
* A clean edit form (one line only)
* A modal to manage multiple links
* Deterministic behavior (no handler surprises)
* Easy rendering in Views and Twig
* Reusable across all content types

== 1. Overview ==
Instead of using Drupal’s multi-value Link field (which clutters the edit form),
a single text field is used to store all links in JSON format.

Each record stores its own JSON string. There is no global file.

Example JSON stored in the field:
<pre>
[
{ "label": "Foo", "url": "https://foo.com" },
{ "label": "Bar", "url": "https://bar.com" }
]
</pre>

== 2. Edit Form UX ==
The edit form shows only one line:
<pre>
Website links: [ Manage links ]
</pre>

Clicking the button opens a modal where the editor can:
* Add a link
* Edit a link
* Remove a link
* Reorder links

When the modal is saved, the JSON is written back into the field.

== 3. Storage Model ==
A single field (e.g., <code>field_links_json</code>) stores the JSON string.

Characteristics:
* One JSON string per record
* No shared storage
* No extra entities required
* Deterministic and simple

== 4. Rendering in Twig ==
Twig can decode and loop through the JSON:
<pre>
{% set links = node.field_links_json.value|json_decode %}
<ul>
{% for link in links %}
<li><a href="{{ link.url }}">{{ link.label }}</a></li>
{% endfor %}
</ul>
</pre>

== 5. Rendering in Views ==
A small custom Views field handler is used.

Responsibilities:
* Read the JSON string
* Decode it
* Render 0…N links as HTML or a render array

This keeps Views clean and avoids exposing raw JSON.

== 6. Reusability ==
This architecture works for:
* All records in a content type
* Any number of content types
* Any custom entity type

The field and widget are generic and reusable.

== 7. Module Complexity Estimate ==
Approximate code size:
* Field widget: 80–120 lines
* Modal form: 100–150 lines
* Views field handler: 60–80 lines
* Module scaffolding: 20–40 lines

Total: ~260–390 lines of code.

== 8. Advantages ==
* Clean edit form (one line only)
* Deterministic behavior
* No multi-value field clutter
* No handler switching
* Easy to render in Twig and Views
* Successor-friendly and maintainable
* Reusable across the entire system

== 9. Considerations ==
* Links are not reusable across records (by design)
* Requires a small custom module
* JSON must be validated in the modal

== 10. Conclusion ==
This JSON-based approach provides a clean, predictable, and maintainable
solution for managing multiple website links per record, without cluttering
the edit form or relying on Drupal’s multi-value field behavior.

Research:Drupal Glossary

2026-03-31T16:22:24Z

Mngr:

= '''Drupal Glossary''' =
'''Ajax'''

A web technology used to exchange data with a server to dynamically update parts of a web page (for example, forms) without needing entire page reloads.

'''Alias'''

A user-friendly name to replace the internal path that the system assigns to a URL on the site. For example, you might assign an alias of ''/about'' to the About page on your site, to replace the internal path ''/node/5''. This would give the page a URL of ''<nowiki>http://example.com/about</nowiki>'' instead of ''<nowiki>http://example.com/node/5</nowiki>''.

'''Anonymous'''

A person (user) interacting with the site who is not logged in.

'''Authenticated'''

A person (user) interacting with the site who is logged in.

'''Block'''

A chunk of content (text, images, links, etc.) that can be displayed on a page of a site. Blocks are displayed in regions.

'''Breakpoint'''

Breakpoints are used to separate the height or width of browser screens, printers, and other media output types into steps. A responsive site adjusts its presentation at these breakpoints.

'''Bundle'''

Synonym for Entity subtype.

'''Cache'''

The site’s internal cache stores the output of time-consuming calculations, such as computing output for an HTML page request, and then retrieves them instead of recalculating the next time they are needed. External caching systems can also be used on the web server to speed up a site’s response.

'''Coding standards'''

Coding standards are the rules for programmers that define best practices, formatting, and various other rules, so that everyone uses the same conventions and has the same expectations when they see code.

'''Composer'''

The PHP dependency manager used by Drupal, Drush, the Symfony framework and others. It is the preferred means of installing Drupal projects.

'''CMS'''

Acronym for Content Management System.

'''Configuration'''

Information about your site that is not content, and is meant to be more permanent than state information, such as the name of your site, the content types and views you have defined, etc.

'''Content'''

Information meant to be displayed on your site, such as text, images, downloads, etc. See also Configuration and State.

'''Content item'''

An item of content that is typically meant to be displayed as the main content of a page on your site. This is an entity type.

'''Content Management System (CMS)'''

A collection of tools designed to allow the creation, modification, organization, search, retrieval and removal of information on a website.

'''Content type'''

An entity subtype for the content item entity type. Each content type is used for some particular purpose on the site, and each has its own fields. For example, a site for a farmers market might have a content type for simple pages, and another for a vendor listing page.

'''Contextual Filter (in a View)'''

Limits the data to be output in a view, based on the context of the view display, such as the full URL of the page.

'''Contextual link'''

A link to an administrative page for editing or configuring a feature of the site, shown in the context where that feature is displayed. Example: a link to configure a menu that is shown when you hover your mouse over the menu.

'''Contributed'''

Modules, themes, and distributions that are not part of the Drupal core download, and that can be downloaded separately from the ''Drupal.org'' website.

'''Cron'''

On some operating systems, ''cron'' is a command scheduler application that executes commands or scripts periodically. Your site defines periodic tasks, also known as cron tasks, that need to be triggered either by an operating system cron scheduler, or internally.

'''Cross Site Scripting'''

Security vulnerability typically found in websites. In a site that is not well protected, malicious users can enter script into web pages that are viewed by other users.

'''Devel'''

Module that helps with development tasks such as debugging and inspecting code, analyzing database queries, and generating dummy content.

'''Development site'''

Copy of the live website that is used for developing, updating, and testing the website.

'''Display (in a View)'''

Type of output of a view, for example a page, a block or a feed.

'''Distribution'''

A single download that provides a shortcut for setting up a specific type of site, such as a website for a club or for e-commerce. A distribution contains Drupal core, along with contributed modules and/or themes; many distributions also pre-configure the site or even create sample content upon installation.

'''Drupal Association'''

Non-profit organization dedicated to supporting the Drupal project and community.

'''Drupal core'''

The files, themes, profiles, and modules included with the standard project software download.

'''Drush'''

Command line shell and scripting interface for Drupal.

'''Editorial Workflow'''

Process to create, review, edit, and publish content. Multiple people in different roles (for example content creators and editors) can be part of the process.

'''Entity'''

An item of either content or configuration data, although in common usage, the term often refers to content entities. Examples include content items, custom blocks, taxonomy terms, and definitions of content types; the first three are content entities, and the last is a configuration entity. See also Entity type, Entity subtype, and Field.

'''Entity subtype'''

Within a content entity type, a grouping of entities that share the same fields. For example, within the content item entity type, a farmers market site might have subtypes (known as content types) for static pages and vendor pages, each with its own group of fields. You may also see the term ''bundle'' used (especially in programmer documentation) as a synonym of entity subtype.

'''Entity type'''

The overall type of an entity; in common usage, it is only applied to a content entity. Examples include content types, taxonomy terms, and custom blocks.

'''Field'''

Data of a certain type that is attached to a content entity. For instance, on a farmers market site’s vendor content type, you might have fields for an image, the vendor description, and a taxonomy term.

'''Field bundle'''

Synonym for Entity subtype.

'''Field formatter'''

Configuration that defines how the data in a field is displayed. For example, a text field could be displayed with a prefix and/or suffix, and it could have its HTML tags stripped out or limited. See also View mode and Field widget.

'''Field widget'''

Configuration that defines how someone can enter or edit data for a field on a data entry form. For example, a text field could use a single-line or multi-line entry box, and there could be a setting for the size of the box.

'''Filter (in a View)'''

Limits the data to be output in a view, based on criteria such as publication status, type of content, or field value.

'''Formatter'''

See Field formatter.

'''FOSS'''

Acronym for ''Free and Open Source Software'', meaning software that is developed by a community of people and released under a non-commercial license.

'''Git'''

Version control system used by Drupal developers to coordinate their individual code changes. Git records everyone’s changes to a given project in a directory tree called a git repository.

'''GPL'''

Acronym for the ''GNU General Public License'', a non-commercial software license. All software downloaded from the ''Drupal.org'' website is licensed under the "GNU General Public License, version 2".

'''Image style'''

A set of processing steps that transform a base image into a new image; typical processing includes scaling and cropping.

'''Installing'''

Preparing Drupal core or any contributed theme or module for usage. In the case of Drupal core this means downloading the necessary files, creating the database, configuring and running the installation script.

'''LAMP'''

Acronym for ''Linux, Apache, MySQL, and PHP'': the software on the web server that the scripts commonly run on (although it can use other operating systems, web servers, and databases).

'''Log'''

A list of recorded events on the site, such as usage data, performance data, errors, warnings, and operational information.

'''Menu'''

A set of links used for navigation on a site, which may be arranged in a hierarchy.

'''Module'''

Software (usually PHP, JavaScript, and/or CSS) that extends site features and adds functionality. The Drupal project distinguishes between ''core'' and ''contributed'' modules.

'''Path'''

The unique, last part of the internal URL that the system assigns to a page on the site, which can be a visitor-facing page or an administrative page. For example, the internal URL for the About page on your site might be ''<nowiki>http://example.com/node/5</nowiki>'', and in this case, the path is ''node/5''. See also Alias.

'''Permission'''

The ability to perform some action on the site, such as editing a particular type of content, or viewing user profiles. See also Role.

'''Reference field'''

A field that represents a relationship between an entity and one or more other entities, which may be the same entity type or a different type. For example, on a farmers market site, a recipe content item might have a reference field to the vendor (also a content item) that posted the recipe. Taxonomy term fields are also reference fields.

'''Region'''

A defined area of a page where content can be placed, such as the header, footer, main content area, left sidebar, etc. Regions are defined by themes, and the content displayed in each region is contained in blocks.

'''Relationship (in a View)'''

Expansion of the data that is displayed in a view, by relating the base content to other content entities.

'''Repository'''

Location where a version control system stores all the files and directories for a project.

'''Responsive'''

A site or theme is said to be responsive if it adjusts its presentation in response to the size of the browser screen, printer, or other media output type. See also Breakpoint.

'''Revision'''

A record of the past or present state of a content entity, as it is edited over time.

'''Role'''

A named set of permissions that can be applied to a user account.

'''Security update'''

An update that fixes a security-related bug, such as a hacking vulnerability.

'''Session'''

Information about individual site visitors' interactions with the site, such as whether they are logged in and their cookies.

'''Staging site'''

Copy of the live website that can be used for testing, or presenting the changes to the client for approval.

'''State'''

Information of a temporary nature about the current state of your site, such as the time when cron was last run, etc. See also Content and Configuration.

'''Taxonomy'''

The process of classifying content.

'''Taxonomy term'''

A term used to classify content, such as a tag or a category. See also Vocabulary.

'''Text format'''

Configuration that defines the processing that happens to user-entered text before it is shown in the browser. This might include stripping or limiting HTML tags, or turning URLs into links.

'''Theme'''

Software and asset files (images, CSS, PHP code, and/or templates) that determine the style and layout of the site. The Drupal project distinguishes between ''core'' and ''contributed'' themes.

'''UI'''

Acronym for ''User Interface''.

'''Update'''

A newer version of your site’s software, either Drupal core or a module or theme. See also Security update.

'''URL'''

A web page’s unique address on the web. For example <nowiki>https://example.com/node/7</nowiki>.

'''User'''

A person interacting with the site, either logged-in or anonymous.

'''User interface'''

The text, styles, and images that are visible on a site, separated logically into the user interface for site visitors and the administrative user interface.

'''User one (User 1)'''

The initial user account that is created when you install the site (whose ID number is 1). It automatically has all permissions, even if it is not assigned an administrative role.

'''Version Control System'''

Software that keeps copies of files and revision history in a repository, and allows you to add, delete, and update files.

'''View'''

A formatted listing of data; typically, the data comes from content entities. For example, on a farmers market site, you might create a content item for each vendor. You could then make view that generates a listing page that shows a thumbnail image and short description of each vendor, linking to the full-page content item. Using the same data, you could also make a view that generates a new vendors block, which would show information from the most recently added vendors.

'''View mode'''

A set of field formatter configuration for all of the fields of a content entity, some of which may be hidden. Each entity subtype can have one or more view modes defined; for example, content types typically have ''Full'' and ''Teaser'' view modes, where the ''Teaser'' view mode displays fewer or trimmed-down fields.

'''Vocabulary'''

A group of taxonomy terms to choose from when classifying content in a particular way, such as the list of all of the vendor categories on a farmers market site. Technically, vocabularies are the entity subtype for the taxonomy term entity type.

'''Widget'''

Configuration that defines how someone can enter or edit data for a field on a data entry form. For example, a text field could use a single-line or multi-line entry box, and there could be a setting for the size of the box. See also Field formatter.

'''Wizard'''

A web form that allows you to fill in a few values, and creates something with sensible defaults based on the values you chose. For example, there are wizards for creating views of different types.

'''WYSIWYG'''

Acronym for ''What You See is What You Get'', meaning a method for editing content where what you see on the editing screen closely resembles the final product.

'''Workflow'''

See Editorial Workflow.

'''XSS'''

Acronym for Cross Site Scripting.

Research:Drupal Glossary

2026-03-31T16:20:55Z

Mngr: Created page with "dd"

ICT:Final Chapter Architecture

2026-03-31T13:24:56Z

Mngr: Created page with "= Final Chapter Architecture = This page documents the final, endorsed structure for CHAPTER, PLACE, and ORGANISATION within the research platform. It reflects the architectural simplification reached after analysis and Excel validation. == 1. CHAPTER Structure (Flat, Non‑Recursive) == The CHAPTER entity is now: * Flat (no recursion) * Non‑hierarchical * Narrative-only * Max. 3 characters * Two families: ** Txx — time‑based narrative chapters ** Xxx — the..."

= Final Chapter Architecture =

This page documents the final, endorsed structure for CHAPTER, PLACE, and ORGANISATION within the research platform.
It reflects the architectural simplification reached after analysis and Excel validation.

== 1. CHAPTER Structure (Flat, Non‑Recursive) ==

The CHAPTER entity is now:

* Flat (no recursion)
* Non‑hierarchical
* Narrative-only
* Max. 3 characters
* Two families:
** Txx — time‑based narrative chapters
** Xxx — thematic or contextual chapters

There are no subchapters such as T00a, T00b, etc.
All narrative subdivision is handled by PLACE and ORGANISATION.

=== Examples ===

T00 – Before the main period
T01 – Early developments
T02 – First migrations
T06 – WW2
T07 – Post‑war period

X00 – Methodology
X01 – Sources
X02 – Transport & technology
X03 – Family context

CHAPTER codes remain stable and short to keep asset numbering clean.

== 2. PLACE Structure (Recursive, 6‑Character Codes) ==

PLACE is the primary engine for narrative subdivision.
It remains:

* Recursive (multi‑level hierarchy)
* Geographical
* User‑defined
* Using full 6‑character codes
* The natural source of “subchapter‑like” separation

PLACE captures geographical storylines such as:

* WW2 in Ostende
* Children in Alton
* Children in Bristol
* Sanas in Italy and Germany

=== Example PLACE Hierarchy ===

EUROPE
UK
ALTON
BRIST
BELGIUM
OSTEND
ITALY
GERMANY

PLACE codes (6 chars) are used directly in asset numbering.

== 3. ORGANISATION Structure (Recursive, 6‑Character Codes) ==

ORGANISATION is also recursive and captures institutional storylines.

It remains:

* Recursive
* User‑defined
* 6‑character codes
* Parallel to PLACE in structure and purpose

=== Example ORGANISATION Hierarchy ===

SANAS
SANAS-IT
SANAS-DE

This allows assets to be grouped by institutional context.

== 4. Asset Numbering (Clean, Stable) ==

Asset numbering uses:

<Chapter.Code> – <Place.Code OR Organisation.Code> – <Counter(5)>

Because CHAPTER is flat and fixed-length, numbering remains clean and aligned.

=== Examples ===

T06-OSTEND-00012
T00-ALTON-00013
T00-BRIST-00014
T00-UKPRE-00015

This structure automatically groups assets by:

* Chapter (narrative period)
* Place (geographical storyline)
* Organisation (institutional storyline)

No subchapter codes are needed.

== 5. Why Subchapters Are No Longer Needed ==

Subchapters were originally used to subdivide narrative chapters (e.g., CH06a, CH00b).
After analysis, it became clear that:

* These subdivisions were geographical or institutional, not structural.
* PLACE and ORGANISATION already provide natural, recursive subdivision.
* Adding subchapter codes would pollute asset numbering.
* CHAPTER should remain a top‑level narrative container only.

Therefore:

'''Subchapters are now expressed through PLACE and ORGANISATION, not through CHAPTER.'''

== 6. Benefits of the Final Architecture ==

* Clean, stable CHAPTER codes
* Powerful recursive PLACE and ORGANISATION hierarchies
* Natural narrative subdivision without extra fields
* Clean asset numbering
* Strong filtering for publications (Chapter + Place + Organisation + Keywords)
* Easy to explain to club members
* Successor‑friendly and future‑proof

== 7. Status ==

This structure has been validated through Excel analysis and is ready for presentation to the club members for endorsement.
Once approved, it becomes the final, stable architecture for all future research, publications, and digital heritage workflows.

ICT:Asset-Chain Children Button logic (with boolean field)

2026-03-30T16:44:41Z

Mngr:

== Asset Hierarchy: "Children" Button Logic ==

=== Overview ===
This implementation displays a clickable button in the Top Assets table only when an asset has at least one child. It avoids complex and performance-heavy Views relationships by using a data-driven boolean flag.

=== Data Model ===
* '''Entity Type:''' Asset (or Node)
* '''Parent Field:''' <code>field_as_parent_asset</code> (Entity Reference pointing to the parent).
* '''Indicator Field:''' <code>field_as_has_children</code> (Boolean).
** Default: Off (0)
** Logic: Marks if a Top Asset is a parent.

=== Automation (The Tweak Module) ===
The logic is handled automatically by the '''Heritage Tweaks''' module via <code>hook_entity_presave</code>.

* '''Trigger:''' When a child asset is saved.
* '''Action:''' The code identifies the parent referenced in <code>field_as_parent_asset</code>.
* '''Result:''' It programmatically flips the parent's <code>field_as_has_children</code> to '''True (1)'''.

=== Views Configuration ===
The button is rendered using a '''Global: Custom Text''' field in the Assets View.

==== Logic ====
The button uses Twig to check the boolean state before rendering:
<syntaxhighlight lang="twig">
{% if field_as_has_children %}
<a href="/admin/asset-chain/{{ nid }}" class="button button--primary">Children</a>
{% endif %}
</syntaxhighlight>

==== Key Settings ====
* '''Filters:''' <code>field_as_parent_asset</code> is EMPTY (Ensures only Top Assets are listed).
* '''Gin Styling:''' Uses <code>button button--primary</code> classes to match the Gin Admin Theme accent colors.
* '''Field Order:''' The <code>field_as_has_children</code> field must be positioned '''above''' the Custom Text field and set to "Exclude from display."

=== Maintenance ===
* '''Adding Children:''' The button appears automatically the moment the first child is saved.
* '''Existing Data:''' To "wake up" a button for a Top Asset that already has children, simply Edit and Save one of its child records.

=== Hierarchy Integrity Rule ===
To enforce the "Single Level" hierarchy design:
* '''Logic:''' The <code>field_as_parent_asset</code> field is hidden from the Edit form if <code>field_as_has_children</code> is TRUE.
* '''Result:''' Prevents a Parent from being assigned a Parent (Nested recursion).
* '''Exception:''' Top Assets without children can still be edited to assign a parent, allowing for data entry error correction.

== Heritage Project: Asset Hierarchy System ==

=== Overview ===
This system manages a single-level recursive asset hierarchy. It uses a custom boolean field to drive the User Interface (showing buttons) and data integrity (locking the hierarchy).

=== Data Structure ===
* '''Entity Types:''' Supports standard <code>node</code> and custom <code>asset</code> entities.
* '''Field: Parent Asset''' (<code>field_as_parent_asset</code>): An Entity Reference field on child assets pointing to their Top Asset.
* '''Field: Has Children''' (<code>field_as_has_children</code>): A boolean field on Top Assets used as a flag for hierarchy state.

=== Implementation Logic (heritage_tweaks.module) ===

The module automates the hierarchy through two main PHP hooks.

==== 1. Hierarchy Automation (The Switch) ====
The <code>heritage_tweaks_entity_presave()</code> function acts as a "detector" during the save process.
* '''Trigger:''' When any asset is saved.
* '''Action:''' If <code>field_as_parent_asset</code> is not empty, the code identifies the parent entity.
* '''Result:''' It programmatically sets the parent's <code>field_as_has_children</code> to '''1 (TRUE)'''.
* '''Outcome:''' This "wakes up" the children button in the main list view automatically.

==== 2. Hierarchy Protection (The Safety Rail) ====
The <code>heritage_tweaks_form_alter()</code> function protects data integrity during editing.
* '''Trigger:''' When an existing asset is opened in the Edit form.
* '''Logic:''' It checks the <code>field_as_has_children</code> value.
* '''Constraint:''' If the value is '''1''', the <code>field_as_parent_asset</code> field is hidden (<code>#access = FALSE</code>).
* '''Outcome:''' This prevents a Parent from being assigned to another Parent, strictly enforcing the '''single-level design rule'''.

=== Views Configuration ===
The "Children" button is rendered via a '''Global: Custom Text''' field using Twig logic:
<syntaxhighlight lang="twig">
{% if field_as_has_children %}
<a href="/admin/asset-chain/{{ nid }}" class="button button--primary">Children</a>
{% endif %}
</syntaxhighlight>

=== User Experience (UX) Guidelines ===
* '''Single-Tab Navigation:''' The "Children" button opens in the current tab (no <code>_blank</code> target).
* '''Gin Styling:''' Primary actions (Forward) use <code>button--primary</code>. Secondary actions (Back) use <code>button--secondary</code>.
* '''Error Correction:''' Top Assets without children can still be edited to assign a parent if they were created as "Top" by mistake.

=== Maintenance & Troubleshooting ===
* '''Syncing Existing Data:''' To update assets created before this module, simply Edit and Save one child record for each Top Asset.
* '''Cache:''' After any module code changes, perform a <code>drush cr</code> to refresh the hook registry.

ICT:Asset-Chain Children Button logic (with boolean field)

2026-03-30T16:39:23Z

Mngr:

ICT:Asset-Chain Children Button logic (with boolean field)

2026-03-30T16:26:23Z

Mngr: Created page with "== Asset Hierarchy: "Children" Button Logic == === Overview === This implementation displays a clickable button in the Top Assets table only when an asset has at least one child. It avoids complex and performance-heavy Views relationships by using a data-driven boolean flag. === Data Model === * '''Entity Type:''' Asset (or Node) * '''Parent Field:''' <code>field_as_parent_asset</code> (Entity Reference pointing to the parent). * '''Indicator Field:''' <code>field_as_h..."

ICT:D Asset-Chain header arrangement with top asset

2026-03-29T22:20:37Z

Mngr:

== Drupal 11: Displaying Parent Asset Metadata in a Recursive View Header ==

This guide explains how to display fields (Thumbnail, Caption) from a parent "Digital Asset" entity in the header of a View that lists its children. This uses the "View Area" method to maintain a single View configuration.

=== Step 1: Create the "Header" Block Display ===
Instead of a new View, we add a specialized display to the existing one to keep the project organized.

# Open your '''AssetChain''' View.
# Click the '''+ Add''' button and select '''Block'''.
# '''Crucial:''' Change the "Display name" (found under Display Settings) to "Parent Header Block".
# In the center column, look for the dropdown that says "All displays" and change it to '''This block (override)'''.
# '''Fields:'''
#* Add your Thumbnail field.
#* Add your Asset Caption field.
# '''Pager:''' Set to "Display a specified number of items" and set the value to '''1'''.
# '''Contextual Filter:'''
#* Add '''Content: ID''' (This targets the parent asset directly).
#* Set "When the filter value is NOT available" to '''Hide view'''.
# Save the View.

=== Step 2: Format the Header Layout ===
To make the thumbnail and caption sit side-by-side without a table, use a Custom Text field.

# In the '''Parent Header Block''' display, add a '''Global: Custom text''' field.
# Move it to the bottom of the field list.
# Mark the original Thumbnail and Caption fields as '''Exclude from display'''.
# In the "Custom text" box, use the following HTML (Verify tokens in the "Replacement Patterns" list):

<pre>
<div class="parent-summary" style="display: flex; gap: 20px; align-items: flex-start; margin-bottom: 20px; border: 1px solid #ccc; padding: 15px;">
<div class="header-image">
{{ field_media_thumbnail }}
</div>
<div class="header-text">
<h3 style="margin-top: 0;">Parent Asset Information</h3>
<p>{{ field_asset_caption }}</p>
</div>
</div>
</pre>

=== Step 3: Embed the Block in the Main View Header ===
This step connects the "Parent Header" to your "Children Table."

# Switch back to your '''Main View''' (the display that shows the table of children).
# In the '''Header''' section, click '''Add'''.
# Search for and select '''Global: View area'''.
# Configure the View Area as follows:
#* '''View to insert:''' Select "AssetChain".
#* '''Display to insert:''' Select "Parent Header Block".
#* '''Inherit contextual filters:''' Check this box. (This passes the ID from the URL to the header).
# Click '''Apply''' and '''Save''' the View.

=== ICT Support Notes ===
* '''Recursive Logic:''' The header fetches the entity based on the current URL ID, while the table fetches children based on the reference field filter.
* '''Theming:''' If inline styles are forbidden by site policy, move the CSS from the {{code|<pre>}} block to the site's global stylesheet.

ICT:D Asset-Chain header arrangement with top asset

2026-03-29T22:16:31Z

Mngr: Created page with "== Drupal 11: Displaying Parent Asset Metadata in a Recursive View Header == This guide explains how to display fields (Thumbnail, Caption) from a parent "Digital Asset" entity in the header of a View that lists its children. === Prerequisites === '''Content Type:''' Digital Asset (containing fields: {{code|field_media_thumbnail}}, {{code|field_asset_caption}}). '''Entity Reference:''' A field (e.g., {{code|field_parent_asset}}) linking children to parents. '''Main View:..."

== Drupal 11: Displaying Parent Asset Metadata in a Recursive View Header ==
This guide explains how to display fields (Thumbnail, Caption) from a parent "Digital Asset" entity
in the header of a View that lists its children.
=== Prerequisites ===
'''Content Type:''' Digital Asset (containing fields: {{code|field_media_thumbnail}}, {{code|field_asset_caption}}).
'''Entity Reference:''' A field (e.g., {{code|field_parent_asset}}) linking children to parents.
'''Main View:''' An existing View (e.g., ''AssetChain'') showing child assets in a table.
=== Step 1: Create the "Header" Block Display ===
Instead of a new View, we add a specialized display to the existing one.
Open your '''AssetChain''' View.
Click '''+ Add''' and select '''Block'''.
'''Crucial:''' Change the "Display name" to "Parent Header Block".
In the center column, look for the dropdown that says "All displays" and change it to '''This block (override)'''.
'''Fields:'''
#* Add {{code|field_media_thumbnail}}.
#* Add {{code|field_asset_caption}}.
#* Remove any fields you don't want in the header (like the table columns).
'''Pager:''' Set to "Display a specified number of items" and set value to '''1'''.
'''Contextual Filter:'''
#* Add {{code|ID}} (from the Content category).
#* Set "When the filter value is NOT available" to '''Hide view'''.
Save the View.
=== Step 2: Format the Header Layout (Optional but Recommended) ===
To make the thumbnail and caption sit side-by-side:
In the '''Parent Header Block''' display, add a '''Global: Custom text''' field.
Move it to the bottom of the field list.
Mark the original Thumbnail and Caption fields as '''Exclude from display'''.
In the "Custom text" box, use the following HTML (adjust tokens based on "Replacement Patterns"):

{{ field_media_thumbnail }}

Parent Asset
{{ field_asset_caption }}

=== Step 3: Embed the Block in the Main View Header ===
Switch back to your '''Main View''' (the Page or Block that shows the table).
In the '''Header''' section, click '''Add'''.
Search for and select '''Global: View area'''.
Configure the View Area:
#* '''View to insert:''' Select "AssetChain".
#* '''Display to insert:''' Select "Parent Header Block".
#* '''Inherit contextual filters:''' [[File:Checked_checkbox.png]] '''CHECK THIS BOX'''. (This passes the Parent ID from the URL to the header).
Click '''Apply''' and '''Save''' the View.
=== Troubleshooting ===
'''Empty Header:''' If the header doesn't appear, check that the "Inherit contextual filters" box is checked in the View Area settings.
'''Wrong Asset:''' Ensure the Contextual Filter in the "Parent Header Block" is targeting the '''ID''' of the asset, not the reference field.

ICT:D Linking Assets to Person

2026-03-27T19:29:31Z

Mngr:

= Drupal: Linking Assets to Persons (MM Relationship Without Custom Code) =

== Purpose ==
This page documents the step‑by‑step implementation of a **many‑to‑many–style
relationship between Person and Asset entities** in Drupal 11.x.

The objective is to allow editors to:
* link existing Assets to a Person,
* manage these links in a table‑based UI,
* search and select Assets via a modal browser,
* avoid custom modules and custom database tables.

This solution uses **standard Drupal mechanisms** and is upgrade‑safe.

---

== Design Principles ==
* Prefer configuration over code
* Avoid custom schema and join tables
* Use Drupal’s entity reference system
* Use contrib modules for UX, not data modeling
* Ensure maintainability and handover safety

---

== Conceptual Model ==

{| class="wikitable"
! Entity !! Role
|-
| Person || Main entity (e.g. historical person)
|-
| Asset || Reusable referenced entity (documents, images, objects, etc.)
|}

Relationship:
* One Person → many Assets
* One Asset → many Persons (implicit)

Drupal handles this naturally via **entity references**.

---

== Required Modules ==
Ensure the following modules are enabled:

* Core:
** Field
** Views
* Contrib:
** Inline Entity Form (IEF)
** Entity Browser

No custom module is required.

---

== Step 1: Create the Entity Reference Field ==

On the **Person** entity:

1. Go to:
<pre>
Structure → Content types → Person → Manage fields
</pre>

2. Add a new field:
* Field type: '''Entity reference'''
* Label: <code>Assets</code>
* Machine name: <code>field_assets</code>

3. Reference settings:
* Target type: <code>Asset</code>
* Allowed bundles: select relevant Asset bundles
* Cardinality: '''Unlimited'''

Save the field.

---

== Step 2: Configure the Form Widget (Critical Step) ==

1. Go to:
<pre>
Manage form display
</pre>

2. For <code>field_assets</code>, select widget:
* '''Inline Entity Form – Complex'''

3. Open the widget settings (gear icon):

* ✅ Allow users to add existing entities
* ❌ Allow users to add new entities
* Entity Browser: select the Asset browser (configured in Step 3)

4. Save the form display.

'''Important:'''
Do NOT select “Entity Browser” as the field widget itself.
That widget does not provide a table‑based UI.

---

== Step 3: Create the Entity Browser for Assets ==

1. Go to:
<pre>
Configuration → Content authoring → Entity Browser
</pre>

2. Create a new browser:
* Name: <code>asset_browser</code>
* Display: Modal
* Selection mode: Multi‑select

3. Add a widget:
* Widget type: View

4. Create or select a View:
* Base table: Asset
* Display type: Entity Browser
* Pagination: 10–25 items per page
* Exposed filters:
- Title
- Type / taxonomy (as needed)
* Fields:
- Thumbnail (image style)
- Title
- Optional metadata

5. Save the Entity Browser.

---

== Step 4: Resulting Editor UX ==

On the Person edit form:

* Assets are displayed in a table
* Editors can:
- Add existing Assets
- Remove Assets
- Reorder Assets
* Clicking “Add existing Asset” opens a modal browser
* Assets are searched and selected visually

This provides a historian‑friendly workflow.

---

== Step 4a: Table Representation on the Person Edit Form ==

The table‑based representation of linked Assets on the Person edit form
is provided automatically by the **Inline Entity Form – Complex** widget.

This step documents how the table is configured and what editors see.

---

=== How the Table Is Generated ===
When the field <code>field_assets</code> is configured with:

* Widget: '''Inline Entity Form – Complex'''
* Cardinality: Unlimited

Drupal renders the referenced Assets as a **tabular list** instead of
individual widgets.

No custom Views, no custom code, and no join tables are involved.

---

=== Default Table Columns ===
Out of the box, the table typically contains:

{| class="wikitable"
! Column !! Purpose
|-
| Label / Title || Identifies the linked Asset
|-
| Type / Bundle || Shows the Asset type (if applicable)
|-
| Operations || Remove / Edit actions
|-
| Weight || Drag‑and‑drop ordering
|}

The exact columns depend on:
* Asset entity type
* Enabled fields
* Display settings

---

=== Editor Capabilities ===
Editors can:

* ✅ Add existing Assets (via Entity Browser)
* ✅ Remove Assets from the Person
* ✅ Reorder Assets using drag‑and‑drop
* ✅ See all linked Assets at once

This makes the relationship **explicit and transparent**, which is
important for historical research workflows.

---

=== Why This Table Matters ===
Compared to alternative approaches:

{| class="wikitable"
! Approach !! Result
|-
| Autocomplete reference || Poor overview
|-
| Pills / tags || No metadata, no ordering
|-
| Custom join table || High complexity
|-
| '''IEF table''' || ✅ Clear, structured, maintainable
|}

The IEF table offers the best balance between:
* usability
* transparency
* maintainability
* upgrade safety

---

=== Configuration Notes ===
* No additional configuration is required beyond selecting
'''Inline Entity Form – Complex'''.
* The table appears automatically on the Person edit form.
* Display styling is handled by the admin theme (Gin).

---

=== Extensibility ===
Later enhancements (optional):

* Add thumbnail columns
* Show additional Asset metadata
* Adjust column order or visibility

These enhancements can be achieved without changing the data model.

== Step 5: UX Cleanup – Hide the Misleading “Add node” Button ==

Inline Entity Form displays an intermediate chooser containing an
“Add node” button, which is misleading when creation is disabled.

This is hidden via Gin admin CSS.

=== CSS Location ===
<pre>
sites/default/files/gin-custom.css
</pre>

=== CSS Rule ===
<syntaxhighlight lang="css">
/* Hide misleading "Add node" button in Inline Entity Form chooser */
input.ief-entity-submit[data-drupal-selector*="ief-reference-save"][value="Add node"] {
display: none !important;
}
</syntaxhighlight>

This solution:
* requires no JavaScript
* survives AJAX rendering
* is upgrade‑safe
* does not depend on dialog wrappers

---

== Why No Join Table Was Used ==
An experimental approach using a “real” join table was evaluated and rejected because:

* it required a custom module
* it required schema lifecycle management
* UI construction required many hooks
* upgrades would require maintenance work

Drupal’s entity reference system already models the relationship correctly.

---

== Performance Notes ==
* 1000+ Assets are handled without issue
* Only referenced Assets are rendered on the Person form
* Entity Browser uses pagination and indexed Views
* Thumbnails should always use image styles

---

== Summary ==
This implementation achieves:

* ✅ Many‑to‑many relationship semantics
* ✅ Clean table‑based UI
* ✅ Visual asset selection
* ✅ No custom code
* ✅ No custom schema
* ✅ Upgrade‑safe architecture

This is the recommended approach for modern Drupal (11.x).

---

== Reusability and Generalization of the Asset Linking Pattern ==

=== Purpose of This Section ===
The procedure described above is **not limited to Person → Asset**.
It defines a **reusable architectural pattern** for linking Assets to
any other entity type in Drupal.

This pattern enables true many‑to‑many semantics without custom code.

---

=== Core Idea ===
The solution separates concerns:

{| class="wikitable"
! Concern !! Mechanism
|-
| Relationship modeling || Entity reference field
|-
| Selection UX || Entity Browser
|-
| Management UX || Inline Entity Form (Complex)
|-
| Data storage || Drupal core entity system
|}

Because of this separation, the same components can be reused.

---

=== Reusing the Entity Browser ===
The **Asset Entity Browser**:

* is generic
* operates on the Asset entity type
* does not depend on Person

Therefore, it can be reused **as‑is** for other entities.

Examples:
* Object → Asset
* Event → Asset
* Place → Asset
* Organisation → Asset

No changes to the browser are required.

---

=== Reusing the Pattern for Other Entities ===

To link Assets to another entity (e.g. Object):

1. Add an **Entity reference** field on the target entity:
* Target type: Asset
* Cardinality: Unlimited

2. Configure the form widget:
* Widget: '''Inline Entity Form – Complex'''
* Allow existing entities: ✅
* Allow new entities: ❌
* Entity Browser: reuse the existing Asset browser

3. Save the form display.

The result is identical:
* table‑based Asset management
* modal Asset selection
* no custom schema
* no custom code

---

=== Resulting Many‑to‑Many Relationship ===
When applied consistently:

* One Asset can be linked to many Persons
* One Asset can be linked to many Objects
* One Person can link many Assets
* One Object can link many Assets

Drupal handles this naturally via entity references.

No explicit join table is required.

---

=== Why This Works in Drupal ===
Drupal entities are first‑class, reusable objects.
Entity references already implement relational semantics.

By reusing:
* the same Asset entity
* the same Entity Browser
* the same IEF table UI

the system behaves like a relational many‑to‑many model,
while remaining configuration‑driven and upgrade‑safe.

---

=== Architectural Benefit ===
This approach:

* ✅ avoids schema duplication
* ✅ avoids custom join tables
* ✅ avoids module proliferation
* ✅ enforces UX consistency
* ✅ scales across entity types
* ✅ simplifies maintenance and handover

This is the recommended approach for modern Drupal (11.x).

---

=== Key Takeaway ===
Once the Asset linking pattern is implemented once,
it becomes a **reusable building block**.

New relationships are created by configuration,
not by programming.
``

== Key Lesson ==
If a solution requires:
* custom join tables
* extensive hook usage
* complex UI overrides

…it is often a sign that Drupal already offers a better abstraction.

ICT:D Linking Assets to Person

2026-03-27T19:22:33Z

Mngr: Created page with "= Drupal: Linking Assets to Persons (MM Relationship Without Custom Code) = == Purpose == This page documents the step‑by‑step implementation of a **many‑to‑many–style relationship between Person and Asset entities** in Drupal 11.x. The objective is to allow editors to: * link existing Assets to a Person, * manage these links in a table‑based UI, * search and select Assets via a modal browser, * avoid custom modules and custom database tables. This solutio..."

ICT:D Cleaning up Unused Custom Modules (Composer - Drush)

2026-03-27T17:45:43Z

Mngr: Created page with "= Drupal: Cleaning Up Unused Custom Modules (Composer + Drush) = == Purpose == This page documents the **correct and safe procedure** for removing unused or experimental **custom Drupal modules**, including: * database cleanup * configuration cleanup * file system cleanup The procedure avoids common pitfalls and is suitable for long‑lived Drupal installations that must remain upgrade‑safe. --- == Important Principles == Drupal deliberately separates: {| class="..."

= Drupal: Cleaning Up Unused Custom Modules (Composer + Drush) =

== Purpose ==
This page documents the **correct and safe procedure** for removing
unused or experimental **custom Drupal modules**, including:

* database cleanup
* configuration cleanup
* file system cleanup

The procedure avoids common pitfalls and is suitable for long‑lived
Drupal installations that must remain upgrade‑safe.

---

== Important Principles ==
Drupal deliberately separates:

{| class="wikitable"
! Aspect !! Managed by
|-
| Module enable/disable || Drupal
|-
| Configuration & schema cleanup || Module uninstall logic
|-
| Module files on disk || You / Composer
|}

'''Drupal never deletes module files automatically.'''
This is a security and deployment design choice.

---

== Never Do This ==
* ❌ Do NOT delete module files before uninstalling
* ❌ Do NOT drop tables while the module is still enabled
* ❌ Do NOT rely on Drupal to clean up experimental schema automatically

Doing so may leave broken configuration or database artifacts.

---

== Correct Cleanup Procedure ==

=== Step 1: Verify the Module Is No Longer Used ===
Before removal, ensure:
* no content depends on the module
* no fields, entities, or views reference it
* no other module lists it as a dependency

---

=== Step 2: Uninstall the Module (Mandatory) ===

Uninstalling runs:
* <code>hook_uninstall()</code>
* configuration cleanup
* entity cleanup (if implemented correctly)

==== Using Drush (recommended) ====
<pre>
drush pmu my_custom_module
</pre>

==== Using the Admin UI ====
* Go to <code>Extend → Uninstall</code>
* Select the module
* Confirm uninstall

'''Note:'''
Disabling a module is NOT sufficient.
You must uninstall it.

---

=== Step 3: Remove the Module Files ===

Drupal will NOT remove files from disk.

==== Custom module (manual) ====
<pre>
rm -rf modules/custom/my_custom_module
</pre>

==== Contrib module (Composer-managed) ====
<pre>
composer remove drupal/my_module
</pre>

This removes:
* the module directory
* composer.json / composer.lock references

---

=== Step 4: Clear Caches ===
After file removal:

<pre>
drush cr
</pre>

This ensures Drupal no longer tries to discover the module.

---

== Database Cleanup (If Needed) ==

=== Custom Tables ===
Drupal does NOT drop custom tables automatically unless explicitly coded.

If the module created a “real” join table or custom schema:

<pre>
DROP TABLE my_custom_join_table;
</pre>

Only do this:
* after uninstalling the module
* when you are certain the table is unused

This is normal for experimental schema.

---

=== How to Check for Leftovers ===
Search the database for the module name:

<pre>
grep my_custom_module database_dump.sql
</pre>

Or inspect:
* <code>config</code>
* <code>key_value</code>
* <code>cache_*</code> tables (usually cleared by cache rebuild)

---

== Common Error Scenario ==
If files are deleted before uninstalling:

* Drupal reports:
“The following module is missing from the file system…”
* Uninstall hooks never ran
* Manual DB cleanup is required

This is why uninstall must always come first.

---

== Why Drupal Works This Way ==
Drupal avoids automatic file deletion because:

* web servers should not delete their own code
* production file systems are often read‑only
* deployments are controlled externally
* safety is preferred over convenience

This design supports secure, professional deployments.

---

== Architectural Lesson ==
Custom modules:
* create lifecycle responsibility
* require manual cleanup
* increase long‑term maintenance cost

Configuration‑driven solutions:
* leave no schema debris
* uninstall cleanly
* survive core upgrades

This cleanup step is not housekeeping — it is architectural alignment.

---

== Summary Checklist ==

{| class="wikitable"
! Step !! Required
|-
| Uninstall module (pmu) || ✅ Yes
|-
| Remove module files || ✅ Yes
|-
| Clear caches || ✅ Yes
|-
| Drop custom tables (if any) || ✅ Manual
|-
| Verify no leftovers || ✅ Recommended
|}

---

== Final Note ==
Experimental work is valuable.

Cleaning it up properly:
* preserves system integrity
* simplifies upgrades
* helps your successor
* reflects professional discipline

ICT:D Media-Library uploading one file in an Asset

2026-03-27T16:33:49Z

Mngr:

= Media Library use in Asset for uploading ONE single media file =

== Media field edit in Asset ==
* is an Entity Reference to Media with types: Audio, Document, Image and Video
* Required field
* Referencemethod to default
* Limited to 1 (very important - one asset one file)

== Media in Manage form display ==
* Widget = Media Library
* Tab order: Image, Document, Video, Audio

== Media in Manage display ==
* View mode = Media Library

After this configurtion there is an important GUI finetuning needed to simplify the interface and mask unneeded filters and buttons.
Therefor the next chapter is very important.

= Media Library Widget UI Simplification (CSS Overrides) =

== Purpose ==
This document records the CSS overrides applied to the **Drupal Media Library widget**
to simplify the user interface for editors.

The goal is to:
* reduce cognitive load
* hide internal mechanics (filters, buttons)
* provide a clean, focused media selection experience
* preserve full Media Library functionality

These overrides are **intentional**, **documented**, and **part of the UI contract**.

---

== Context ==
The Media Library widget is powered by:
* a Drupal View (for listing media)
* exposed filters (search, filtering)
* a jQuery UI modal dialog

By default, the UI exposes:
* filter forms
* layout switches
* confirmation button bars

For this project, these elements are **not required** and confuse users.

---

== Design Principle ==
Editors should:
* focus on selecting or replacing a single media item
* not be exposed to filtering mechanics
* not be presented with redundant confirmation actions

Filtering and constraints are applied **silently** via Views configuration.

---

== Applied CSS Overrides ==

The following CSS rules are applied to the admin theme (e.g. gin-custom.css).

=== 1. Hide the exposed filter form ===

<syntaxhighlight lang="css">
/* Hide the Views exposed filter form inside Media Library */
.media-library-view .views-exposed-form {
display: none !important;
}
</syntaxhighlight>

Effect:
* Removes the visible filter form from the Media Library modal
* Filters continue to work internally
* Prevents users from interacting with unintended controls

---

=== 2. Hide the dialog button bar (Select / Cancel) ===

<syntaxhighlight lang="css">
/* Hide the bottom button bar in the Media Library modal */
.ui-dialog--media-library .ui-dialog-buttonpane {
display: none !important;
}
</syntaxhighlight>

Effect:
* Removes the redundant “Select / Cancel” button pane
* Selection happens directly via clicking media items
* Avoids duplicate confirmation paths

Note:
* Media Library uses jQuery UI dialogs
* Hiding the button pane via CSS is a supported and safe approach

---

=== 3. Hide the Grid / Table display switch ===

<syntaxhighlight lang="css">
/* Hide the Grid / Table view switch */
.media-library-view--display-switch {
display: none !important;
}
</syntaxhighlight>

Effect:
* Enforces a single, consistent layout
* Removes unnecessary UI choices
* Simplifies training and usage

---

== What These Overrides Do NOT Do ==

These CSS rules:
* do NOT affect data
* do NOT alter Media entities
* do NOT disable Media Library functionality
* do NOT change Views filtering logic
* do NOT interfere with file replacement

They are **presentation‑only**.

---

== Operational Notes ==

* These CSS rules are required for correct UI behavior
* Removing them may:
* reintroduce clutter
* confuse editors
* appear to “break” Media Library UX
* They must be restored after experiments or refactoring

---

== Maintenance Recommendation ==
Maintain a dedicated section in documentation for:
* UI‑level CSS overrides
* why they exist
* where they are applied

This prevents accidental removal during future development.

---

== Summary ==
{| class="wikitable"
! Area !! Decision
|-
| Media selection UI || Simplified via CSS
|-
| Filters || Hidden visually, active internally
|-
| Confirmation buttons || Removed to avoid redundancy
|-
| Layout switching || Disabled for consistency
|-
| Impact || UI only, no data or logic changes
|}

---

== Appendix: Why CSS UI Simplification Is Required for Media Library Upload/Replace ==

=== Observation ===
During testing, it was observed that when the Media Library modal UI elements
(exposed filters, dialog buttons, layout switches) were visible:

* selecting an existing media item
* and attempting to upload or replace the file

did NOT trigger the expected switch to the upload/replace interface.

After restoring the CSS rules that hide these elements, the upload and replacement
behavior started working again immediately.

At first sight this appears surprising, because CSS is normally considered
“presentation only”.

---

=== Explanation (Important) ===

The Media Library widget is NOT a single, isolated component.
It is a composite UI made of:

* a Views-powered listing (grid/table)
* exposed filter forms
* a selection state manager
* jQuery UI dialog controls
* AJAX-driven JavaScript behaviors

All of these parts communicate via DOM presence, focus events, and click handlers.

In particular:

* the Media Library JavaScript uses **visible UI elements** to determine
the current interaction state:
* browsing
* selecting
* uploading
* replacing
* when multiple interaction paths are visible at the same time
(filters, dialog buttons, layout switches),
the internal state machine can no longer reliably determine
which action the user intends

As a result:
* the transition to the upload/replace state is not triggered
* the upload box never appears
* replacement of the currently selected file fails silently

This effect is **amplified inside modal dialogs**, where focus handling
and AJAX re-rendering are especially fragile.

---

=== Why Hiding UI Elements Fixes the Problem ===

The applied CSS rules intentionally remove UI elements that are not needed
for the single-file Media Library workflow.

By doing so, they:

* eliminate competing interaction paths
* remove focus and submit-event conflicts
* prevent redundant confirmation logic
* reduce layout re-rendering during selection

This forces the Media Library widget into a **deterministic interaction model**
that matches its expectations for:

* cardinality = 1
* direct selection
* upload or replace of a single file

Once the UI state becomes unambiguous, the JavaScript correctly switches
into upload/replace mode.

---

=== Important Conclusion ===

These CSS overrides are **not cosmetic tweaks**.

They are an **integral part of the Media Library configuration** for this project.

Removing them may:
* reintroduce UI ambiguity
* break upload or replacement behavior
* make Media Library appear “corrupt” or inconsistent

Therefore:
* the CSS must be preserved
* the CSS must be documented
* the CSS must be restored after experiments

---

=== Design Principle (Summary) ===

In the Media Library modal:

''Hiding unused UI elements is required to stabilize widget behavior,
not just to simplify appearance.''

---

== End of Appendix ==

== End of document ==

ICT:D Media-Library uploading one file in an Asset

2026-03-27T16:25:03Z

Mngr: Created page with "= Media Library use in Asset for uploading ONE single media file = == Media field edit in Asset == * is an Entity Reference to Media with types: Audio, Document, Image and Video * Required field * Referencemethod to default * Limited to 1 (very important - one asset one file) == Media in Manage form display == * Widget = Media Library * Tab order: Image, Document, Video, Audio == Media in Manage display == * View mode = Media Library After this configurtion there is..."

ICT:Asset Chain Model - definition and application

2026-03-27T14:45:33Z

Mngr: Created page with "= Asset Chain Model and Selection Strategy = == Purpose == This document defines the **Asset Chain model** used in this system and explains: * how Assets are versioned * how “top assets” are defined * how Assets are selected easily by users * how the full Asset chain can be displayed consistently The model is designed to: * remain simple for historian users * avoid complex custom code * scale to large collections (1000+ Assets) * keep editorial intent explicit and..."

= Asset Chain Model and Selection Strategy =

== Purpose ==
This document defines the **Asset Chain model** used in this system and explains:
* how Assets are versioned
* how “top assets” are defined
* how Assets are selected easily by users
* how the full Asset chain can be displayed consistently

The model is designed to:
* remain simple for historian users
* avoid complex custom code
* scale to large collections (1000+ Assets)
* keep editorial intent explicit and stable over time

---

== Core Principles ==

* One Asset represents **one file**
* Assets may have multiple **versions**
* Versions are grouped into **Asset chains**
* Other entities (Object, Person, Place, etc.) link to **one Asset only**
* That Asset acts as the **entry point to the full chain**

---

== Asset Chain Definition ==

=== Top Asset (Chain Root) ===
* The **first Asset created** for a subject
* Has **no parent Asset**
* Is the **top asset permanently**
* Represents:
* recognition thumbnail
* subject identification
* entry point for the chain

The definition of “top asset” is **structural**, not qualitative:
* it is NOT “best quality”
* it is NOT “highest resolution”
* it does NOT change later

---

=== Child Assets (Versions) ===
* Represent alternative versions of the same Asset
(e.g. better scan, restoration, derivative)
* Always have a **parent Asset**
* The parent **must be the top asset**
* Children of children are **not allowed**

This creates a constrained structure:

<pre>
Top asset (no parent)
├── Version A
├── Version B
├── Version C
</pre>

No deep or random trees are permitted for Assets.

---

== Editorial Workflow ==

=== Creating an Asset Chain ===
1. User creates the first Asset
* Parent field left empty
* Asset becomes the **top asset**
2. User creates a new version
* Parent selected = top asset
3. Repeat for additional versions

At no point does the user need to redefine or move the top asset.

---

=== Linking Assets to Other Entities ===
* Object / Person / Place entities link to:
* **exactly one Asset**
* always a **top asset**
* This link never changes when new versions are added

Benefits:
* stable references
* no cascading updates
* no hidden automation

---

== Asset Selection (Entity Browser) ==

=== User Interface Principle ===
Users should:
* see **only top assets**
* search using **one simple search box**
* never need to understand Asset chains

---

=== Entity Browser View Rules ===

The Asset selection View applies:

1. **One exposed filter (visible)**
* Combined fields filter
* Searches across:
* title
* identifiers
* keywords
* other metadata fields

2. **Additional filters (not visible)**
* Asset has no parent (top assets only)
* Content type = Asset

Important:
* Only the first exposed filter is shown in the modal
* All other filters are still applied silently

Result:
* clean UI
* strong constraints
* no risk of selecting a child asset

---

== Presenting the Asset Chain ==

=== Asset Chain View ===
A dedicated View is used to show the full chain.

Definition:
* Contextual argument = top asset ID
* Filters:
* Asset ID = argument
* OR parent Asset = argument
* Sorting:
* creation date
* version label
* or other editorial order

Result:
* shows the top asset and all its versions together

---

=== Usage ===
The Asset chain View can be:
* linked from Object / Person / Place
* linked from the Asset itself
* used to choose the appropriate version for publication

This keeps:
* selection simple
* presentation rich
* version choice contextual

---

== Why This Model Was Chosen ==

* Avoids redefining “top asset” over time
* Avoids automatic propagation or inference
* Avoids recursive Views logic
* Keeps historian workflow simple
* Makes system behavior predictable
* Allows future extensions if needed

---

== Summary ==

{| class="wikitable"
! Aspect !! Decision
|-
| Asset versioning || Flat chain under permanent top asset
|-
| Top asset || First created, no parent, never changes
|-
| Selection UI || Only top assets visible
|-
| Filtering || One combined search + silent constraints
|-
| Linking from other entities || Always to top asset
|-
| Chain presentation || Dedicated Asset chain View
|-
| Custom code || Minimal, UI-level only
|}

---

== End ==

ICT:D Taxonomy - Vocabulary - Terms use

2026-03-27T13:39:06Z

Mngr: Created page with "= Using Taxonomy for Keywords and Search in Drupal (Assets, Views, Entity Browser) = == Purpose == This document describes how to use **taxonomy (vocabularies and terms)** in Drupal to: * assign multiple keywords to entities (Assets, Persons, Objects, etc.) * reuse keywords consistently * enable effective searching via **Combined fields filters** in Views and Entity Browser modals * scale to large datasets (1000+ entities) No custom code is required. --- == Concepts..."

= Using Taxonomy for Keywords and Search in Drupal (Assets, Views, Entity Browser) =

== Purpose ==
This document describes how to use **taxonomy (vocabularies and terms)** in Drupal to:
* assign multiple keywords to entities (Assets, Persons, Objects, etc.)
* reuse keywords consistently
* enable effective searching via **Combined fields filters** in Views and Entity Browser modals
* scale to large datasets (1000+ entities)

No custom code is required.

---

== Concepts (short definitions) ==

{| class="wikitable"
! Term !! Meaning in Drupal
|-
| Taxonomy || The classification system
|-
| Vocabulary || A named set of related terms (e.g. "Keywords")
|-
| Term || One keyword inside a vocabulary
|}

A **vocabulary is part of taxonomy**, not a separate concept.

---

== Creating a Keyword Vocabulary ==

1. Go to
'''Structure → Taxonomy → Add vocabulary'''
2. Example:
* Name: '''Keywords'''
* Description: Free or controlled keywords for Assets and related entities
3. Save

You may create **multiple vocabularies** if needed, e.g.:
* Subject keywords
* Object type
* Period
* Location
* Technique / Material

---

== Adding Keywords to an Entity Type ==

Repeat for each entity type that needs keywords (Asset, Person, Object, etc.).

1. Go to
'''Structure → Content types → Asset → Manage fields'''
2. Add a new field:
* Field type: '''Term reference'''
* Reference type: '''Taxonomy term'''
3. Field settings:
* Allowed vocabulary: '''Keywords'''
* Cardinality: '''Unlimited'''
4. Widget:
* '''Autocomplete (tags style)'''
5. Save

---

== Keyword Usage by Editors ==

With autocomplete (tags style):

* Editors can **select existing keywords**
* Editors can **create new keywords on the fly** by typing and pressing Enter
* New terms are automatically added to the vocabulary
* Existing entities can be edited later to add or remove keywords

(Requires permission: ''Create terms in Keywords vocabulary''.)

---

== Using Keywords in Views (Search) ==

=== Basic rule ===
The **Combined fields filter** can search:
* any field that is present in the View’s '''Fields''' list
* even if the field is '''excluded from display'''

---

== Configuring a View for Keyword Search ==

1. Edit the View (e.g. Entity Browser View)
2. Under '''Fields''':
* Add the keyword field (term reference)
* Enable '''Exclude from display'''
3. Repeat for any other searchable fields (title, identifier, description, etc.)

---

== Adding the Combined Fields Filter ==

1. Under '''Filter criteria → Add'''
2. Choose:
* '''Global: Combine fields filter'''
3. Expose the filter
4. In filter settings:
* Select all searchable fields (including hidden keyword fields)
5. Save

---

== How the Combined Fields Filter Works ==

* One search box
* OR logic across fields
* Example logic:
<pre>
Title OR Identifier OR Keywords OR Description
</pre>

There is:
* no AND syntax
* no multi-filter UI in Entity Browser modals
* only one exposed filter is shown

This is a known Entity Browser limitation.

---

== Scaling to Large Datasets ==

For large collections (1000+ Assets):

* Rich keyword metadata is essential
* Multiple vocabularies are recommended
* Combined search enables progressive narrowing:
<pre>
map 1850 Antwerp manuscript
</pre>

This approach:
* avoids scrolling
* avoids complex UI
* remains performant
* requires no custom module

---

== Recommended Pattern (Summary) ==

{| class="wikitable"
! Requirement !! Solution
|-
| Multiple keywords per entity || Term reference field (unlimited)
|-
| Reusable keywords || Taxonomy vocabulary
|-
| Free keyword creation || Autocomplete (tags)
|-
| Narrowing search || Combined fields filter
|-
| Entity Browser modal || Single exposed combined filter
|-
| No custom code || Configuration only
|}

---

== Notes for Maintainers ==

* Taxonomy vocabularies can be reused across entities
* Keyword structure can evolve over time
* Existing entities are not locked to initial keywords
* This setup intentionally avoids custom modules for maintainability

---

== End ==

ICT:m-m with IEF and Entity Browser - no custom module

2026-03-26T18:30:44Z

Mngr: Created page with "= Drupal: Asset selection with Inline Entity Form + Entity Browser (Gin, no custom module) = == Purpose == This page documents the final, working setup for selecting and managing Assets on entity edit forms (e.g. Person → Asset), using: * Inline Entity Form (IEF) – Complex (table display) * Entity Browser (modal picker with search and thumbnails) * Gin admin theme * No custom module * No JavaScript logic * Hardened for AlmaLinux / SELinux The goal was to provide a..."

= Drupal: Asset selection with Inline Entity Form + Entity Browser (Gin, no custom module) =

== Purpose ==
This page documents the final, working setup for selecting and managing Assets
on entity edit forms (e.g. Person → Asset), using:

* Inline Entity Form (IEF) – Complex (table display)
* Entity Browser (modal picker with search and thumbnails)
* Gin admin theme
* No custom module
* No JavaScript logic
* Hardened for AlmaLinux / SELinux

The goal was to provide a historian‑friendly UX while keeping the solution
maintainable and upgrade‑safe.

---

== Requirements ==
* Drupal 10/11
* Inline Entity Form (>= 3.x)
* Entity Browser (2.x)
* Gin admin theme
* Assets as a reusable entity (e.g. node or media)
* AlmaLinux with SELinux enforcing

---

== Functional Requirements ==
* Editors select existing Assets via a modal with search and thumbnails
* Selected Assets appear as a table on the edit form
* Editors can remove / reorder Assets
* Editors must NOT be confused by an "Add node" action
* No custom Drupal module may be introduced

---

== Architecture Overview ==

=== Why this architecture ===
Drupal provides two strong but complementary tools:

{| class="wikitable"
! Tool !! Role
|-
| Inline Entity Form (Complex) || Table display + edit/remove/reorder
|-
| Entity Browser || Modal selection UI using Views
|}

The key is:
* IEF controls '''how selected items are displayed'''
* Entity Browser controls '''how items are selected'''

They must be combined correctly.

---

== Correct Field Configuration ==

=== Entity reference field ===
On the parent entity (e.g. Person):

* Field type: Entity reference
* Target: Asset
* Cardinality: Unlimited

=== Form display ===
* Widget: '''Inline Entity Form – Complex'''
* Widget settings:
** ✅ Allow users to add existing entities
** ❌ Allow users to add new entities
** Entity Browser: select the Asset picker browser

'''Important:'''
Do NOT set the field widget itself to "Entity Browser".
That results in a pill/tabs UI instead of a table.

---

== Known UX Issue ==
When clicking '''Add existing Asset''', Inline Entity Form opens an intermediate
chooser dialog containing:

* Select entities
* Add node
* Cancel

Even when "Add new" is disabled in IEF settings, the '''Add node''' button
still appears. This is a known limitation of IEF.

For historians, this button is misleading and must be hidden.

---

== Final Solution: Hide the "Add node" Button (CSS only) ==

=== Why CSS ===
* No custom module
* No JS behaviors
* Upgrade‑safe
* Gin explicitly supports admin CSS overrides

=== Location ===
Create or edit:

<pre>
sites/default/files/gin-custom.css
</pre>

This file is automatically loaded by Gin for admin pages.

---

=== Working CSS (final) ===

<syntaxhighlight lang="css">
/* Hide misleading "Add node" button in Inline Entity Form chooser */
input.ief-entity-submit[data-drupal-selector*="ief-reference-save"][value="Add node"] {
display: none !important;
}
</syntaxhighlight>

=== Why this works ===
* Targets the exact submit button rendered by IEF
* Uses stable attributes:
** class: <code>ief-entity-submit</code>
** attribute: <code>data-drupal-selector</code>
* Does NOT depend on dialog wrappers (.ui-dialog, .gin-dialog)
* Survives AJAX re-rendering
* Gin does not override <code>display: none</code> on this element

---

== Security Considerations (AlmaLinux / SELinux) ==

Because <code>gin-custom.css</code> and optional <code>gin-custom.js</code>
live in <code>sites/default/files</code>, permissions and SELinux labels matter.

=== Correct permissions ===
<pre>
-rw-r--r-- root root gin-custom.css
</pre>

Apache must NOT have write access.

=== Correct SELinux label ===
<pre>
httpd_sys_content_t
</pre>

Verify with:
<pre>
ls -Z sites/default/files/gin-custom.css
</pre>

Apache write test (should fail):
<pre>
echo "test" | sudo -u apache tee -a sites/default/files/gin-custom.css
</pre>

Expected:
<pre>
Permission denied
</pre>

This ensures admin JS/CSS cannot be overwritten by the web server.

---

== Performance Notes ==

* 1000+ Assets is fine
* Entity Browser uses a View with pagination and filters
* Only referenced Assets are rendered in the IEF table
* Thumbnails should always use image styles
* This setup is comparable to Drupal Media Library performance

---

== Known Limits ==
* The intermediate IEF chooser dialog cannot be removed by configuration
* The "Add node" button cannot be removed server‑side without custom code
* CSS hiding is the cleanest possible solution under the constraints

---

== Future Improvements ==
* Add thumbnail column to IEF table
* Scope CSS to specific fields if desired
* Improve wording via UI translation if needed

---

== Summary ==
This solution achieves:

* ✅ Clean historian UX
* ✅ Table-based Asset management
* ✅ Modal picker with search
* ✅ No custom module
* ✅ Secure on SELinux
* ✅ Maintainable and upgrade-safe

The key lesson is:
'''Once the exact HTML is known, target the element directly.'''

ICT:Remove view link in messages - augmented version

2026-03-26T11:02:06Z

Mngr: Created page with "= Drupal 11 – Removing the “View” link from node save messages = == Context == In the Heritage Project (Drupal 11.3.x), historian users must **not** be redirected to or encouraged to view the node page after saving content. However, Drupal core automatically shows a status message such as: <pre> Article “My title” has been updated. View </pre> The “View” link is part of the default node save status message. A custom module (`heritage_tweaks`) modifies..."

= Drupal 11 – Removing the “View” link from node save messages =

== Context ==
In the Heritage Project (Drupal 11.3.x), historian users must **not** be redirected to or encouraged to view the node page after saving content.
However, Drupal core automatically shows a status message such as:

<pre>
Article “My title” has been updated. View
</pre>

The “View” link is part of the default node save status message.

A custom module (`heritage_tweaks`) modifies this behavior:
* The link is removed for non-administrators
* Administrators retain the default behavior
* Existing date validation logic is untouched

This page documents **why the initial implementation was unreliable** and **what exactly was changed** to make it work consistently in Drupal 11.

---

== Initial implementation (problematic) ==

The original code attached a custom submit handler like this:

<pre>
$form['actions']['submit']['#submit'][] = 'heritage_tweaks_clean_save_message';
</pre>

This assumes that:
* The node form always submits via <code>actions[submit]</code>
* The custom submit handler always runs after Drupal core adds its status message

These assumptions were **sometimes false** in Drupal 11.

---

== Why this failed intermittently ==

=== 1. Node forms can have multiple submit buttons ===
Even if the UI appears to show only one “Save” button, internally Drupal may expose:
* Multiple submit actions
* Workflow or moderation-related submit buttons
* Theme-generated submit wrappers

If the user clicks a submit button that is **not** <code>actions[submit]</code>, then:
* The custom handler is never executed
* The core “Saved … View” message remains unchanged

=== 2. Submit handlers are button-specific ===
In Drupal Form API:
* Submit handlers attached to one button are **not shared** with others
* Attaching to the wrong button means the code simply never runs

This is a common cause of “my submit handler works sometimes” bugs in Drupal.

---

== Final implementation (working) ==

The fix was to attach the cleanup handler to **all submit buttons**, not just one.

Simplified logic:

<pre>
foreach ($form['actions'] as $action) {
if ($action['#type'] === 'submit') {
$action['#submit'][] = 'heritage_tweaks_clean_save_message';
}
}
</pre>

This ensures:
* The handler always runs, regardless of which submit action is used
* The cleanup logic executes after core has added its status message

---

== What did NOT change ==

* The date validation logic (fields ending in <code>_day</code>)
* The placeholder logic (<code>dd/mm/yyyy</code>)
* The use of Drupal’s Messenger API
* The permission check for administrators

Only the **submit-handler attachment strategy** changed.

---

== How the message cleanup works ==

When the submit handler runs:

# If the user has the <code>administer nodes</code> permission, do nothing
# Otherwise:
## Remove all STATUS messages
## Add a new plain-text status message without links

Example replacement message:

<pre>
Article “My title” has been updated.
</pre>

Warnings and errors are preserved because only STATUS messages are removed.

---

== Why this is correct for Drupal 11 ==

Drupal 8.5+ introduced the Messenger service, and Drupal 11 relies fully on it for user messages.

Key points:
* Status messages are stored in a message queue
* Messages must be removed **after** they are added
* Entity hooks (e.g. <code>hook_node_update</code>) run too early
* Form submit handlers run at the correct time

Attaching to all submit buttons is the **recommended defensive pattern** for node forms in modern Drupal.

---

== Summary (one sentence) ==

The fix works because the cleanup logic is now attached to **every submit button**, guaranteeing that the “View” link is removed no matter how the node form is submitted.

---

== Maintenance note ==
If future changes introduce new submit actions (custom workflows, contributed modules, admin themes), this implementation will continue to work without modification.

ICT:Reverse-Proxy on AlmaLinux with nginx to apache backend

2026-03-25T18:00:41Z

Mngr:

= Reverse‑Proxy Architecture (nginx → Apache) =
This page documents the complete reverse‑proxy setup for the AlmaLinux frontend server.
It replaces the former IIS reverse‑proxy and Windows‑based certificate renewal system.
The configuration is now fully Linux‑native, stable, and successor‑friendly.

== Overview ==
* Frontend: AlmaLinux + nginx
* Backend: Apache (Drupal + MediaWiki)
* Certificates: Let’s Encrypt (certbot)
* Automatic renewal: systemd timer
* Windows/IIS: fully retired (no bindings, no renewals, no proxies)

The nginx server terminates HTTPS and forwards traffic to the internal Apache instance.

== Directory Layout ==
* '''/etc/nginx/nginx.conf''' – global nginx configuration
* '''/etc/nginx/conf.d/''' – per‑site reverse‑proxy configs
* '''/var/www/letsencrypt/''' – ACME challenge directory
* '''/etc/letsencrypt/live/<domain>/''' – certificate files

== ACME Challenge Directory ==
Certbot uses a shared directory for HTTP‑01 validation:

<syntaxhighlight lang="bash">
/var/www/letsencrypt/
</syntaxhighlight>

nginx exposes this path for both domains.

== Site: research.costasano.club ==
=== HTTP (port 80) ===
Redirects all traffic to HTTPS, except ACME challenges.

<syntaxhighlight lang="nginx">
server {
listen 80;
listen [::]:80;
server_name research.costasano.club;

location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}

return 301 https://$host$request_uri;
}
</syntaxhighlight>

=== HTTPS (port 443) ===
Terminates TLS and proxies to Apache.

<syntaxhighlight lang="nginx">
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;

server_name research.costasano.club;

ssl_certificate /etc/letsencrypt/live/research.costasano.club/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/research.costasano.club/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}

location / {
proxy_pass http://192.168.33.231;

proxy_set_header Host research.costasano.club;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;

proxy_buffering on;
proxy_buffers 16 16k;
proxy_buffer_size 16k;

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}
</syntaxhighlight>

== Site: mwiki.costasano.club ==
=== HTTP (port 80) ===
<syntaxhighlight lang="nginx">
server {
listen 80;
listen [::]:80;
server_name mwiki.costasano.club;

location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}

return 301 https://$host$request_uri;
}
</syntaxhighlight>

=== HTTPS (port 443) ===
<syntaxhighlight lang="nginx">
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;

server_name mwiki.costasano.club;

ssl_certificate /etc/letsencrypt/live/mwiki.costasano.club/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mwiki.costasano.club/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}

location / {
proxy_pass http://192.168.33.231;

proxy_set_header Host mwiki.costasano.club;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;

proxy_buffering on;
proxy_buffers 16 16k;
proxy_buffer_size 16k;

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}
</syntaxhighlight>

== Certificate Renewal ==
Certbot is installed natively on AlmaLinux.

=== Renewal Timer ===
<syntaxhighlight lang="bash">
systemctl status certbot-renew.timer
</syntaxhighlight>

The timer runs daily and triggers renewal when certificates approach expiry.

=== Manual Dry‑Run Test ===
<syntaxhighlight lang="bash">
sudo certbot renew --dry-run
</syntaxhighlight>

== Windows/IIS Retirement ==
The former IIS reverse‑proxy and win‑acme renewal system were removed:
* IIS sites deleted
* win‑acme renewal entries cancelled
* scheduled tasks removed
* old certificates removed from certlm.msc
* no bindings remain on ports 80/443

== Verification Checklist ==
* nginx configs validated: <code>nginx -t</code>
* nginx reloaded: <code>systemctl reload nginx</code>
* certbot timer active
* ACME challenge reachable
* backend Apache reachable
* Windows silent on ports 80/443

== Architecture Diagram (ASCII) ==

The following diagram shows the full request flow from the internet to the backend applications.

<pre>
+----------------------+
| Internet |
+----------+-----------+
|
v
+----------------------+
| AlmaLinux Server |
| (frontend) |
+----------+-----------+
|
HTTPS :443 / HTTP :80
|
v
+---------------+
| nginx |
| reverse proxy|
+-------+-------+
|
+-------------------+-------------------+
| |
v v
+---------------------+ +---------------------+
| research.costasano | | mwiki.costasano |
| .club (vhost) | | .club (vhost) |
+----------+----------+ +----------+----------+
| |
| proxy_pass http://192.168.33.231 |
+-------------------------+-----------+
|
v
+------------------------+
| Apache (backend) |
| 192.168.33.231 |
+-----------+------------+
|
+-------------------+-------------------+
| |
v v
+-------------------+ +-------------------+
| Drupal site | | MediaWiki site |
| research.* | | mwiki.* |
+-------------------+ +-------------------+

ACME / Let’s Encrypt HTTP-01 validation:

Let’s Encrypt ---> nginx ---> /var/www/letsencrypt/
(both vhosts expose
/.well-known/acme-challenge/)

Certificates:

/etc/letsencrypt/live/research.costasano.club/
/etc/letsencrypt/live/mwiki.costasano.club/

Renewal:

systemd timer: certbot-renew.timer
service: certbot-renew.service
</pre>

== Rationale for Replacing IIS with nginx ==

This section explains why the former Windows/IIS reverse‑proxy was retired in favour of a native Linux‑based nginx setup. The decision was driven by stability, clarity, maintainability, and long‑term operational safety.

=== 1. Architectural Simplicity ===
The previous setup required:
* Windows Server
* IIS with URL Rewrite + ARR
* win-acme for certificate renewal
* Manual bindings for each hostname
* Coordination between Windows and the Linux backend

This created a multi‑platform dependency chain.
The new setup collapses the entire frontend into a single, predictable layer:
* AlmaLinux
* nginx
* certbot (systemd‑managed)

Fewer moving parts → fewer failure points.

=== 2. Elimination of Cross‑Platform Coupling ===
The old architecture required Windows to proxy traffic to Linux.
This meant:
* Two operating systems had to stay in sync
* Two certificate systems had to be maintained
* Two sets of logs had to be consulted during troubleshooting

By moving the reverse‑proxy to the same machine that hosts the backend, the system becomes self‑contained and easier to reason about.

=== 3. Cleaner TLS and Certificate Management ===
The Windows setup used win‑acme, scheduled tasks, and IIS bindings.
This caused:
* Duplicate certificate stores
* Renewal tasks that were easy to forget
* Certificates living on a machine that no longer served the content

The new setup uses:
* certbot
* systemd timers
* a shared ACME challenge directory
* certificates stored exactly where they are used

This is simpler, safer, and fully automated.

=== 4. nginx Is Purpose‑Built for Reverse‑Proxying ===
nginx excels at:
* high‑performance proxying
* buffering
* header management
* HTTP/2
* TLS termination

IIS can do these things, but only through multiple modules (ARR, URL Rewrite) and with more complexity. nginx provides them natively and predictably.

=== 5. Reduced Operational Overhead ===
The Windows/IIS layer required:
* OS patching
* IIS updates
* win‑acme maintenance
* Monitoring of scheduled tasks
* Manual cleanup of old bindings and certificates

The nginx layer requires:
* a single systemd timer
* a single config directory
* one place to check logs

This reduces cognitive load for both you and any future maintainer.

=== 6. Successor‑Friendly Documentation and Maintenance ===
The new architecture is:
* linear
* transparent
* fully documented
* reproducible
* platform‑consistent

A successor only needs to understand:
* nginx vhost files
* certbot
* Apache backend routing

No Windows knowledge is required.

=== 7. Removal of Legacy Dependencies ===
The IIS reverse‑proxy was originally introduced as a workaround during earlier infrastructure phases.
Now that the backend is stable on AlmaLinux, the Windows layer no longer serves a purpose and only adds risk.

Removing it:
* reduces attack surface
* removes unused services
* avoids silent port conflicts
* simplifies backups and disaster recovery

=== Summary ===
The migration from IIS to nginx was not just a technical change but an architectural improvement.
It aligns the system with:
* clarity
* maintainability
* long‑term stability
* reduced operational burden
* successor‑friendly design

The result is a cleaner, more predictable, and more robust infrastructure.

== Before vs After: Reverse‑Proxy Architecture ==

The table below summarizes the differences between the former IIS‑based setup and the current nginx‑based architecture.

{| class="wikitable"
! Aspect
! '''Before: Windows + IIS'''
! '''After: AlmaLinux + nginx'''

|-
| Reverse‑proxy layer
| IIS with ARR + URL Rewrite
(added modules, multi‑step configuration)
| nginx (native reverse‑proxy, single config file per site)

|-
| Operating system
| Windows Server
(separate from backend)
| AlmaLinux
(same platform as backend)

|-
| Certificate management
| win‑acme (scheduled task, IIS bindings)
Certificates stored in Windows certificate store
| certbot (systemd timer)
Certificates stored directly under /etc/letsencrypt/

|-
| ACME challenge handling
| IIS rewrite rules + filesystem mapping
More fragile and harder to debug
| Direct nginx location block
Shared ACME directory for all vhosts

|-
| Number of moving parts
| High: Windows + IIS + ARR + Rewrite + win‑acme
| Low: nginx + certbot

|-
| Logging
| Split across Windows Event Viewer, IIS logs, win‑acme logs
| Unified: nginx logs + certbot logs

|-
| Maintenance burden
| Requires Windows patching, IIS updates, scheduled task monitoring
| Minimal: systemd‑managed services, simple config reloads

|-
| Failure modes
| Certificate renewal failures often silent
Bindings could break after updates
Proxy rules spread across GUI modules
| Transparent and predictable
Config validated with nginx -t
Renewal handled by systemd

|-
| Security surface
| Larger (Windows + IIS + ARR + Rewrite)
| Smaller (nginx only)

|-
| Successor‑friendliness
| Requires Windows + IIS knowledge
Proxy logic hidden behind GUI layers
| Fully text‑based, documented, reproducible
Easy for any Linux‑familiar maintainer

|-
| Architectural clarity
| Cross‑platform coupling (Windows → Linux)
| Single‑platform, self‑contained frontend

|}

== Status ==
The reverse‑proxy setup is stable, maintainable, and fully Linux‑native.

== Troubleshooting Appendix ==

This appendix lists common issues that may occur in the nginx → Apache reverse‑proxy setup, along with clear diagnostic steps and expected outcomes. It is designed to help future maintainers quickly identify where a failure originates.

=== 1. Site Not Loading (General) ===
If a site does not load at all:

# Check nginx status:
<syntaxhighlight lang="bash">
systemctl status nginx
</syntaxhighlight>

# Validate configuration:
<syntaxhighlight lang="bash">
nginx -t
</syntaxhighlight>

# Reload nginx:
<syntaxhighlight lang="bash">
systemctl reload nginx
</syntaxhighlight>

If nginx fails to start or reload, the error message will point to the exact file and line.

=== 2. HTTPS Works but HTTP Does Not Redirect ===
Symptoms:
* Visiting http://domain shows an error
* Visiting https://domain works normally

Check the port 80 server block for the domain:
* It must include the ACME location block
* It must end with: <code>return 301 https://$host$request_uri;</code>

Restart nginx after correcting:
<syntaxhighlight lang="bash">
systemctl reload nginx
</syntaxhighlight>

=== 3. Certificate Renewal Fails ===
Symptoms:
* Certbot emails warnings
* Browser shows certificate expiring soon
* Dry‑run renewal fails

Diagnostics:

# Test ACME challenge manually:
<syntaxhighlight lang="bash">
curl http://domain/.well-known/acme-challenge/test
</syntaxhighlight>

Expected:
* 404 Not Found (normal)
* NOT a 403 or 500

# Check permissions:
<syntaxhighlight lang="bash">
ls -ld /var/www/letsencrypt
</syntaxhighlight>

# Run a dry‑run:
<syntaxhighlight lang="bash">
sudo certbot renew --dry-run
</syntaxhighlight>

If renewal fails, the error message will indicate whether nginx routing or filesystem access is the cause.

=== 4. Backend (Apache) Not Responding ===
Symptoms:
* nginx returns 502 Bad Gateway
* nginx returns 504 Gateway Timeout

Diagnostics:

# Check Apache:
<syntaxhighlight lang="bash">
systemctl status httpd
</syntaxhighlight>

# Test backend directly:
<syntaxhighlight lang="bash">
curl http://192.168.33.231
</syntaxhighlight>

If Apache is down, restart it:
<syntaxhighlight lang="bash">
systemctl restart httpd
</syntaxhighlight>

If Apache is up but unreachable, check firewall rules.

=== 5. Wrong Site Appears (Host Header Issue) ===
Symptoms:
* Visiting research.* shows the MediaWiki site
* Visiting mwiki.* shows the Drupal site

Cause:
* Missing or incorrect <code>proxy_set_header Host ...</code> in nginx

Fix:
Ensure each vhost sets the correct Host header:
<syntaxhighlight lang="nginx">
proxy_set_header Host research.costasano.club;
</syntaxhighlight>

Reload nginx afterwards.

=== 6. ACME Challenge Returns 404 ===
Symptoms:
* Certbot renewal fails
* Browser shows 404 for ACME path

Check that both vhosts contain:
<syntaxhighlight lang="nginx">
location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}
</syntaxhighlight>

Ensure the directory exists:
<syntaxhighlight lang="bash">
ls /var/www/letsencrypt
</syntaxhighlight>

=== 7. Windows Still Interfering (Legacy Setup) ===
Symptoms:
* Port conflicts
* Unexpected certificates
* Old bindings still active

Diagnostics on Windows:

# Check ports:
<syntaxhighlight lang="powershell">
netstat -ano | findstr :80
netstat -ano | findstr :443
</syntaxhighlight>

# Check IIS:
Ensure no sites remain in IIS Manager.

# Check scheduled tasks:
Remove any leftover win‑acme tasks.

If Windows is still listening on 80/443, disable the Web Server (IIS) role entirely.

=== 8. Browser Shows Old Certificate ===
Symptoms:
* Browser still shows the old expiry date
* Renewal succeeded on the server

Possible causes:
* Browser caching
* Intermediate certificate caching
* CDN or proxy caching (if applicable)

Fix:
* Hard refresh (Ctrl+F5)
* Test with curl:
<syntaxhighlight lang="bash">
curl -v https://domain
</syntaxhighlight>

The certificate shown by curl is authoritative.

=== 9. nginx Reload Fails After Editing Config ===
Symptoms:
* <code>systemctl reload nginx</code> fails
* nginx refuses to start

Run:
<syntaxhighlight lang="bash">
nginx -t
</syntaxhighlight>

This will show:
* the file
* the line
* the exact syntax error

Fix the issue and reload nginx.

=== 10. Slow Responses or Timeouts ===
Symptoms:
* Pages load slowly
* MediaWiki or Drupal feels sluggish

Check proxy timeouts:
<syntaxhighlight lang="nginx">
proxy_read_timeout 60s;
proxy_send_timeout 60s;
</syntaxhighlight>

Check backend load:
<syntaxhighlight lang="bash">
top
systemctl status httpd
</syntaxhighlight>

If Apache is overloaded, investigate modules, PHP-FPM, or database performance.

== Summary ==
This appendix provides a structured approach to diagnosing issues in the nginx → Apache reverse‑proxy setup. Most problems fall into one of three categories:
* nginx configuration
* certificate renewal
* backend availability

Following the steps above should isolate the cause quickly and safely.

== Notes for AlmaLinux 10.1 Security Changes ==

AlmaLinux 10.1 introduces several security‑related changes that affect nginx, certbot, and
backend communication. The following points must be checked whenever the system is updated
or rebuilt.

=== 1. SELinux: Stricter Defaults ===
AlmaLinux 10.1 enforces tighter SELinux rules, especially for:
* nginx reading files outside /usr/share/nginx/html
* ACME challenge directories
* proxy connections to backend servers

Ensure:
<syntaxhighlight lang="bash">
semanage fcontext -a -t httpd_sys_content_t "/var/www/letsencrypt(/.*)?"
restorecon -Rv /var/www/letsencrypt
</syntaxhighlight>

If nginx cannot reach Apache:
<syntaxhighlight lang="bash">
setsebool -P httpd_can_network_connect 1
</syntaxhighlight>

=== 2. FirewallD: More Restrictive Defaults ===
After updates, FirewallD may re‑apply stricter profiles.

Verify:
<syntaxhighlight lang="bash">
firewall-cmd --list-services
</syntaxhighlight>

Ensure:
* http
* https

are enabled permanently.

=== 3. OpenSSL 3.x Enforcement ===
AlmaLinux 10.1 uses OpenSSL 3.x with stricter cipher policies.

Ensure nginx uses:
* TLSv1.2
* TLSv1.3

and avoid deprecated ciphers.

=== 4. Systemd Hardening of Services ===
Some systemd units (nginx, certbot) may receive tightened sandboxing.

If certbot renewal fails after an update:
<syntaxhighlight lang="bash">
journalctl -u certbot-renew.service
</syntaxhighlight>

Check for:
* permission denials
* sandbox restrictions
* missing ACME directory access

=== 5. nginx: HTTP/2 and TLS Requirements ===
AlmaLinux 10.1 enforces modern TLS for HTTP/2.

Ensure:
<syntaxhighlight lang="nginx">
http2 on;
ssl_protocols TLSv1.2 TLSv1.3;
</syntaxhighlight>

HTTP/2 will silently disable itself if insecure ciphers are used.

=== 6. Apache: Private IP Binding Verification ===
After updates, Apache may rebind or change Listen directives.

Verify:
<syntaxhighlight lang="bash">
grep -R "Listen" /etc/httpd/conf*
</syntaxhighlight>

Expected:
* Apache listens on 192.168.33.231:80
* NOT on 0.0.0.0:80 (to avoid conflicts)

=== 7. Certbot: Renewal Timer Integrity ===
System updates may reset or disable timers.

Verify:
<syntaxhighlight lang="bash">
systemctl status certbot-renew.timer
systemctl list-timers | grep certbot
</syntaxhighlight>

Expected:
* Timer active
* Next run scheduled within 24 hours

=== 8. Kernel-Level Networking Changes ===
AlmaLinux 10.1 includes updated nftables and TCP stack behaviour.

If proxying becomes slow or unstable:
<syntaxhighlight lang="bash">
sysctl net.ipv4.ip_local_port_range
sysctl net.core.somaxconn
</syntaxhighlight>

Ensure defaults are not overly restrictive.

== Summary ==
AlmaLinux 10.1 is more secure by default, but this can affect nginx, certbot, and Apache
interactions. After any major update, verify:
* SELinux permissions
* FirewallD rules
* nginx TLS configuration
* Apache binding
* certbot timers

This ensures the reverse‑proxy remains stable and predictable.

ICT:Reverse-Proxy on AlmaLinux with nginx to apache backend

2026-03-25T17:56:51Z

Mngr: Created page with "= Reverse‑Proxy Architecture (nginx → Apache) = This page documents the complete reverse‑proxy setup for the AlmaLinux frontend server. It replaces the former IIS reverse‑proxy and Windows‑based certificate renewal system. The configuration is now fully Linux‑native, stable, and successor‑friendly. == Overview == * Frontend: AlmaLinux + nginx * Backend: Apache (Drupal + MediaWiki) * Certificates: Let’s Encrypt (certbot) * Automatic renewal: systemd timer..."

ICT:Drupal Blueprint - Version 6.5

2026-03-23T10:51:15Z

Mngr:

= Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.5) =

== Purpose of this Document ==
This page defines the architectural, conceptual, and workflow foundations of the Costasano Heritage Project.

It serves as:
* a stable reference for human contributors
* a briefing document for AI-assisted work sessions
* a safeguard against context loss over long-term development

All future design, implementation, and automation decisions must be compatible with the principles defined here.

----

== Project Overview ==

The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists, except for Martin, realising the IT-project, also amateur historian).

The project manages:
* hundreds of gigabytes of documents, images, and maps
* collaborative historical research
* multi-channel dissemination (wiki, public website, exhibitions, video)

The system is designed for '''decades-long durability''', not short-term publication.

----

== Core Philosophy ==

=== Authoritative Source Principle ===
There is exactly ONE authoritative system for data and assets:
* '''Drupal 11.3'''

All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.

No downstream system is allowed to correct, invent, or override facts.
All corrections must return to Drupal.

----

=== Asset-Centric Design ===
The central object of the entire system is:

'''Asset + File (ONE asset = ONE file)'''

Everything else (chapter, place, organisation) exists to:
* contextualize assets
* classify assets
* generate stable identifiers
* reuse assets across outputs
* chapters provide a sort of timeline

----

=== Ingest First, Enrich Later ===
The system must allow:
* rapid bulk ingestion of files with minimal metadata
* gradual collaborative enrichment over time
* clear lifecycle states without pressure for completeness

Completeness is a process, not a prerequisite.

----

== Target Users & UX Constraints ==

=== User Profile ===
* Age: 70+
* Background: amateur historians
* ICT skills: minimal
* Tolerance for complexity: low

=== UX Non-Negotiables ===
* No technical terminology exposed (no “entity”, “taxonomy”, “foreign key”)
* No cluttered forms
* Dashboard-first and only navigation
* Large click targets
* Predictable layouts
* Dark mode mandatory (accessibility)

Users must never feel they are “using Drupal”.

----

== System Architecture ==

=== Infrastructure ===
* Reverse Proxy: Windows Server 2019 (IIS + ARR, SSL offloading)
* Web Server: AlmaLinux 10.1 (Apache 2.4.63, PHP 8.3.29, PHP-FPM)
* Database Server: AlmaLinux 10.1 (MariaDB 10.11.15)
* Drupal 11.3.5
* SELinux: Enforcing
* PHP-FPM: Per-site pools
* Filesystem: Hardened

=== Operational Constants ===
* '''Site URL''': https://research.costasano.club
* '''Drupal project root''': /var/www/drupal
* '''Drupal web root''': /var/www/drupal/web

----

== Output Channels ==

=== 1. MediaWiki (Research & Writing) ===
Role:
* illustrated research pages
* collaborative narrative writing
* preparation for Wikipedia publication

MediaWiki does NOT:
* store authoritative metadata
* manage files
* generate identifiers

----

=== 2. Public Drupal Website ===
Role:
* curated presentation of selected research
* timelines, maps, galleries

Only “complete” or approved assets are shown publicly.

----

=== 3. Offline Outputs ===
* video documentaries
* lectures
* exhibitions

These reuse:
* the same assets
* the same identifiers
* the same metadata

----

== Authority Entity Implementation Strategy ==

Authority entities are implemented progressively, from simplest to most complex.

----

=== Step 1: Chapter (Temporal Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Meaning:
* historical periods / timeline segmentation
* not editorial or narrative content

Characteristics:
* stable Code (max 6 characters) like CHxx.ab CH01, CH01a, CH01aa, CH01ab
* recursive (parent/child) two levels using small letters after the first four
* stable Code (max 6 characters)
* used as first mandatory component in asset identifiers
* no sequence field

Dashboard pattern:
* table of existing records
* add new record
* click pencil in front of row to edit

Status: Drupal Context Type and Dashboard page operational
Changed decision about chapter code layout
ToDo (max 6 characters)
* Address field for geocoding
* coordinates auto-derived when possible
* coordinates never required for ingestion

Purpose:
* spatial context
* optionally reused across assets for numbering reasoons
* reused for organisations

Status: Drupal Context Type and Dashboard page operational
Recently added: type list, geo link in view towards openstreetmap
Added view adapted to type.
Address to coordinates implemented using Openstreatmap providers.
ToDo:Completing helpfunctions

----

=== Step 3: Organisation (Institutional Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Characteristics:
* stable Code (max 6 characters)
* linked to a Place
* optionally reused across assets for numbering

Purpose:
* institutional context
* archival provenance

Status: Drupal Context Type and Dashboard page operational
ToDo: adding map view based on Place coordinnates now that provider is available
Completing help functions

----

=== Step 4: Asset (CORE ENTITY) ===
Type:
* '''Drupal Custom Content Entity'''

Rules:
* ONE asset = ONE file
* file is immutable once uploaded
* identifier is immutable once generated
* physical filenames are managed by Drupal
* original filename is preserved for user reference

Identifier format:
* Chapter.Code
* Context.Code = Place.Code OR Organisation.Code
* Scoped 5-digit counter (asset sequence only)

Example:
<pre>
CH03ab-OOSTEN-00007
</pre>

Asset creation is impossible before Chapter, Place, and Organisation exist.

Status: Drupal Context Type and View complete
Use of special configuration of classic Media-Library for media upload.
Upload of images, documents, video and audio foreseen
Automatic numbering for asset via a custom module
Creation in 2 steps: first essential fields to generate autonumbering.
After that, use of editing via table to fill un further fields like description and note.
Optional change of other fields except autocode.
View enhanced with search filter.
ToDo: complete help functions
Remark: Inital configuration with Code as PK (Drupal Title) has been abandoned.
Now Code is a classic field and the Title field is a Caption field. This is a short description of the file.

== Next Major step: Person and HeritageObject and the m-m relationship with Asset ==

=== Step 5: Person implementation ===

A '''Person''' represents a historical individual with agency.

It answers the question:

''“Who was involved historically?”''

A person is:

* religious sisters
* directors
* architects
* patients
* shareholders
* board members

A Person may:

* play roles in relation to HeritageObjects
* play roles within Organizations
* act as a holder of HeritageObjects
* be documented by DigitalAssets (portraits, letters, biographies, articles)

Roles belong to relationships, not to the Person entity itself.

Purpose: Persons model historical agency, responsibility, and participation.

Implementation:
- automatic numbering of Person entities realized with custom module: PE-00123
- use for plain text for birthday and deathday due to drupal limitation in Date & Time widget
- use of custom module to verify the day format DD/MM/YYYY
- both modules are implemented in heritage-tweaks
- first view operational
ToDo: refinement

=== Step 6: HeritageObject implementation ===
The implementation of HeritageObject abbreviated Object in Drupal

A '''HeritageObject (HO)''' represents a historical, conceptual, or material entity that is the subject of study.

It answers the question:

''“What is the thing we are studying?”''

A HeritageObject may represent:

* a sanatorium
* a building
* a document or register
* a historically meaningful place
* a room, component, or architectural element
* a conceptual or functional unit (e.g. “medical practice”)

HeritageObjects are '''recursive'''.

Each HeritageObject may:

* have zero or one parent HeritageObject
* have zero or more child HeritageObjects

A HeritageObject may:

* be documented by multiple DigitalAssets
* designate one DigitalAsset as preferred representation
* be linked to Persons with roles
* be linked to Organizations with roles
* have Persons or Organizations as holders
* belong to multiple ResearchChapters
* be tagged with Keywords
* be associated with one or more Places

Purpose: HeritageObjects are the primary conceptual anchors of the research.

Implementation:
- automatic numbering of object entity: OB-00123
- Onject is recursive

ToDo
- implementation of a many to many relationship between Object and Asset
- One digital Asset is a prefered Asset only for illustration purposes of the Object in a view
- Notion of top" Asset in the asset structure is the Asset without parent to by used in the many-to-many relationship. This top asset gives also access to the full tree of assets linked to that top. That top may change in the lifetime of the asset-tree (decided by the user).

=== Step 7: Object & Advanced Relationships ===
Type:
* Custom Content Entities
* Role-based relationships
* other many-to-many relationships

----

== Asset Lifecycle & Collaboration Workflow ==

=== Roles (conceptual) ===
* '''Ingestor'''
** uploads files
** assigns minimal context
* '''Enricher'''
** adds metadata
** validates data

One person may have multiple roles.

----

=== Lifecycle States ===
* Newly added
* In progress
* Reviewed
* Complete

States describe maturity, not publication.

----

== Dashboard Design Pattern ==

For Chapter, Place, Organisation:
* single dashboard page
* table of existing records
* add/edit via simple forms

Status: done

For Assets:
* add asset always visible
* recent assets list
* guided asset discovery
* no massive tables

Status: Done,
Refining realised dealing with massive amounts of assets: using a combined field filter.

----

== Help & Guidance Strategy ==

Help must be:
* contextual
* non-intrusive
* always available

Mechanisms:
* field descriptions
* ℹ️ icons (difficult in Drupal - placeholders may help here)
* collapsible help sections
* TBD?: link to MediaWiki Reasearch namespace for extended documentation and system philosophy desccription

----

== Automation & Logic ==

Automation is handled via:
* Drupal configuration and extra available modules
* Custom modules if really necessary, and simplifying a lot the implementation
* take care: using drupal 11.3 - based on new (OO) concepts - needs special attention in building custom modules

Automation is used to:
* generate identifiers
* manage asset counters
* enforce immutability rules
* reduce cognitive load

Automation must never obscure what happens.

----

== Design Discipline Rules ==

* No authority entity is implemented as editorial content
* No field is required unless it enables a mechanism
* No output system becomes authoritative
* No UX decision is optimized for power users
* Stability is more important than elegance

----

== Usage in AI Sessions ==

This document must be:
* pasted or referenced at the start of new AI-assisted sessions
* treated as authoritative context
* updated only when architectural decisions change and progress is made

AI output must conform to this blueprint.

== AI Session protocol ==
* no hurry - simple step by simple step: AI proposes, sysop executes finishing with ACK
* no long explanations and justifications - sysop will ask for if needed.
* making the requirement work is the most important step, sysop will documenent once a milestone is achieved.
* AI will suggest a synthesis in mediawikitext format on sysop request to feed the documentation

----

== Supplement — UI Theming, Accessibility & Visual Discipline ==

This supplement records explicit requirements related to visual theming, accessibility, and user comfort that were clarified after initial project restart.
These requirements are binding and must be respected in all future design and implementation decisions.

----

=== Separation of UI Concerns ===

The system UI is explicitly divided into two independent domains:

* '''Administrative / Dashboard UI''' (authenticated users)
* '''Public Presentation UI''' (anonymous visitors)

No design, theme, or UX decision in one domain is allowed to negatively affect the other.

Decisions:
* GIN skin is used for administration and user input in mandatory DARK mode.
* SOLO skin is used for public pages.

----

=== Administrative & Dashboard UI (Authenticated Users) ===

==== Target Users ====
* System administrator (username: '''mngr''')
* Club members and contributors (e.g. '''testuser''')
* Age profile: 70+
* Long working sessions expected

==== Mandatory Requirements ====
* '''Permanent dark mode''' is used via the GIN skin/template
* Preferred no custom CSS or hacks

==== Scope ====
* Applies to:
** content ingestion
** asset enrichment
** review workflows
** dashboards
* Applies equally to administrators and non-technical contributors

==== Design Discipline ====
* Accessibility and eye comfort take precedence over aesthetics
* The administrative UI must remain:
** predictable
** low-contrast-stress
** uncluttered

----

=== Public Presentation UI (Anonymous Users) ===

==== Audience ====
* General public
* Researchers
* Visitors with unknown accessibility needs

==== Mandatory Requirements ====
* Public-facing theme must be:
** modern
** responsive / adaptive
** suitable for long-term institutional use

DECISION: SOLO skin/template has been choosen for dealing with these requirements

----

=== Timing & Implementation Rules ====

* Public-facing theming is explicitly deferred until:
** asset logic is validated
** authoritative entities are stable
* Early decisions must not constrain future design exploration, but must enforce:
** accessibility
** adaptability
** long-term maintainability

----

=== Stability Principle (UI) ====

* UI comfort is a prerequisite for correct decision-making
* Visual strain increases error rates and architectural drift
* Therefore:
** administrative UI comfort is non-negotiable
** public UI adaptability is mandatory

=== Naming conventions - Design discipline ===
All attributes in an entity will have the first 2 letters of the entity as prefix in the Drupal machine name.
Example: Chapter
field "Start Year" - machine name: ch_startyear internal storage name: field_ch_startyear
field "Description" - ch_description -- field_ch_description

Due to limitation in Drupal concerning the Data and Time widget, a plain text field is used for "day"..
A custom module checks the format DD/MM/YYY and the field is limited to 10 chars, explanation about the format including also a placemarker with the format. The machine field name should end on "_day".

== Implementation Status - March 23th 2026) ==

Entities implemented:

* Chapter
* Place
* Organisation
* Asset (basic structure)
* Person
* Object

All entities include:
* dashboards via Views
* edit workflow via dashboard
* recursive relationships where required
* FK implemented
* entity references verified

== End of Blueprint ==

== Appendix - 1: Data Model -

<pre>
// =====================================================
// Costasano Heritage Database Model — v5.0
// =====================================================

// ==== HERITAGE OBJECTS ====

Table Object {
Code string [pk]
Parent string [ref: > Object.Code]
Name string
Type string
Subtype string
Place string [ref: > Place.Code]
DateFrom date
DateTo date
Description text
Notes text
}

// ==== DIGITAL ASSETS ====

Table Asset {
Caption string
Code string [pk]
Chapter string [ref: > Chapter.Code]
Place string [ref: > Place.Code]
Organisation string [ref: > Organisation.Code]
Sequence int
MediaFile string [ref: > Files.id]
Parent string [ref: > Asset.Code]
AssetSourceType string [ref: > AssetSourceType.Code]
AssetType string [ref: > AssetType.Code]
SourceReference string
Description text
Notes text
AiProcessed boolean
Citation text
Permalink string
Repository string
Rights string
IsPublishable boolean
}

// ==== EXTERNAL DRUPAL FILES ====

Table Files {
id string [pk]
Label string
Timestamp datetime
User string
Comment text
Size int
Sha1 string
Mime string
Url string
}

// ==== RESEARCH ENTITIES ====

Table Person {
Code string [pk]
FirstName string
LastName string
BirthDate date
DeathDate date
Biography text
Contact text
Notes text
}

Table Organisation {
Code string [pk]
Name string
Place string [ref: > Place.Code]
Description text
Contact text
Notes text
}

Table Place {
Code string [pk]
Parent string [ref: > Place.Code]
Label string
Type string
Latitude float
Longitude float
Description text
Notes text
}

Table Chapter {
Code string [pk]
Description string
Parent string [ref: > Chapter.Code]
StartYear integer
EndYear integer
Notes text
}

// ==== LOOKUP TABLES ====

Table ObjectType {
Code string [pk]
Description text
}

Table AssetSourceType {
Code string [pk]
Label string
Description text
}

Table AssetType {
Code string [pk]
Name string
Description text
}

Table AssetRole {
Code string [pk]
Name string
Description text
}

Table PersonRole {
Code string [pk]
Name string
Description text
}

Table OrganisationRole {
Code string [pk]
Name string
Description text
}

Table Keywords {
Code string [pk]
Name string
Description text
}

// ==== RELATIONSHIP TABLES (Junctions) ====

Table ObjectAsset {
id string [pk]
Object string [ref: > Object.Code]
Asset string [ref: > Asset.Code]
Role string [ref: > AssetRole.Code]
IsPreferred boolean
}

Table PersonAsset {
id string [pk]
Person string [ref: > Person.Code]
Asset string [ref: > Asset.Code]
}

Table OrganisationAsset {
id string [pk]
Organisation string [ref: > Organisation.Code]
Asset string [ref: > Asset.Code]
}

Table OjectChapter {
id string [pk]
Object string [ref: > Object.Code]
Chapter string [ref: > Chapter.Code]
}

Table ObjectPerson {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Role string [ref: > PersonRole.Code]
}

Table ObjectOrganisation {
id string [pk]
Object string [ref: > Object.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table PersonOrganisationRole {
id string [pk]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table ObjectKeyword {
id string [pk]
Object string [ref: > Object.Code]
Keyword string [ref: > Keywords.Code]
}

Table ObjectHolder {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
}
</pre>

= Appendix - 2: Modules already enabled in our Drupal 11 configuration - version 20260319 ==

<pre>
mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
---------------- ----------------------------------------------------------------------- --------- ----------
Package Name Status Version
---------------- ----------------------------------------------------------------------- --------- ----------
Core Announcements (announcements_feed) Enabled 11.3.5
Core Automated Cron (automated_cron) Enabled 11.3.5
Core BigPipe (big_pipe) Enabled 11.3.5
Core Block (block) Enabled 11.3.5
Core Block Content (block_content) Enabled 11.3.5
Core Breakpoint (breakpoint) Enabled 11.3.5
Core CKEditor 5 (ckeditor5) Enabled 11.3.5
Core Comment (comment) Enabled 11.3.5
Core Configuration Manager (config) Enabled 11.3.5
Core Contact (contact) Enabled 11.3.5
Core Contextual Links (contextual) Enabled 11.3.5
Field types Datetime (datetime) Enabled 11.3.5
Field types Datetime Range (datetime_range) Enabled 11.3.5
Core Database Logging (dblog) Enabled 11.3.5
Core Internal Dynamic Page Cache (dynamic_page_cache) Enabled 11.3.5
Core Text Editor (editor) Enabled 11.3.5
Core Field (field) Enabled 11.3.5
Core Field UI (field_ui) Enabled 11.3.5
Field types File (file) Enabled 11.3.5
Core Filter (filter) Enabled 11.3.5
Core Help (help) Enabled 11.3.5
Core History (history) Enabled 11.3.5
Field types Image (image) Enabled 11.3.5
Core Inline Form Errors (inline_form_errors) Enabled 11.3.5
Core Layout Builder (layout_builder) Enabled 11.3.5
Core Layout Discovery (layout_discovery) Enabled 11.3.5
Field types Link (link) Enabled 11.3.5
Core Media (media) Enabled 11.3.5
Core Media Library (media_library) Enabled 11.3.5
Core Custom Menu Links (menu_link_content) Enabled 11.3.5
Core Menu UI (menu_ui) Enabled 11.3.5
Core MySQL (mysql) Enabled 11.3.5
Core Node (node) Enabled 11.3.5
Field types Options (options) Enabled 11.3.5
Core Internal Page Cache (page_cache) Enabled 11.3.5
Core Path (path) Enabled 11.3.5
Core Path alias (path_alias) Enabled 11.3.5
Core Responsive Image (responsive_image) Enabled 11.3.5
Core Search (search) Enabled 11.3.5
Core Shortcut (shortcut) Enabled 11.3.5
Core System (system) Enabled 11.3.5
Core Taxonomy (taxonomy) Enabled 11.3.5
Field types Text (text) Enabled 11.3.5
Core Toolbar (toolbar) Enabled 11.3.5
Core Update Status (update) Enabled 11.3.5
Core User (user) Enabled 11.3.5
Core Views (views) Enabled 11.3.5
Core Views UI (views_ui) Enabled 11.3.5
Core Workspaces (workspaces) Enabled 11.3.5
Core Workspaces UI (workspaces_ui) Enabled 11.3.5
Field types Address (address) Enabled 2.0.4
Development Asset Injector (asset_injector) Enabled 8.x-2.21
Field types Color Field (color_field) Enabled 3.0.2
Other Computed Field (computed_field) Enabled 4.0.0
Other Contact Formatter (contact_formatter) Enabled 2.0.4
Core Dashboard (dashboard) Enabled 2.2.0
Field types Entity Reference Revisions (entity_reference_revisions) Enabled 8.x-1.14
Fields Field Group (field_group) Enabled 4.0.0
File metadata File metadata manager (file_mdm) Enabled 3.2.0
File metadata File metadata - EXIF (file_mdm_exif) Enabled 3.2.0
File metadata File metadata - Font (file_mdm_font) Enabled 3.2.0
Geocoding Geocoder (geocoder) Enabled 8.x-4.31
Geocoding Geocoder Address (geocoder_address) Enabled 8.x-4.31
Geocoding Geocoder Field (geocoder_field) Enabled 8.x-4.31
Geocoding Geocoder Geofield (geocoder_geofield) Enabled 8.x-4.31
Geofield Geofield (geofield) Enabled 10.3.4
Geolocation Geolocation (geolocation) Enabled 8.x-3.14
Geolocation Geolocation - Address (geolocation_address) Enabled 8.x-3.14
Geolocation Geolocation - Baidu Maps (geolocation_baidu) Enabled 8.x-3.14
Geolocation Geolocation - Here Maps (geolocation_here) Enabled 8.x-3.14
Geolocation Geolocation - Leaflet (geolocation_leaflet) Enabled 8.x-3.14
Other Gin Toolbar (gin_toolbar) Enabled 3.0.3
Media Image Effects (image_effects) Enabled 5.0.0
Media ImageMagick (imagemagick) Enabled 5.0.1
jQuery UI jQuery UI (jquery_ui) Enabled 8.x-1.8
jQuery UI jQuery UI Autocomplete (jquery_ui_autocomplete) Enabled 2.1.0
jQuery UI jQuery UI Menu (jquery_ui_menu) Enabled 2.1.0
User interface Klaro Cookie & Consent Manager (klaro) Enabled 3.0.8
Geofield Leaflet (leaflet) Enabled 10.4.4
Geofield Leaflet Markercluster (leaflet_markercluster) Enabled 10.4.4
Geofield Leaflet Views (leaflet_views) Enabled 10.4.4
User interface Linkit (linkit) Enabled 7.0.13
Other Media Library Form Element (media_library_form_element) Enabled 2.1.4
Paragraphs Paragraphs Type Permissions (paragraphs_type_permissions) Enabled 8.x-1.20
Paragraphs Paragraphs (paragraphs) Enabled 8.x-1.20
Paragraphs Paragraph Bundle 3D Carousel (paragraph_bundle_3d_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle 3D Flip Box (paragraph_bundle_3d_flip_box) Enabled 1.0.16
Paragraphs Paragraph Bundle Accordion (paragraph_bundle_accordion) Enabled 1.0.16
Paragraphs Paragraph Bundle Alert (paragraph_bundle_alert) Enabled 1.0.16
Paragraphs Paragraph Bundle Block (paragraph_bundle_block) Enabled 1.0.16
Paragraphs Paragraph Bundle Block Content (paragraph_bundle_block_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Card (paragraph_bundle_card) Enabled 1.0.16
Paragraphs Paragraph Bundle Carousel (paragraph_bundle_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle Contact Form (paragraph_bundle_contact_form) Enabled 1.0.16
Paragraphs Paragraph Bundle Content (paragraph_bundle_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Grid (paragraph_bundle_grid) Enabled 1.0.16
Paragraphs Paragraph Bundle Hero (paragraph_bundle_hero) Enabled 1.0.16
Paragraphs Paragraph Bundle Icon (paragraph_bundle_icon) Enabled 1.0.16
Paragraphs Paragraph Bundle Image (paragraph_bundle_image) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Background (paragraph_bundle_image_background) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Grid (Image Gallery - Lightbox) Enabled 1.0.16
(paragraph_bundle_image_grid)
Paragraphs Paragraph Bundle Image Overlay (paragraph_bundle_image_overlay) Enabled 1.0.16
Paragraphs Paragraph Bundle Layout (paragraph_bundle_layout) Enabled 1.0.16
Paragraphs Paragraph Bundle Modal (paragraph_bundle_modal) Enabled 1.0.16
Paragraphs Paragraph Bundle Node Reference (paragraph_bundle_node_reference) Enabled 1.0.16
Paragraphs Paragraph Bundle Parallax (paragraph_bundle_parallax) Enabled 1.0.16
Paragraphs Paragraph Bundle Slideshow (paragraph_bundle_slideshow) Enabled 1.0.16
Paragraphs Paragraph Bundle Tabs (paragraph_bundle_tabs) Enabled 1.0.16
Paragraphs Paragraphs Bundles (paragraphs_bundles) Enabled 1.0.16
Mail SMTP Authentication Support (smtp) Enabled 8.x-1.4
Solo Suite Solo Utilities (solo_utilities) Enabled 1.0.6
Other Sophron (sophron) Enabled 3.1.0
Media SVG Image Responsive (svg_image_responsive) Enabled 3.2.2
Media SVG image (svg_image) Enabled 3.2.2
Costasano Costasano Asset (costasano_asset) Enabled
Heritage Heritage Codes (heritage_codes) Enabled 1.0.0
Heritage Heritage Tweaks (heritage_tweaks) Enabled
Core Claro (claro) Enabled 11.3.5
Core Olivero (olivero) Enabled 11.3.5
Gin (gin) Enabled 5.0.12
Solo Solo (solo) Enabled 1.0.31
---------------- ----------------------------------------------------------------------- --------- ----------
</pre>

ICT:Drupal Blueprint - Version 6.5

2026-03-23T10:46:28Z

Mngr:

= Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.5) =

== Purpose of this Document ==
This page defines the architectural, conceptual, and workflow foundations of the Costasano Heritage Project.

It serves as:
* a stable reference for human contributors
* a briefing document for AI-assisted work sessions
* a safeguard against context loss over long-term development

All future design, implementation, and automation decisions must be compatible with the principles defined here.

----

== Project Overview ==

The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists, except for Martin, realising the IT-project, also amateur historian).

The project manages:
* hundreds of gigabytes of documents, images, and maps
* collaborative historical research
* multi-channel dissemination (wiki, public website, exhibitions, video)

The system is designed for '''decades-long durability''', not short-term publication.

----

== Core Philosophy ==

=== Authoritative Source Principle ===
There is exactly ONE authoritative system for data and assets:
* '''Drupal 11.3'''

All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.

No downstream system is allowed to correct, invent, or override facts.
All corrections must return to Drupal.

----

=== Asset-Centric Design ===
The central object of the entire system is:

'''Asset + File (ONE asset = ONE file)'''

Everything else (chapter, place, organisation) exists to:
* contextualize assets
* classify assets
* generate stable identifiers
* reuse assets across outputs
* chapters provide a sort of timeline

----

=== Ingest First, Enrich Later ===
The system must allow:
* rapid bulk ingestion of files with minimal metadata
* gradual collaborative enrichment over time
* clear lifecycle states without pressure for completeness

Completeness is a process, not a prerequisite.

----

== Target Users & UX Constraints ==

=== User Profile ===
* Age: 70+
* Background: amateur historians
* ICT skills: minimal
* Tolerance for complexity: low

=== UX Non-Negotiables ===
* No technical terminology exposed (no “entity”, “taxonomy”, “foreign key”)
* No cluttered forms
* Dashboard-first and only navigation
* Large click targets
* Predictable layouts
* Dark mode mandatory (accessibility)

Users must never feel they are “using Drupal”.

----

== System Architecture ==

=== Infrastructure ===
* Reverse Proxy: Windows Server 2019 (IIS + ARR, SSL offloading)
* Web Server: AlmaLinux 10.1 (Apache 2.4.63, PHP 8.3.29, PHP-FPM)
* Database Server: AlmaLinux 10.1 (MariaDB 10.11.15)
* Drupal 11.3.5
* SELinux: Enforcing
* PHP-FPM: Per-site pools
* Filesystem: Hardened

=== Operational Constants ===
* '''Site URL''': https://research.costasano.club
* '''Drupal project root''': /var/www/drupal
* '''Drupal web root''': /var/www/drupal/web

----

== Output Channels ==

=== 1. MediaWiki (Research & Writing) ===
Role:
* illustrated research pages
* collaborative narrative writing
* preparation for Wikipedia publication

MediaWiki does NOT:
* store authoritative metadata
* manage files
* generate identifiers

----

=== 2. Public Drupal Website ===
Role:
* curated presentation of selected research
* timelines, maps, galleries

Only “complete” or approved assets are shown publicly.

----

=== 3. Offline Outputs ===
* video documentaries
* lectures
* exhibitions

These reuse:
* the same assets
* the same identifiers
* the same metadata

----

== Authority Entity Implementation Strategy ==

Authority entities are implemented progressively, from simplest to most complex.

----

=== Step 1: Chapter (Temporal Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Meaning:
* historical periods / timeline segmentation
* not editorial or narrative content

Characteristics:
* stable Code (max 6 characters) like CHxx.ab CH01, CH01a, CH01aa, CH01ab
* recursive (parent/child) two levels using small letters after the first four
* stable Code (max 6 characters)
* used as first mandatory component in asset identifiers
* no sequence field

Dashboard pattern:
* table of existing records
* add new record
* click pencil in front of row to edit

Status: Drupal Context Type and Dashboard page operational
Changed decision about chapter code layout
ToDo (max 6 characters)
* Address field for geocoding
* coordinates auto-derived when possible
* coordinates never required for ingestion

Purpose:
* spatial context
* optionally reused across assets for numbering reasoons
* reused for organisations

Status: Drupal Context Type and Dashboard page operational
Recently added: type list, geo link in view towards openstreetmap
Added view adapted to type.
Address to coordinates implemented using Openstreatmap providers.
ToDo:Completing helpfunctions

----

=== Step 3: Organisation (Institutional Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Characteristics:
* stable Code (max 6 characters)
* linked to a Place
* optionally reused across assets for numbering

Purpose:
* institutional context
* archival provenance

Status: Drupal Context Type and Dashboard page operational
ToDo: adding map view based on Place coordinnates now that provider is available
Completing help functions

----

=== Step 4: Asset (CORE ENTITY) ===
Type:
* '''Drupal Custom Content Entity'''

Rules:
* ONE asset = ONE file
* file is immutable once uploaded
* identifier is immutable once generated
* physical filenames are managed by Drupal
* original filename is preserved for user reference

Identifier format:
* Chapter.Code
* Context.Code = Place.Code OR Organisation.Code
* Scoped 5-digit counter (asset sequence only)

Example:
<pre>
CH03ab-OOSTEN-00007
</pre>

Asset creation is impossible before Chapter, Place, and Organisation exist.

Status: Drupal Context Type and View complete
Use of special configuration of classic Media-Library for media upload.
Upload of images, documents, video and audio foreseen
Automatic numbering for asset via a custom module
Creation in 2 steps: first essential fields to generate autonumbering.
After that, use of editing via table to fill un further fields like description and note.
Optional change of other fields except autocode.
View enhanced with search filter.
ToDo: complete help functions
Remark: Inital configuration with Code as PK (Drupal Title) has been abandoned.
Now Code is a classic field and the Title field is a Caption field. This is a short description of the file.

== Next Major step: HeritageObject and Person ==

Now that Chapter, Place, Organisation and Asset are stable it is time for a next major step.
HeritageObject, Drupal called Object, is the next challenge due to the fact it has a many to many relationship with Asset,
is recursive and also linked to a serious number of other entities. One of these is Person, not yet prepared for. This will be the first next step.

=== Step 5: Person implementation ===

A '''Person''' represents a historical individual with agency.

It answers the question:

''“Who was involved historically?”''

A person is:

* religious sisters
* directors
* architects
* patients
* shareholders
* board members

A Person may:

* play roles in relation to HeritageObjects
* play roles within Organizations
* act as a holder of HeritageObjects
* be documented by DigitalAssets (portraits, letters, biographies, articles)

Roles belong to relationships, not to the Person entity itself.

Purpose: Persons model historical agency, responsibility, and participation.

Implementation:
- automatic numbering of Person entities realized with custom module: PE-00123
- use for plain text for birthday and deathday due to drupal limitation in Date & Time widget
- use of custom module to verify the day format DD/MM/YYYY
- both modules are implemented in heritage-tweaks
- first view operational
ToDo: Nihil for time being

=== Step 6: HeritageObject implementation ===
The implementation of HeritageObject abbreviated Object in Drupal

A '''HeritageObject (HO)''' represents a historical, conceptual, or material entity that is the subject of study.

It answers the question:

''“What is the thing we are studying?”''

A HeritageObject may represent:

* a sanatorium
* a building
* a document or register
* a historically meaningful place
* a room, component, or architectural element
* a conceptual or functional unit (e.g. “medical practice”)

HeritageObjects are '''recursive'''.

Each HeritageObject may:

* have zero or one parent HeritageObject
* have zero or more child HeritageObjects

A HeritageObject may:

* be documented by multiple DigitalAssets
* designate one DigitalAsset as preferred representation
* be linked to Persons with roles
* be linked to Organizations with roles
* have Persons or Organizations as holders
* belong to multiple ResearchChapters
* be tagged with Keywords
* be associated with one or more Places

Purpose: HeritageObjects are the primary conceptual anchors of the research.

Implementation:
- automatic numbering of object entity: OB-00123
- Onject is recursive

ToDO
- implementation of a many to many relationship between Object and Asset
- One digital Asset is a prefered Asset only for illustration purposes of the Object in a view
- Notion of top" Asset in the asset structure is the Asset without parent to by used in the many-to-many relationship. This top asset gives also access to the full tree of assets linked to that top. That top may change in the lifetime of the asset-tree (decided by the user).

=== Step 7: Object & Advanced Relationships ===
Type:
* Custom Content Entities
* Role-based relationships

----

== Asset Lifecycle & Collaboration Workflow ==

=== Roles (conceptual) ===
* '''Ingestor'''
** uploads files
** assigns minimal context
* '''Enricher'''
** adds metadata
** validates data

One person may have multiple roles.

----

=== Lifecycle States ===
* Newly added
* In progress
* Reviewed
* Complete

States describe maturity, not publication.

----

== Dashboard Design Pattern ==

For Chapter, Place, Organisation:
* single dashboard page
* table of existing records
* add/edit via simple forms

Status: done

For Assets:
* add asset always visible
* recent assets list
* guided asset discovery
* no massive tables

Status: Done,
Refining realised dealing with massive amounts of assets: using a combined field filter.

----

== Help & Guidance Strategy ==

Help must be:
* contextual
* non-intrusive
* always available

Mechanisms:
* field descriptions
* ℹ️ icons (difficult in Drupal - placeholders may help here)
* collapsible help sections
* TBD?: link to MediaWiki Reasearch namespace for extended documentation and system philosophy desccription

----

== Automation & Logic ==

Automation is handled via:
* Drupal configuration and extra available modules
* Custom modules if really necessary, and simplifying a lot the implementation
* take care: using drupal 11.3 - based on new (OO) concepts - needs special attention in building custom modules

Automation is used to:
* generate identifiers
* manage asset counters
* enforce immutability rules
* reduce cognitive load

Automation must never obscure what happens.

----

== Design Discipline Rules ==

* No authority entity is implemented as editorial content
* No field is required unless it enables a mechanism
* No output system becomes authoritative
* No UX decision is optimized for power users
* Stability is more important than elegance

----

== Usage in AI Sessions ==

This document must be:
* pasted or referenced at the start of new AI-assisted sessions
* treated as authoritative context
* updated only when architectural decisions change and progress is made

AI output must conform to this blueprint.

== AI Session protocol ==
* no hurry - simple step by simple step: AI proposes, sysop executes finishing with ACK
* no long explanations and justifications - sysop will ask for if needed.
* making the requirement work is the most important step, sysop will documenent once a milestone is achieved.
* AI will suggest a synthesis in mediawikitext format on sysop request to feed the documentation

----

== Supplement — UI Theming, Accessibility & Visual Discipline ==

This supplement records explicit requirements related to visual theming, accessibility, and user comfort that were clarified after initial project restart.
These requirements are binding and must be respected in all future design and implementation decisions.

----

=== Separation of UI Concerns ===

The system UI is explicitly divided into two independent domains:

* '''Administrative / Dashboard UI''' (authenticated users)
* '''Public Presentation UI''' (anonymous visitors)

No design, theme, or UX decision in one domain is allowed to negatively affect the other.

Decisions:
* GIN skin is used for administration and user input in mandatory DARK mode.
* SOLO skin is used for public pages.

----

=== Administrative & Dashboard UI (Authenticated Users) ===

==== Target Users ====
* System administrator (username: '''mngr''')
* Club members and contributors (e.g. '''testuser''')
* Age profile: 70+
* Long working sessions expected

==== Mandatory Requirements ====
* '''Permanent dark mode''' is used via the GIN skin/template
* Preferred no custom CSS or hacks

==== Scope ====
* Applies to:
** content ingestion
** asset enrichment
** review workflows
** dashboards
* Applies equally to administrators and non-technical contributors

==== Design Discipline ====
* Accessibility and eye comfort take precedence over aesthetics
* The administrative UI must remain:
** predictable
** low-contrast-stress
** uncluttered

----

=== Public Presentation UI (Anonymous Users) ===

==== Audience ====
* General public
* Researchers
* Visitors with unknown accessibility needs

==== Mandatory Requirements ====
* Public-facing theme must be:
** modern
** responsive / adaptive
** suitable for long-term institutional use

DECISION: SOLO skin/template has been choosen for dealing with these requirements

----

=== Timing & Implementation Rules ====

* Public-facing theming is explicitly deferred until:
** asset logic is validated
** authoritative entities are stable
* Early decisions must not constrain future design exploration, but must enforce:
** accessibility
** adaptability
** long-term maintainability

----

=== Stability Principle (UI) ====

* UI comfort is a prerequisite for correct decision-making
* Visual strain increases error rates and architectural drift
* Therefore:
** administrative UI comfort is non-negotiable
** public UI adaptability is mandatory

=== Naming conventions - Design discipline ===
All attributes in an entity will have the first 2 letters of the entity as prefix in the Drupal machine name.
Example: Chapter
field "Start Year" - machine name: ch_startyear internal storage name: field_ch_startyear
field "Description" - ch_description -- field_ch_description

Due to limitation in Drupal concerning the Data and Time widget, a plain text field is used for "day"..
A custom module checks the format DD/MM/YYY and the field is limited to 10 chars, explanation about the format including also a placemarker with the format. The machine field name should end on "_day".

== Implementation Status - March 23th 2026) ==

Entities implemented:

* Chapter
* Place
* Organisation
* Asset (basic structure)
* Person
* Object

All entities include:
* dashboards via Views
* edit workflow via dashboard
* recursive relationships where required
* FK implemented
* entity references verified

== End of Blueprint ==

== Appendix - 1: Data Model -

<pre>
// =====================================================
// Costasano Heritage Database Model — v5.0
// =====================================================

// ==== HERITAGE OBJECTS ====

Table Object {
Code string [pk]
Parent string [ref: > Object.Code]
Name string
Type string
Subtype string
Place string [ref: > Place.Code]
DateFrom date
DateTo date
Description text
Notes text
}

// ==== DIGITAL ASSETS ====

Table Asset {
Caption string
Code string [pk]
Chapter string [ref: > Chapter.Code]
Place string [ref: > Place.Code]
Organisation string [ref: > Organisation.Code]
Sequence int
MediaFile string [ref: > Files.id]
Parent string [ref: > Asset.Code]
AssetSourceType string [ref: > AssetSourceType.Code]
AssetType string [ref: > AssetType.Code]
SourceReference string
Description text
Notes text
AiProcessed boolean
Citation text
Permalink string
Repository string
Rights string
IsPublishable boolean
}

// ==== EXTERNAL DRUPAL FILES ====

Table Files {
id string [pk]
Label string
Timestamp datetime
User string
Comment text
Size int
Sha1 string
Mime string
Url string
}

// ==== RESEARCH ENTITIES ====

Table Person {
Code string [pk]
FirstName string
LastName string
BirthDate date
DeathDate date
Biography text
Contact text
Notes text
}

Table Organisation {
Code string [pk]
Name string
Place string [ref: > Place.Code]
Description text
Contact text
Notes text
}

Table Place {
Code string [pk]
Parent string [ref: > Place.Code]
Label string
Type string
Latitude float
Longitude float
Description text
Notes text
}

Table Chapter {
Code string [pk]
Description string
Parent string [ref: > Chapter.Code]
StartYear integer
EndYear integer
Notes text
}

// ==== LOOKUP TABLES ====

Table ObjectType {
Code string [pk]
Description text
}

Table AssetSourceType {
Code string [pk]
Label string
Description text
}

Table AssetType {
Code string [pk]
Name string
Description text
}

Table AssetRole {
Code string [pk]
Name string
Description text
}

Table PersonRole {
Code string [pk]
Name string
Description text
}

Table OrganisationRole {
Code string [pk]
Name string
Description text
}

Table Keywords {
Code string [pk]
Name string
Description text
}

// ==== RELATIONSHIP TABLES (Junctions) ====

Table ObjectAsset {
id string [pk]
Object string [ref: > Object.Code]
Asset string [ref: > Asset.Code]
Role string [ref: > AssetRole.Code]
IsPreferred boolean
}

Table PersonAsset {
id string [pk]
Person string [ref: > Person.Code]
Asset string [ref: > Asset.Code]
}

Table OrganisationAsset {
id string [pk]
Organisation string [ref: > Organisation.Code]
Asset string [ref: > Asset.Code]
}

Table OjectChapter {
id string [pk]
Object string [ref: > Object.Code]
Chapter string [ref: > Chapter.Code]
}

Table ObjectPerson {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Role string [ref: > PersonRole.Code]
}

Table ObjectOrganisation {
id string [pk]
Object string [ref: > Object.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table PersonOrganisationRole {
id string [pk]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table ObjectKeyword {
id string [pk]
Object string [ref: > Object.Code]
Keyword string [ref: > Keywords.Code]
}

Table ObjectHolder {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
}
</pre>

= Appendix - 2: Modules already enabled in our Drupal 11 configuration - version 20260319 ==

<pre>
mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
---------------- ----------------------------------------------------------------------- --------- ----------
Package Name Status Version
---------------- ----------------------------------------------------------------------- --------- ----------
Core Announcements (announcements_feed) Enabled 11.3.5
Core Automated Cron (automated_cron) Enabled 11.3.5
Core BigPipe (big_pipe) Enabled 11.3.5
Core Block (block) Enabled 11.3.5
Core Block Content (block_content) Enabled 11.3.5
Core Breakpoint (breakpoint) Enabled 11.3.5
Core CKEditor 5 (ckeditor5) Enabled 11.3.5
Core Comment (comment) Enabled 11.3.5
Core Configuration Manager (config) Enabled 11.3.5
Core Contact (contact) Enabled 11.3.5
Core Contextual Links (contextual) Enabled 11.3.5
Field types Datetime (datetime) Enabled 11.3.5
Field types Datetime Range (datetime_range) Enabled 11.3.5
Core Database Logging (dblog) Enabled 11.3.5
Core Internal Dynamic Page Cache (dynamic_page_cache) Enabled 11.3.5
Core Text Editor (editor) Enabled 11.3.5
Core Field (field) Enabled 11.3.5
Core Field UI (field_ui) Enabled 11.3.5
Field types File (file) Enabled 11.3.5
Core Filter (filter) Enabled 11.3.5
Core Help (help) Enabled 11.3.5
Core History (history) Enabled 11.3.5
Field types Image (image) Enabled 11.3.5
Core Inline Form Errors (inline_form_errors) Enabled 11.3.5
Core Layout Builder (layout_builder) Enabled 11.3.5
Core Layout Discovery (layout_discovery) Enabled 11.3.5
Field types Link (link) Enabled 11.3.5
Core Media (media) Enabled 11.3.5
Core Media Library (media_library) Enabled 11.3.5
Core Custom Menu Links (menu_link_content) Enabled 11.3.5
Core Menu UI (menu_ui) Enabled 11.3.5
Core MySQL (mysql) Enabled 11.3.5
Core Node (node) Enabled 11.3.5
Field types Options (options) Enabled 11.3.5
Core Internal Page Cache (page_cache) Enabled 11.3.5
Core Path (path) Enabled 11.3.5
Core Path alias (path_alias) Enabled 11.3.5
Core Responsive Image (responsive_image) Enabled 11.3.5
Core Search (search) Enabled 11.3.5
Core Shortcut (shortcut) Enabled 11.3.5
Core System (system) Enabled 11.3.5
Core Taxonomy (taxonomy) Enabled 11.3.5
Field types Text (text) Enabled 11.3.5
Core Toolbar (toolbar) Enabled 11.3.5
Core Update Status (update) Enabled 11.3.5
Core User (user) Enabled 11.3.5
Core Views (views) Enabled 11.3.5
Core Views UI (views_ui) Enabled 11.3.5
Core Workspaces (workspaces) Enabled 11.3.5
Core Workspaces UI (workspaces_ui) Enabled 11.3.5
Field types Address (address) Enabled 2.0.4
Development Asset Injector (asset_injector) Enabled 8.x-2.21
Field types Color Field (color_field) Enabled 3.0.2
Other Computed Field (computed_field) Enabled 4.0.0
Other Contact Formatter (contact_formatter) Enabled 2.0.4
Core Dashboard (dashboard) Enabled 2.2.0
Field types Entity Reference Revisions (entity_reference_revisions) Enabled 8.x-1.14
Fields Field Group (field_group) Enabled 4.0.0
File metadata File metadata manager (file_mdm) Enabled 3.2.0
File metadata File metadata - EXIF (file_mdm_exif) Enabled 3.2.0
File metadata File metadata - Font (file_mdm_font) Enabled 3.2.0
Geocoding Geocoder (geocoder) Enabled 8.x-4.31
Geocoding Geocoder Address (geocoder_address) Enabled 8.x-4.31
Geocoding Geocoder Field (geocoder_field) Enabled 8.x-4.31
Geocoding Geocoder Geofield (geocoder_geofield) Enabled 8.x-4.31
Geofield Geofield (geofield) Enabled 10.3.4
Geolocation Geolocation (geolocation) Enabled 8.x-3.14
Geolocation Geolocation - Address (geolocation_address) Enabled 8.x-3.14
Geolocation Geolocation - Baidu Maps (geolocation_baidu) Enabled 8.x-3.14
Geolocation Geolocation - Here Maps (geolocation_here) Enabled 8.x-3.14
Geolocation Geolocation - Leaflet (geolocation_leaflet) Enabled 8.x-3.14
Other Gin Toolbar (gin_toolbar) Enabled 3.0.3
Media Image Effects (image_effects) Enabled 5.0.0
Media ImageMagick (imagemagick) Enabled 5.0.1
jQuery UI jQuery UI (jquery_ui) Enabled 8.x-1.8
jQuery UI jQuery UI Autocomplete (jquery_ui_autocomplete) Enabled 2.1.0
jQuery UI jQuery UI Menu (jquery_ui_menu) Enabled 2.1.0
User interface Klaro Cookie & Consent Manager (klaro) Enabled 3.0.8
Geofield Leaflet (leaflet) Enabled 10.4.4
Geofield Leaflet Markercluster (leaflet_markercluster) Enabled 10.4.4
Geofield Leaflet Views (leaflet_views) Enabled 10.4.4
User interface Linkit (linkit) Enabled 7.0.13
Other Media Library Form Element (media_library_form_element) Enabled 2.1.4
Paragraphs Paragraphs Type Permissions (paragraphs_type_permissions) Enabled 8.x-1.20
Paragraphs Paragraphs (paragraphs) Enabled 8.x-1.20
Paragraphs Paragraph Bundle 3D Carousel (paragraph_bundle_3d_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle 3D Flip Box (paragraph_bundle_3d_flip_box) Enabled 1.0.16
Paragraphs Paragraph Bundle Accordion (paragraph_bundle_accordion) Enabled 1.0.16
Paragraphs Paragraph Bundle Alert (paragraph_bundle_alert) Enabled 1.0.16
Paragraphs Paragraph Bundle Block (paragraph_bundle_block) Enabled 1.0.16
Paragraphs Paragraph Bundle Block Content (paragraph_bundle_block_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Card (paragraph_bundle_card) Enabled 1.0.16
Paragraphs Paragraph Bundle Carousel (paragraph_bundle_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle Contact Form (paragraph_bundle_contact_form) Enabled 1.0.16
Paragraphs Paragraph Bundle Content (paragraph_bundle_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Grid (paragraph_bundle_grid) Enabled 1.0.16
Paragraphs Paragraph Bundle Hero (paragraph_bundle_hero) Enabled 1.0.16
Paragraphs Paragraph Bundle Icon (paragraph_bundle_icon) Enabled 1.0.16
Paragraphs Paragraph Bundle Image (paragraph_bundle_image) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Background (paragraph_bundle_image_background) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Grid (Image Gallery - Lightbox) Enabled 1.0.16
(paragraph_bundle_image_grid)
Paragraphs Paragraph Bundle Image Overlay (paragraph_bundle_image_overlay) Enabled 1.0.16
Paragraphs Paragraph Bundle Layout (paragraph_bundle_layout) Enabled 1.0.16
Paragraphs Paragraph Bundle Modal (paragraph_bundle_modal) Enabled 1.0.16
Paragraphs Paragraph Bundle Node Reference (paragraph_bundle_node_reference) Enabled 1.0.16
Paragraphs Paragraph Bundle Parallax (paragraph_bundle_parallax) Enabled 1.0.16
Paragraphs Paragraph Bundle Slideshow (paragraph_bundle_slideshow) Enabled 1.0.16
Paragraphs Paragraph Bundle Tabs (paragraph_bundle_tabs) Enabled 1.0.16
Paragraphs Paragraphs Bundles (paragraphs_bundles) Enabled 1.0.16
Mail SMTP Authentication Support (smtp) Enabled 8.x-1.4
Solo Suite Solo Utilities (solo_utilities) Enabled 1.0.6
Other Sophron (sophron) Enabled 3.1.0
Media SVG Image Responsive (svg_image_responsive) Enabled 3.2.2
Media SVG image (svg_image) Enabled 3.2.2
Costasano Costasano Asset (costasano_asset) Enabled
Heritage Heritage Codes (heritage_codes) Enabled 1.0.0
Heritage Heritage Tweaks (heritage_tweaks) Enabled
Core Claro (claro) Enabled 11.3.5
Core Olivero (olivero) Enabled 11.3.5
Gin (gin) Enabled 5.0.12
Solo Solo (solo) Enabled 1.0.31
---------------- ----------------------------------------------------------------------- --------- ----------
</pre>

ICT:Drupal Blueprint - Version 6.5

2026-03-23T10:25:23Z

Mngr:

= Costasano Heritage Project — Drupal 11 Architecture & Workflow Blueprint (v6.5) =

== Purpose of this Document ==
This page defines the architectural, conceptual, and workflow foundations of the Costasano Heritage Project.

It serves as:
* a stable reference for human contributors
* a briefing document for AI-assisted work sessions
* a safeguard against context loss over long-term development

All future design, implementation, and automation decisions must be compatible with the principles defined here.

----

== Project Overview ==

The Costasano Heritage Project is a long-term digital heritage initiative operated by members of the Costa Sano Club (70+ years old, amateur historians, non-ICT specialists, except for Martin, realising the IT-project, also amateur historian).

The project manages:
* hundreds of gigabytes of documents, images, and maps
* collaborative historical research
* multi-channel dissemination (wiki, public website, exhibitions, video)

The system is designed for '''decades-long durability''', not short-term publication.

----

== Core Philosophy ==

=== Authoritative Source Principle ===
There is exactly ONE authoritative system for data and assets:
* '''Drupal 11.3'''

All other outputs (MediaWiki, public website, video, exhibitions) are derivatives.

No downstream system is allowed to correct, invent, or override facts.
All corrections must return to Drupal.

----

=== Asset-Centric Design ===
The central object of the entire system is:

'''Asset + File (ONE asset = ONE file)'''

Everything else (chapter, place, organisation) exists to:
* contextualize assets
* classify assets
* generate stable identifiers
* reuse assets across outputs
* chapters provide a sort of timeline

----

=== Ingest First, Enrich Later ===
The system must allow:
* rapid bulk ingestion of files with minimal metadata
* gradual collaborative enrichment over time
* clear lifecycle states without pressure for completeness

Completeness is a process, not a prerequisite.

----

== Target Users & UX Constraints ==

=== User Profile ===
* Age: 70+
* Background: amateur historians
* ICT skills: minimal
* Tolerance for complexity: low

=== UX Non-Negotiables ===
* No technical terminology exposed (no “entity”, “taxonomy”, “foreign key”)
* No cluttered forms
* Dashboard-first and only navigation
* Large click targets
* Predictable layouts
* Dark mode mandatory (accessibility)

Users must never feel they are “using Drupal”.

----

== System Architecture ==

=== Infrastructure ===
* Reverse Proxy: Windows Server (IIS + ARR, SSL offloading)
* Web Server: AlmaLinux 10.1 (Apache 2.4.63, PHP 8.3.29, PHP-FPM)
* Database Server: AlmaLinux 10.1 (MariaDB 10.11.15)
* Drupal 11.3.5
* SELinux: Enforcing
* PHP-FPM: Per-site pools
* Filesystem: Hardened

=== Operational Constants ===
* '''Site URL''': https://research.costasano.club
* '''Drupal project root''': /var/www/drupal
* '''Drupal web root''': /var/www/drupal/web

----

== Output Channels ==

=== 1. MediaWiki (Research & Writing) ===
Role:
* illustrated research pages
* collaborative narrative writing
* preparation for Wikipedia publication

MediaWiki does NOT:
* store authoritative metadata
* manage files
* generate identifiers

----

=== 2. Public Drupal Website ===
Role:
* curated presentation of selected research
* timelines, maps, galleries

Only “complete” or approved assets are shown publicly.

----

=== 3. Offline Outputs ===
* video documentaries
* lectures
* exhibitions

These reuse:
* the same assets
* the same identifiers
* the same metadata

----

== Authority Entity Implementation Strategy ==

Authority entities are implemented progressively, from simplest to most complex.
This order is mandatory.

----

=== Step 1: Chapter (Temporal Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Meaning:
* historical periods / timeline segmentation
* not editorial or narrative content

Characteristics:
* stable Code (max 6 characters) like CHxx.ab CH01, CH01a, CH01aa, CH01ab
* recursive (parent/child) two levels using small letters after the first four
* stable Code (max 6 characters)
* used as first mandatory component in asset identifiers
* no sequence field

Dashboard pattern:
* table of existing records
* add new record
* click pencil in front of row to edit

Status: Drupal Context Type and Dashboard page operational
Changed decision about chapter code layout
ToDo (max 6 characters)
* Address field for geocoding
* coordinates auto-derived when possible
* coordinates never required for ingestion

Purpose:
* spatial context
* optionally reused across assets for numbering reasoons
* reused for organisations

Status: Drupal Context Type and Dashboard page operational
Recently added: type list, geo link in view towards openstreetmap
Added view adapted to type.
Address to coordinates implemented using Openstreatmap providers.
ToDo:Completing helpfunctions

----

=== Step 3: Organisation (Institutional Authority) ===
Type:
* '''Drupal Custom Content Entity (authority)'''

Characteristics:
* stable Code (max 6 characters)
* linked to a Place
* optionally reused across assets for numbering

Purpose:
* institutional context
* archival provenance

Status: Drupal Context Type and Dashboard page operational
ToDo: adding map view based on Place coordinnates now that provider is available
Completing help functions

----

=== Step 4: Asset (CORE ENTITY) ===
Type:
* '''Drupal Custom Content Entity'''

Rules:
* ONE asset = ONE file
* file is immutable once uploaded
* identifier is immutable once generated
* physical filenames are managed by Drupal
* original filename is preserved for user reference

Identifier format:
* Chapter.Code
* Context.Code = Place.Code OR Organisation.Code
* Scoped 5-digit counter (asset sequence only)

Example:
<pre>
CH03ab-OOSTEN-00007
</pre>

Asset creation is impossible before Chapter, Place, and Organisation exist.

Status: Drupal Context Type and View complete
Use of special configuration of classic Media-Library for media upload.
Upload of images, documents, video and audio foreseen
Automatic numbering for asset via a custom module
Creation in 2 steps: first essential fields to generate autonumbering.
After that, use of editing via table to fill un further fields like description and note.
Optional change of other fields except autocode.
View enhanced with search filter.
ToDo: complete help functions
Remark: Inital configuration with Code as PK (Drupal Title) has been abandoned.
Now Code is a classic field and the Title field is a Caption field. This is a short description of the file.

== Next Major step: HeritageObject and Person ==

Now that Chapter, Place, Organisation and Asset are stable it is time for a next major step.
HeritageObject, Drupal called Object, is the next challenge due to the fact it has a many to many relationship with Asset,
is recursive and also linked to a serious number of other entities. One of these is Person, not yet prepared for. This will be the first next step.

=== Step 5: Person implementation ===

A '''Person''' represents a historical individual with agency.

It answers the question:

''“Who was involved historically?”''

A person is:

* religious sisters
* directors
* architects
* patients
* shareholders
* board members

A Person may:

* play roles in relation to HeritageObjects
* play roles within Organizations
* act as a holder of HeritageObjects
* be documented by DigitalAssets (portraits, letters, biographies, articles)

Roles belong to relationships, not to the Person entity itself.

Purpose: Persons model historical agency, responsibility, and participation.

Implementation:
- automatic numbering of Person entities realized with custom module: PE-00123
- use for plain text for birthday and deathday due to drupal limitation in Date & Time widget
- use of custom module to verify the day format DD/MM/YYYY
- both modules are implemented in heritage-tweaks
- first view operational
ToDo: Nihil for time being

=== Step 6: HeritageObject implementation ===
The implementation of HeritageObject abbreviated Object in Drupal

A '''HeritageObject (HO)''' represents a historical, conceptual, or material entity that is the subject of study.

It answers the question:

''“What is the thing we are studying?”''

A HeritageObject may represent:

* a sanatorium
* a building
* a document or register
* a historically meaningful place
* a room, component, or architectural element
* a conceptual or functional unit (e.g. “medical practice”)

HeritageObjects are '''recursive'''.

Each HeritageObject may:

* have zero or one parent HeritageObject
* have zero or more child HeritageObjects

A HeritageObject may:

* be documented by multiple DigitalAssets
* designate one DigitalAsset as preferred representation
* be linked to Persons with roles
* be linked to Organizations with roles
* have Persons or Organizations as holders
* belong to multiple ResearchChapters
* be tagged with Keywords
* be associated with one or more Places

Purpose: HeritageObjects are the primary conceptual anchors of the research.

Implementation:
- automatic numbering of object entity: OB-00123
- Onject is recursive

ToDO
- implementation of a many to many relationship between Object and Asset
- One digital Asset is a prefered Asset only for illustration purposes of the Object in a view
- Notion of top" Asset in the asset structure is the Asset without parent to by used in the many-to-many relationship. This top asset gives also access to the full tree of assets linked to that top. That top may change in the lifetime of the asset-tree (decided by the user).

=== Step 7: Object & Advanced Relationships ===
Type:
* Custom Content Entities
* Role-based relationships

----

== Asset Lifecycle & Collaboration Workflow ==

=== Roles (conceptual) ===
* '''Ingestor'''
** uploads files
** assigns minimal context
* '''Enricher'''
** adds metadata
** validates data

One person may have multiple roles.

----

=== Lifecycle States ===
* Newly added
* In progress
* Reviewed
* Complete

States describe maturity, not publication.

----

== Dashboard Design Pattern ==

For Chapter, Place, Organisation:
* single dashboard page
* table of existing records
* add/edit via simple forms

Status: done

For Assets:
* add asset always visible
* recent assets list
* guided asset discovery
* no massive tables

Status: Done, but some refining necessary to deal with massive amounts of assets.

----

== Help & Guidance Strategy ==

Help must be:
* contextual
* non-intrusive
* always available

Mechanisms:
* field descriptions
* ℹ️ icons
* collapsible help sections

No separate manuals.

----

== Automation & Logic ==

Automation is handled via:
* Drupal configuration
* Custom module

Status: DONE but some refinements might be needed

Automation is used to:
* generate identifiers
* manage asset counters
* enforce immutability rules
* reduce cognitive load

Automation must never obscure what happens.

----

== Design Discipline Rules ==

* No authority entity is implemented as editorial content
* No field is required unless it enables a mechanism
* No output system becomes authoritative
* No UX decision is optimized for power users
* Stability is more important than elegance

----

== Usage in AI Sessions ==

This document must be:
* pasted or referenced at the start of new AI-assisted sessions
* treated as authoritative context
* updated only when architectural decisions change and progress is made

AI output must conform to this blueprint.

== AI Session protocol ==
* no hurry - simple step by simple step: AI proposes, sysop executes finishing with ACK
* no long explanations and justifications - sysop will ask for if needed.
* making the requirement work is the most important step, sysop will documenent once a milestone is achieved.
* AI will suggest a synthesis in mediawikitext format on sysop request to feed the documentation

----

== Supplement — UI Theming, Accessibility & Visual Discipline ==

This supplement records explicit requirements related to visual theming, accessibility, and user comfort that were clarified after initial project restart.
These requirements are binding and must be respected in all future design and implementation decisions.

----

=== Separation of UI Concerns ===

The system UI is explicitly divided into two independent domains:

* '''Administrative / Dashboard UI''' (authenticated users)
* '''Public Presentation UI''' (anonymous visitors)

No design, theme, or UX decision in one domain is allowed to negatively affect the other.

Decisions:
* GIN skin is used for administration and user input in mandatory DARK mode.
] SOLO skin is used for public pages.

----

=== Administrative & Dashboard UI (Authenticated Users) ===

==== Target Users ====
* System administrator (username: '''mngr''')
* Club members and contributors (e.g. '''testuser''')
* Age profile: 70+
* Long working sessions expected

==== Mandatory Requirements ====
* '''Permanent dark mode''' is used via the GIN skin/template
* No custom CSS or hacks

==== Scope ====
* Applies to:
** content ingestion
** asset enrichment
** review workflows
** dashboards
* Applies equally to administrators and non-technical contributors

==== Design Discipline ====
* Accessibility and eye comfort take precedence over aesthetics
* The administrative UI must remain:
** predictable
** low-contrast-stress
** uncluttered
* No experimental or unstable admin themes are permitted

----

=== Public Presentation UI (Anonymous Users) ===

==== Audience ====
* General public
* Researchers
* Visitors with unknown accessibility needs

==== Mandatory Requirements ====
* Public-facing theme must be:
** modern
** responsive / adaptive
** suitable for long-term institutional use

DECISION: SOLO skin/template has been choosen for dealing with these requirements

----

=== Timing & Implementation Rules ====

* Public-facing theming is explicitly deferred until:
** asset logic is validated
** authoritative entities are stable
* Early decisions must not constrain future design exploration, but must enforce:
** accessibility
** adaptability
** long-term maintainability

----

=== Stability Principle (UI) ====

* UI comfort is a prerequisite for correct decision-making
* Visual strain increases error rates and architectural drift
* Therefore:
** administrative UI comfort is non-negotiable
** public UI adaptability is mandatory

=== Naming conventions - Design discipline ===
All attributes in an entity will have the first 2 letters of the entity as prefix in the Drupal machine name.
Example: Chapter
field "Start Year" - machine name: ch_startyear internal storage name: field_ch_startyear
field "Description" - ch_description -- field_ch_description

== Implementation Status - March 7th 2026) ==

Entities implemented:

* Chapter
* Place
* Organisation
* Asset (basic structure)

All entities include:
* dashboards via Views
* edit workflow via dashboard
* recursive relationships where required
* FK implemented where required
* entity references verified

Automation for DigitalAsset identifiers is not yet implemented.

== End of Blueprint ==

== Appendix - 1: Data Model -

<pre>
// =====================================================
// Costasano Heritage Database Model — v5.0
// =====================================================

// ==== HERITAGE OBJECTS ====

Table Object {
Code string [pk]
Parent string [ref: > Object.Code]
Name string
Type string
Subtype string
Place string [ref: > Place.Code]
DateFrom date
DateTo date
Description text
Notes text
}

// ==== DIGITAL ASSETS ====

Table Asset {
Caption string
Code string [pk]
Chapter string [ref: > Chapter.Code]
Place string [ref: > Place.Code]
Organisation string [ref: > Organisation.Code]
Sequence int
MediaFile string [ref: > Files.id]
Parent string [ref: > Asset.Code]
AssetSourceType string [ref: > AssetSourceType.Code]
AssetType string [ref: > AssetType.Code]
SourceReference string
Description text
Notes text
AiProcessed boolean
Citation text
Permalink string
Repository string
Rights string
IsPublishable boolean
}

// ==== EXTERNAL DRUPAL FILES ====

Table Files {
id string [pk]
Label string
Timestamp datetime
User string
Comment text
Size int
Sha1 string
Mime string
Url string
}

// ==== RESEARCH ENTITIES ====

Table Person {
Code string [pk]
FirstName string
LastName string
BirthDate date
DeathDate date
Biography text
Contact text
Notes text
}

Table Organisation {
Code string [pk]
Name string
Place string [ref: > Place.Code]
Description text
Contact text
Notes text
}

Table Place {
Code string [pk]
Parent string [ref: > Place.Code]
Label string
Type string
Latitude float
Longitude float
Description text
Notes text
}

Table Chapter {
Code string [pk]
Description string
Parent string [ref: > Chapter.Code]
StartYear integer
EndYear integer
Notes text
}

// ==== LOOKUP TABLES ====

Table ObjectType {
Code string [pk]
Description text
}

Table AssetSourceType {
Code string [pk]
Label string
Description text
}

Table AssetType {
Code string [pk]
Name string
Description text
}

Table AssetRole {
Code string [pk]
Name string
Description text
}

Table PersonRole {
Code string [pk]
Name string
Description text
}

Table OrganisationRole {
Code string [pk]
Name string
Description text
}

Table Keywords {
Code string [pk]
Name string
Description text
}

// ==== RELATIONSHIP TABLES (Junctions) ====

Table ObjectAsset {
id string [pk]
Object string [ref: > Object.Code]
Asset string [ref: > Asset.Code]
Role string [ref: > AssetRole.Code]
IsPreferred boolean
}

Table PersonAsset {
id string [pk]
Person string [ref: > Person.Code]
Asset string [ref: > Asset.Code]
}

Table OrganisationAsset {
id string [pk]
Organisation string [ref: > Organisation.Code]
Asset string [ref: > Asset.Code]
}

Table OjectChapter {
id string [pk]
Object string [ref: > Object.Code]
Chapter string [ref: > Chapter.Code]
}

Table ObjectPerson {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Role string [ref: > PersonRole.Code]
}

Table ObjectOrganisation {
id string [pk]
Object string [ref: > Object.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table PersonOrganisationRole {
id string [pk]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
Role string [ref: > OrganisationRole.Code]
}

Table ObjectKeyword {
id string [pk]
Object string [ref: > Object.Code]
Keyword string [ref: > Keywords.Code]
}

Table ObjectHolder {
id string [pk]
Object string [ref: > Object.Code]
Person string [ref: > Person.Code]
Organisation string [ref: > Organisation.Code]
}

</pre>

= Appendix - 2: Lessons learned on feb 27 2026 =

This session ended in with Drupal in an undetermined stated due to a misunderstanding about the requirements, and then finally a problem wrongly using a Drupal reserved word DASHBOARD.

Restart from scratch after that day, restoring of the full virtual disks for both machines dated 26 feb.

Conclusion of the day were chatgpt promises for restarting.

Tomorrow I will:

* avoid cleverness
* avoid custom routing early
* avoid reserved names
* rely on Drupal defaults first
* reduce bash steps to the minimum stop earlier when entropy appears

Agreement: You bring architectural clarity. I bring Drupal-specific caution. That’s a workable division.

== Important AI protocal ==
After the agreement an a workflow, we work step by step, no hurry. AI proposes a step, I execute and report back the result and then only we go for the next step. Too much explanation is NOT needed, as I am a novice in this field. After 50+ years in ICT, I understand mostly what the steps do and if not, I will ask for. This should permit for a slow but steady flow towards the endgoal of the session.

= Appendix - 4: Modules already enabled in our Drupal 11 configuration - version 20260319 ==

<pre>
mngr@localhost:/var/www/drupal$ drush pm:list --status=enabled
---------------- ----------------------------------------------------------------------- --------- ----------
Package Name Status Version
---------------- ----------------------------------------------------------------------- --------- ----------
Core Announcements (announcements_feed) Enabled 11.3.5
Core Automated Cron (automated_cron) Enabled 11.3.5
Core BigPipe (big_pipe) Enabled 11.3.5
Core Block (block) Enabled 11.3.5
Core Block Content (block_content) Enabled 11.3.5
Core Breakpoint (breakpoint) Enabled 11.3.5
Core CKEditor 5 (ckeditor5) Enabled 11.3.5
Core Comment (comment) Enabled 11.3.5
Core Configuration Manager (config) Enabled 11.3.5
Core Contact (contact) Enabled 11.3.5
Core Contextual Links (contextual) Enabled 11.3.5
Field types Datetime (datetime) Enabled 11.3.5
Field types Datetime Range (datetime_range) Enabled 11.3.5
Core Database Logging (dblog) Enabled 11.3.5
Core Internal Dynamic Page Cache (dynamic_page_cache) Enabled 11.3.5
Core Text Editor (editor) Enabled 11.3.5
Core Field (field) Enabled 11.3.5
Core Field UI (field_ui) Enabled 11.3.5
Field types File (file) Enabled 11.3.5
Core Filter (filter) Enabled 11.3.5
Core Help (help) Enabled 11.3.5
Core History (history) Enabled 11.3.5
Field types Image (image) Enabled 11.3.5
Core Inline Form Errors (inline_form_errors) Enabled 11.3.5
Core Layout Builder (layout_builder) Enabled 11.3.5
Core Layout Discovery (layout_discovery) Enabled 11.3.5
Field types Link (link) Enabled 11.3.5
Core Media (media) Enabled 11.3.5
Core Media Library (media_library) Enabled 11.3.5
Core Custom Menu Links (menu_link_content) Enabled 11.3.5
Core Menu UI (menu_ui) Enabled 11.3.5
Core MySQL (mysql) Enabled 11.3.5
Core Node (node) Enabled 11.3.5
Field types Options (options) Enabled 11.3.5
Core Internal Page Cache (page_cache) Enabled 11.3.5
Core Path (path) Enabled 11.3.5
Core Path alias (path_alias) Enabled 11.3.5
Core Responsive Image (responsive_image) Enabled 11.3.5
Core Search (search) Enabled 11.3.5
Core Shortcut (shortcut) Enabled 11.3.5
Core System (system) Enabled 11.3.5
Core Taxonomy (taxonomy) Enabled 11.3.5
Field types Text (text) Enabled 11.3.5
Core Toolbar (toolbar) Enabled 11.3.5
Core Update Status (update) Enabled 11.3.5
Core User (user) Enabled 11.3.5
Core Views (views) Enabled 11.3.5
Core Views UI (views_ui) Enabled 11.3.5
Core Workspaces (workspaces) Enabled 11.3.5
Core Workspaces UI (workspaces_ui) Enabled 11.3.5
Field types Address (address) Enabled 2.0.4
Development Asset Injector (asset_injector) Enabled 8.x-2.21
Field types Color Field (color_field) Enabled 3.0.2
Other Computed Field (computed_field) Enabled 4.0.0
Other Contact Formatter (contact_formatter) Enabled 2.0.4
Core Dashboard (dashboard) Enabled 2.2.0
Field types Entity Reference Revisions (entity_reference_revisions) Enabled 8.x-1.14
Fields Field Group (field_group) Enabled 4.0.0
File metadata File metadata manager (file_mdm) Enabled 3.2.0
File metadata File metadata - EXIF (file_mdm_exif) Enabled 3.2.0
File metadata File metadata - Font (file_mdm_font) Enabled 3.2.0
Geocoding Geocoder (geocoder) Enabled 8.x-4.31
Geocoding Geocoder Address (geocoder_address) Enabled 8.x-4.31
Geocoding Geocoder Field (geocoder_field) Enabled 8.x-4.31
Geocoding Geocoder Geofield (geocoder_geofield) Enabled 8.x-4.31
Geofield Geofield (geofield) Enabled 10.3.4
Geolocation Geolocation (geolocation) Enabled 8.x-3.14
Geolocation Geolocation - Address (geolocation_address) Enabled 8.x-3.14
Geolocation Geolocation - Baidu Maps (geolocation_baidu) Enabled 8.x-3.14
Geolocation Geolocation - Here Maps (geolocation_here) Enabled 8.x-3.14
Geolocation Geolocation - Leaflet (geolocation_leaflet) Enabled 8.x-3.14
Other Gin Toolbar (gin_toolbar) Enabled 3.0.3
Media Image Effects (image_effects) Enabled 5.0.0
Media ImageMagick (imagemagick) Enabled 5.0.1
jQuery UI jQuery UI (jquery_ui) Enabled 8.x-1.8
jQuery UI jQuery UI Autocomplete (jquery_ui_autocomplete) Enabled 2.1.0
jQuery UI jQuery UI Menu (jquery_ui_menu) Enabled 2.1.0
User interface Klaro Cookie & Consent Manager (klaro) Enabled 3.0.8
Geofield Leaflet (leaflet) Enabled 10.4.4
Geofield Leaflet Markercluster (leaflet_markercluster) Enabled 10.4.4
Geofield Leaflet Views (leaflet_views) Enabled 10.4.4
User interface Linkit (linkit) Enabled 7.0.13
Other Media Library Form Element (media_library_form_element) Enabled 2.1.4
Paragraphs Paragraphs Type Permissions (paragraphs_type_permissions) Enabled 8.x-1.20
Paragraphs Paragraphs (paragraphs) Enabled 8.x-1.20
Paragraphs Paragraph Bundle 3D Carousel (paragraph_bundle_3d_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle 3D Flip Box (paragraph_bundle_3d_flip_box) Enabled 1.0.16
Paragraphs Paragraph Bundle Accordion (paragraph_bundle_accordion) Enabled 1.0.16
Paragraphs Paragraph Bundle Alert (paragraph_bundle_alert) Enabled 1.0.16
Paragraphs Paragraph Bundle Block (paragraph_bundle_block) Enabled 1.0.16
Paragraphs Paragraph Bundle Block Content (paragraph_bundle_block_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Card (paragraph_bundle_card) Enabled 1.0.16
Paragraphs Paragraph Bundle Carousel (paragraph_bundle_carousel) Enabled 1.0.16
Paragraphs Paragraph Bundle Contact Form (paragraph_bundle_contact_form) Enabled 1.0.16
Paragraphs Paragraph Bundle Content (paragraph_bundle_content) Enabled 1.0.16
Paragraphs Paragraph Bundle Grid (paragraph_bundle_grid) Enabled 1.0.16
Paragraphs Paragraph Bundle Hero (paragraph_bundle_hero) Enabled 1.0.16
Paragraphs Paragraph Bundle Icon (paragraph_bundle_icon) Enabled 1.0.16
Paragraphs Paragraph Bundle Image (paragraph_bundle_image) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Background (paragraph_bundle_image_background) Enabled 1.0.16
Paragraphs Paragraph Bundle Image Grid (Image Gallery - Lightbox) Enabled 1.0.16
(paragraph_bundle_image_grid)
Paragraphs Paragraph Bundle Image Overlay (paragraph_bundle_image_overlay) Enabled 1.0.16
Paragraphs Paragraph Bundle Layout (paragraph_bundle_layout) Enabled 1.0.16
Paragraphs Paragraph Bundle Modal (paragraph_bundle_modal) Enabled 1.0.16
Paragraphs Paragraph Bundle Node Reference (paragraph_bundle_node_reference) Enabled 1.0.16
Paragraphs Paragraph Bundle Parallax (paragraph_bundle_parallax) Enabled 1.0.16
Paragraphs Paragraph Bundle Slideshow (paragraph_bundle_slideshow) Enabled 1.0.16
Paragraphs Paragraph Bundle Tabs (paragraph_bundle_tabs) Enabled 1.0.16
Paragraphs Paragraphs Bundles (paragraphs_bundles) Enabled 1.0.16
Mail SMTP Authentication Support (smtp) Enabled 8.x-1.4
Solo Suite Solo Utilities (solo_utilities) Enabled 1.0.6
Other Sophron (sophron) Enabled 3.1.0
Media SVG Image Responsive (svg_image_responsive) Enabled 3.2.2
Media SVG image (svg_image) Enabled 3.2.2
Costasano Costasano Asset (costasano_asset) Enabled
Heritage Heritage Codes (heritage_codes) Enabled 1.0.0
Heritage Heritage Tweaks (heritage_tweaks) Enabled
Core Claro (claro) Enabled 11.3.5
Core Olivero (olivero) Enabled 11.3.5
Gin (gin) Enabled 5.0.12
Solo Solo (solo) Enabled 1.0.31
---------------- ----------------------------------------------------------------------- --------- ----------
</pre>