Editing Documentation (section)

= System Architecture =
This chapter provides an overview of the UNITApedia system architecture, highlighting the containerized design, data flows, and interactions between the various services. The architecture ensures scalability, maintainability, and security, while leveraging open-source technologies to facilitate collaboration and data accessibility across the UNITA alliance.

The following considerations shaped the UNITApedia architecture:

* '''Modularity & Scalability'''
** '''Docker''' ensures each service is isolated, easily updated, and can be scaled independently if usage grows.
** Clear separation of roles ([https://unitapedia.univ-unita.eu/strapi/ Strapi] for input, [https://unitapedia.univ-unita.eu/hop/ Apache HOP] for ETL, MediaWiki for output) streamlines development and maintenance.

* '''Open-Source & Extensibility'''
** '''MediaWiki''': Chosen for its mature ecosystem (extensions like [https://www.mediawiki.org/wiki/Extension:Semantic_Media_Wiki Semantic MediaWiki], [https://www.mediawiki.org/wiki/Extension:External_Data External Data], [https://www.mediawiki.org/wiki/Extension:Page_Forms Page Forms]) and robust community support.
** '''PostgreSQL''': Offers advanced query capabilities, reliability, and easy integration with [https://unitapedia.univ-unita.eu/hop/ '''Apache HOP'''].
** '''MinIO''': An open-source, S3-compatible object store that fits seamlessly into containerized deployments.

* '''Security & SSL'''
** '''Nginx-Proxy + ACME Companion''': Provides automated certificate management and secure HTTPS connections, protecting data in transit.
** Role-Based Access: [https://unitapedia.univ-unita.eu/strapi/ Strapi] enforces form-level permissions, while MediaWiki can be configured with namespace-based access for sensitive data.

* '''Data Consistency & Quality'''
** '''Apache HOP ETL''': Ensures data from different sources ([https://unitapedia.univ-unita.eu/strapi/ Strapi], [https://unitapedia.univ-unita.eu/minio/ MinIO] CSVs) is validated, cleaned, and structured before landing in the datamart.
** '''Semantic MediaWiki''':[https://www.mediawiki.org/wiki/Extension:Semantic_Media_Wiki Semantic MediaWiki] allows for structured data definitions and cross-referencing, ensuring consistent reporting across tasks and indicators.

* '''Maintainability & Future Growth'''
** Each service can be updated or replaced with minimal impact on the others, thanks to Docker’s container-based isolation.
** The architecture can accommodate new data sources, additional tasks/indicators, or new alliances with minimal refactoring.


[[File:Global-archi.png|thumb|930px|center|alt=Architecture to represent the solution proposed in the framework of the task 1.2 working's groups.|UNITApedia Global Architecture]]

=== Request Flow ===
# '''User Interaction''': A UNITA Office user or a Task Leader navigates to the UNITApedia URL.  
# '''Nginx-Proxy''': Receives the request over HTTPS and routes it to the appropriate container (MediaWiki, [https://unitapedia.univ-unita.eu/strapi/ Strapi], etc.).  
# '''Data Entry (Strapi)''': If the user is adding new indicator data, the form submission is stored in the [https://unitapedia.univ-unita.eu/strapi/ Strapi] database.  
# '''ETL (Apache HOP)''': On a scheduled or on-demand basis, [https://unitapedia.univ-unita.eu/hop/ Apache HOP] retrieves the new entries from [https://unitapedia.univ-unita.eu/strapi/ Strapi] (or CSV files in [https://unitapedia.univ-unita.eu/minio/ MinIO]), applies transformations, and loads them into the datamart.  
# '''MediaWiki Display''': MediaWiki queries the datamart schema via the [https://www.mediawiki.org/wiki/Extension:External_Data External Data] extension to display up-to-date metrics on wiki pages or dashboards.  
# '''Administration''': pgAdmin is used by database administrators for maintenance tasks, accessible behind the Nginx-Proxy with proper credentials.


[[File:UNITApedia Architecture.jpg|thumb|930px|center|UNITApedia Technological Architecture]]

== High-Level Overview ==
UNITApedia is composed of several interconnected services running in Docker containers, orchestrated via Docker Compose. The main components are:
=== Nginx-Proxy Service ===
* '''Role''': Acts as a reverse proxy, routing external HTTP/HTTPS requests to the appropriate backend service based on URL paths.
* '''Security''': Integrates with the ACME Companion service for automatic SSL certificate management and renewal, ensuring secure connections via HTTPS.
* '''Endpoints''': Forwards traffic to MediaWiki, [https://unitapedia.univ-unita.eu/strapi/ Strapi], phpMyAdmin, [https://unitapedia.univ-unita.eu/pga/ pgAdmin], [https://unitapedia.univ-unita.eu/minio/ MinIO], [https://unitapedia.univ-unita.eu/hop/ Apache HOP], and any additional admin interfaces.


[[File:Nging-proxy service.jpg|thumb|930px|center|Nginx-proxy Service Architeture]]

===MediaWiki Container===
* '''Primary Role''': Serves as the user-facing front-end, allowing UNITA stakeholders to view, edit, and query data related to alliance activities and indicators.
* '''Extensions''':
** [https://www.mediawiki.org/wiki/Extension:External_Data External Data] – Dynamically queries the [https://unitapedia.univ-unita.eu/pga/ PostgreSQL] data warehouse (datamart) to display indicators, metrics, and other information.
** [https://www.mediawiki.org/wiki/Extension:Page_Forms Page Forms] / [https://www.mediawiki.org/wiki/Extension:Semantic_Media_Wiki Semantic MediaWiki] – Enables structured data input and advanced semantic queries within the wiki.
** [https://www.mediawiki.org/wiki/Extension:Scribunto Scribunto (Lua)] – Allows for more advanced scripting and data manipulation.
** [https://www.mediawiki.org/wiki/Extension:PluggableAuth PluggableAuth] + [https://www.mediawiki.org/wiki/Extension:OpenID_Connect OpenID Connect] – Integrates SSO (e.g., Keycloak) for institutional login.
* '''Configuration''': Managed via LocalSettings.php, which includes namespace definitions (e.g., DataSrc and Doc) and data source connections (prepared SQL statements).


[[File:MediaWiki Service.jpg|thumb|930px|center|MediaWiki Service Architeture]]

===PostgreSQL (Data Warehouse)===
* '''Role''': Central repository storing structured data such as deliverables, indicators, and metrics.  
* '''Multi-Database Setup''':  
** ''strapi'': Contains raw input tables from [https://unitapedia.univ-unita.eu/strapi/ Strapi] forms.  
** ''datamart'': Holds transformed and processed data ready for MediaWiki queries.  
** ''unita-data'': Contain additional metadata or wiki configuration tables.   
* '''Administration''': Managed via pgAdmin for database operations (e.g., backups, user management).

===Apache HOP (ETL and Reporting)===
* '''Processes''':  
** '''Data Retrieval''': Fetches raw datasets from [https://unitapedia.univ-unita.eu/minio/ MinIO] buckets (CSV files) or [https://unitapedia.univ-unita.eu/strapi/ Strapi] tables in [https://unitapedia.univ-unita.eu/pga/ PostgreSQL].  
** '''Data Transformation''': Cleans and normalizes data, ensuring consistency (e.g., date formatting, numeric checks, selecting values).  
** '''Data Integration''': Loads validated data into the datamart schema for consumption by MediaWiki.  
* '''Scheduling & Monitoring''': Deployed [https://unitapedia.univ-unita.eu/hop/ Apache HOP] “Carte Server” allows scheduling of jobs and transformations, with logs for error handling and performance monitoring.


[[File:Apache Service.jpg|thumb|930px|center|Apache HOP Service Architeture]]

===MinIO (Object Storage)===
* '''Role''': Stores raw data files (CSV, PDFs, images, etc.) uploaded by UNITA Offices.
* '''Integration''': [https://unitapedia.univ-unita.eu/hop/ Apache HOP] connects to [https://unitapedia.univ-unita.eu/minio/ MinIO] using an S3-compatible interface, retrieving files for ETL processing.  
* '''Organization''': Multiple buckets can be created (e.g., “dev” for storing [https://unitapedia.univ-unita.eu/hop/ Apache HOP] transformations, indicators buckets to store CSV files coming from UNITA Offices).


[[File:Minio Service.jpg|thumb|930px|center|MinIO Service Architeture]]

=== Strapi (Middleware / Headless CMS) ===
* '''Purpose''': Provides a user-friendly interface for UNITA Offices to manually input or update indicator data.  
* '''Data Flow''': Stores raw records in its own [https://unitapedia.univ-unita.eu/pga/ PostgreSQL]L database schema, which [https://unitapedia.univ-unita.eu/hop/ Apache HOP] then reads, transforms, and pushes into datamart.  
* '''APIs''': Exposes REST or GraphQL endpoints if needed for external integrations or advanced use cases.


[[File:Strapi Service.jpg|thumb|930px|center|Strapi Service Architeture]]

=== Administrative Interfaces ===
* '''phpMyAdmin''': Web-based administration tool for MariaDB (if used, e.g., for certain MediaWiki tables or other services).  
* '''pgAdmin''': Used to manage [https://unitapedia.univ-unita.eu/pga/ PostgreSQL] databases, including creation of new schemas, user roles, and backups.

=== Docker-Based Infrastructure ===
* '''Containerization''': Each service (MediaWiki, [https://unitapedia.univ-unita.eu/strapi/ Strapi], [https://unitapedia.univ-unita.eu/hop/ Apache HOP], [https://unitapedia.univ-unita.eu/pga/ PostgreSQL], [https://unitapedia.univ-unita.eu/minio/ MinIO], Nginx) runs in its own container, simplifying updates and scaling.  
* '''Networking''': Docker Compose defines an internal network allowing containers to communicate securely without exposing internal ports directly to the public internet.  
* '''Environment Variables''': Credentials and configuration details (e.g., database passwords, S3 access keys) are injected at runtime to keep them out of version control.

== LocalSettings Configuration (MediaWiki) ==
The <code>LocalSettings.php</code> file is the backbone of the UNITApedia Impact Observatory’s MediaWiki installation. It drives everything from site identity to extensions, external data sources, caching, security and beyond. Below is an overview of how your current configuration supports the site’s functionality.

=== Basic Site Configuration ===
==== Site Identity & URLs ====
* <code>$wgSitename</code>: Set via the <q>OBSERVATORY_NAME</q> environment variable.  
* <code>$wgServer</code> &amp; <code>$wgCanonicalServer</code>: Use <code>https://</code> + <code>DOMAIN_NAME</code> from env.  
* <code>$wgScriptPath</code>: Set to <code>""</code>, so all URLs are relative to the webroot.  
* <code>$wgResourceBasePath</code>: Mirrors <code>$wgScriptPath</code> for static assets.  

==== Locales & Protocols ====
* Default language is English (<code>$wgLanguageCode = "en"</code>).  
* Shell locale forced to <code>C.UTF-8</code> for consistent sorting/formatting.  
* Raw HTML is enabled (<code>$wgRawHtml = true</code>) and an extra allowed protocol was added (<code>https://elearn.univ-pau.fr/</code>).  

=== User Preferences & Authentication ===
==== Email & Notifications ====
* Email is fully enabled (<code>$wgEnableEmail</code>, <code>$wgEnableUserEmail</code>, <code>$wgEmailAuthentication</code>).  
* Sender address and emergency contact are pulled from env (<code>MEDIAWIKI_PWD_EMAIL</code>, <code>MEDIAWIKI_CONTACT_EMAIL</code>).  

==== Login Options ====
* Local login via [https://www.mediawiki.org/wiki/Extension:PluggableAuth PluggableAuth] is enabled (<code>$wgPluggableAuth_EnableLocalLogin = true</code>).  
* Keycloak/[https://www.mediawiki.org/wiki/Extension:OpenID_Connect OpenID Connect] example remains commented out for future SSO.  

=== Database Settings ===
==== Primary Database (MySQL/MariaDB) ====
* Type: <code>mysql</code> on host <code>mariadb</code>.  
* Credentials and database name injected from <q>MEDIAWIKI_DB_</q> env vars.  
* Table options: InnoDB with binary charset.  

=== Caching, File Uploads & Image Handling ===
==== Uploads & Commons ====
* File uploads are enabled (<code>$wgEnableUploads = true</code>).  
* InstantCommons integration is turned on (<code>$wgUseInstantCommons = true</code>).  
* ImageMagick is used for conversions (<code>$wgUseImageMagick = true</code>, convert command at <code>/usr/bin/convert</code>).  

==== File Types & Security ====
* A broad list of extensions is allowed: png, gif, jpg, doc, xls, pdf, pptx, svg, etc.  
* A MIME-type blacklist protects against script uploads (e.g. PHP, shell scripts, MS executables).  

=== Localization & Time Zone ===
* Wiki text in English; PHP shell locale <code>C.UTF-8</code>.  
* <q>Time Zone</q>: <code>$wgLocaltimezone</code> set to <code>UTC</code>, and <code>date_default_timezone_set('UTC')</code> for consistency.  

=== Security & HTTPS ===
* <q>Secret & Upgrade Keys</q>: <code>$wgSecretKey</code> and <code>$wgUpgradeKey</code> loaded from env vars.  
* <q>HTTPS Enforcement</q>: All traffic is forced over HTTPS (<code>$wgForceHTTPS = true</code>).  

=== Skins, Permissions & User Groups ===
==== Skinning ====
* Default skin is Vector-2022 (<code>$wgDefaultSkin = 'vector-2022'</code>), with older Vector-2011 disabled.  
* All users are locked onto Vector-2022 (<code>$wgVectorDefaultSkinVersion = '2'</code>, <code>$wgVectorShowSkinPreferences = false</code>).  

==== User Rights ====
* Anonymous (<q>*</q>) users can read and edit pages but cannot create accounts.  
* Registered <q>user</q> role loses self-edit rights (CSS/JS/JSON).  
* <q>sysop</q> and custom roles (e.g. translator, recipes) have fine-grained SMW and Page Forms permissions.  

=== Enabled Extensions ===
A streamlined but powerful set of extensions is loaded via <code>wfLoadExtension()</code>:
<div style="column-count:4; -moz-column-count:4; -webkit-column-count:4;">
* [https://www.mediawiki.org/wiki/Extension:Arrays Arrays]  
* [https://www.mediawiki.org/wiki/Extension:Babel Babel]  
* [https://www.mediawiki.org/wiki/Extension:CategoryTree CategoryTree]  
* [https://www.mediawiki.org/wiki/Extension:Cargo Cargo]  
* [https://www.mediawiki.org/wiki/Extension:Cite Cite]  
* [https://www.mediawiki.org/wiki/Extension:CleanChanges CleanChanges]  
* [https://www.mediawiki.org/wiki/Extension:CodeEditor CodeEditor/CodeMirror]  
* [https://www.mediawiki.org/wiki/Extension:ConfirmEdit ConfirmEdit]  
* [https://www.mediawiki.org/wiki/Extension:DataTransfer DataTransfer]  
* [https://www.mediawiki.org/wiki/Extension:External_Data External Data]  
* [https://www.mediawiki.org/wiki/Extension:ECharts ECharts]  
* [https://www.mediawiki.org/wiki/Extension:FlexDiagrams FlexDiagrams]  
* [https://www.mediawiki.org/wiki/Extension:Gadgets Gadgets]  
* [https://www.mediawiki.org/wiki/Extension:HeaderTabs HeaderTabs]  
* [https://www.mediawiki.org/wiki/Extension:IframePage IframePage]  
* [https://www.mediawiki.org/wiki/Extension:ImageMap ImageMap]  
* [https://www.mediawiki.org/wiki/Extension:InputBox InputBox]  
* [https://www.mediawiki.org/wiki/Extension:Interwiki Interwiki]  
* [https://www.mediawiki.org/wiki/Extension:MagicNoCache MagicNoCache]  
* [https://www.mediawiki.org/wiki/Extension:Maps Maps]  
* [https://www.mediawiki.org/wiki/Extension:Math Math]  
* [https://www.mediawiki.org/wiki/Extension:ModernTimeline ModernTimeline]  
* [https://www.mediawiki.org/wiki/Extension:MultimediaViewer MultimediaViewer]  
* [https://www.mediawiki.org/wiki/Extension:Network Network]  
* [https://www.mediawiki.org/wiki/Extension:Nuke Nuke]  
* [https://www.mediawiki.org/wiki/Extension:Page_Forms Page Forms]  
* [https://www.mediawiki.org/wiki/Extension:PageImages PageImages]  
* [https://www.mediawiki.org/wiki/Extension:Page_Schemas PageSchemas]  
* [https://www.mediawiki.org/wiki/Extension:ParserFunctions ParserFunctions]  
* [https://www.mediawiki.org/wiki/Extension:PdfHandler PdfHandler]  
* [https://www.mediawiki.org/wiki/Extension:PluggableAuth PluggableAuth]  
* [https://www.mediawiki.org/wiki/Extension:Poem Poem]  
* [https://www.mediawiki.org/wiki/Extension:Renameuser Renameuser]  
* [https://www.mediawiki.org/wiki/Extension:ReplaceText ReplaceText]  
* [https://www.mediawiki.org/wiki/Extension:SecureLinkFixer SecureLinkFixer]  
* [https://www.mediawiki.org/wiki/Extension:Scribunto Scribunto]  
* [https://www.mediawiki.org/wiki/Extension:SpamBlacklist SpamBlacklist]  
* [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi SyntaxHighlight_GeSHi]  
* [https://www.mediawiki.org/wiki/Extension:TabberNeue TabberNeue]  
* [https://www.mediawiki.org/wiki/Extension:TemplateData TemplateData]  
* [https://www.mediawiki.org/wiki/Extension:TemplateWizard TemplateWizard]  
* [https://www.mediawiki.org/wiki/Extension:TextExtracts TextExtracts]  
* [https://www.mediawiki.org/wiki/Extension:TitleBlacklist TitleBlacklist]  
* [https://www.mediawiki.org/wiki/Extension:Translate Translate]  
* [https://www.mediawiki.org/wiki/Extension:TreeAndMenu TreeAndMenu]  
* [https://www.mediawiki.org/wiki/Extension:UniversalLanguageSelector UniversalLanguageSelector]  
* [https://www.mediawiki.org/wiki/Extension:Variables Variables]  
* [https://www.mediawiki.org/wiki/Extension:VisualEditor VisualEditor]  
* [https://www.mediawiki.org/wiki/Extension:Widgets Widgets]  
* [https://www.mediawiki.org/wiki/Extension:WikiEditor WikiEditor]  
</div>

==== Mapping & Charts ====
* [https://www.mediawiki.org/wiki/Extension:ECharts ECharts] for rich, JS-driven charts.  
* [https://www.mediawiki.org/wiki/Extension:OpenStreetMap_OpenLayers_OpenStreetMap OpenStreetMap] for coordinate-based maps.  

=== Semantic MediaWiki Stack ===
* <code>wfLoadExtension('SemanticMediaWiki')</code> and <code>enableSemantics(getenv('DOMAIN_NAME'))</code>.  
* SMW add-ons: [https://www.mediawiki.org/wiki/Extension:SemanticResultFormats SemanticResultFormats], [https://www.mediawiki.org/wiki/Extension:SemanticCompoundQueries SemanticCompoundQueries], [https://www.mediawiki.org/wiki/Extension:SemanticFormsSelect SemanticFormsSelect].  
* Semantic links enabled in the <q>DATASRC</q> namespace.  

=== External Data Sources & Query Files ===
* <q>Local file source DDD</q> pointing at <code>/home/hub/data/files/dev/</code>.  
* [https://unitapedia.univ-unita.eu/pga/ PostgreSQL] source ID for live lookups.  
* GET-allowance turned on (<code>$wgExternalDataAllowGetters = true</code>).  
* Custom query includes: <code>query_meta_unita.php</code>, <code>query_meta_indicators.php</code>, <code>query_raw.php</code>, <code>query_count.php</code>, <code>query_DEMO_DEC24.php</code>, <code>query_DEMO_JAN25.php</code>, and an <code>indicators.php</code> aggregator.  

=== Custom Namespaces ===
* <q>Doc</q> (<code>800/801</code>) and <q>DataSrc</q> (<code>810/811</code>) namespaces defined for structured separation of docs vs. ingested data.  
* A <q>Recipes</q> (<code>805/806</code>) namespace for specialized content.  

=== Mail & Logging ===
* <q>SMTP</q>: Local Postfix on <code>localhost:25</code>, no auth, unencrypted.  
* Mail debug logs written to <code>/tmp/mediawiki-mail.log</code>.  

=== Debugging & Development ===
* <q>Error Display</q>: All exception details, backtraces, SQL errors, and development warnings are enabled (<code>$wgShowExceptionDetails = true</code>, <code>$wgShowDebug = true</code>, etc.) for rapid troubleshooting.

== Docker-Compose File Configuration ==
The UNITApedia system is deployed using Docker Compose (version 3), which orchestrates all the services required for the application. This configuration ensures modularity, scalability, and clear separation between components. Below is the updated Docker Compose configuration.

=== Version and Networks ===
* <q>Version</q>: Compose file uses version <q>3</q>.  
* <q>Networks</q>: A custom network <code>observatory_net</code> defined with the <q>bridge</q> driver.

<pre>
networks:
  observatory_net:
    driver: bridge
</pre>

=== Volumes ===
Persistent storage is defined through several named volumes:

<pre>
volumes:
  mariadb:
  dw-data:
  pgadmin-volume:
  html:
  certs:
  acme:
  minio:
</pre>

=== Services ===
Each service is defined with specific images, settings, and dependencies.

<pre>
  mariadb:
    image: mariadb:10.11
    container_name: mariadb
    restart: always
    networks:
      - observatory_net
    expose:
      - "3306"
    volumes:
      - mariadb:/var/lib/mysql
      - ./services/mariadb/_initdb.mariadb/:/docker-entrypoint-initdb.d/
    env_file:
      - .env
      - ./services/mariadb/.env
</pre>

<pre>
  postgres:
    image: postgres:14.0-alpine
    container_name: postgres
    restart: unless-stopped
    networks:
      - observatory_net
    expose:
      - "5432"
    ports:
      - "5432"
    volumes:
      - dw-data:/var/lib/postgresql/data/
      - ./services/strapi/strapi.dump:/tmp/strapi.dump
      - ./services/postgres/_initdb.pg/:/docker-entrypoint-initdb.d/
    env_file:
      - .env
      - ./services/postgres/.env
</pre>

<pre>
  mediawiki:
    build:
      context: ./services/mediawiki
      dockerfile: MediaWiki.Dockerfile
    container_name: mediawiki
    restart: always
    networks:
      - observatory_net
    expose:
      - "80"
    volumes:
      - ./services/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro
      - ./services/mediawiki/composer.local.json:/var/www/html/composer.local.json
      - ./services/mediawiki/images/:/var/www/html/images/:rw
      - ./services/mediawiki/resources/assets/:/var/www/html/resources/assets/
      - ./services/mediawiki/extensions:/var/www/html/extensions/
      - ./services/mediawiki/mediawiki/:/var/www/html/mediawiki/:ro
    env_file:
      - .env
      - ./services/mediawiki/.env
    environment:
      VIRTUAL_HOST: ${DOMAIN_NAME}
      VIRTUAL_PATH: /
      VIRTUAL_PORT: "80"
      LETSENCRYPT_HOST: ${DOMAIN_NAME}
      LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
    depends_on:
      - mariadb
      - postgres
</pre>

<pre>
  strapi:
    build:
      context: ./services/strapi
      dockerfile: Strapi.Dockerfile
    image: strapi/strapi:latest
    container_name: strapi
    restart: unless-stopped
    networks:
      - observatory_net
    expose:
      - "1337"
    volumes:
      - ./services/strapi/config:/opt/app/config
      - ./services/strapi/src:/opt/app/src
      - ./services/strapi/package.json:/opt/package.json
      - ./services/strapi/yarn.lock:/opt/yarn.lock
      - ./services/strapi/.env:/opt/app/.env
      - ./services/strapi/public/uploads:/opt/app/public/uploads
    env_file:
      - /data/impact-observatory/services/strapi/.env
    environment:
      VIRTUAL_HOST: ${DOMAIN_NAME}
      VIRTUAL_PATH: /strapi/
      VIRTUAL_DEST: /
      VIRTUAL_PORT: "1337"
      LETSENCRYPT_HOST: ${DOMAIN_NAME}
      LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
    depends_on:
      - postgres
    command: /bin/sh -c "yarn strapi ts:generate-types && yarn develop"
</pre>

<pre>
  hop-web:
    image: apache/hop-web:latest
    container_name: hop-web
    restart: unless-stopped
    ports:
      - "8080"
    volumes:
      - ./services/hop-web/projects:/project
      - ./services/hop-web/tomcat/config:/config
    env_file:
      - .env
    environment:
      VIRTUAL_HOST: ${DOMAIN_NAME}
      VIRTUAL_PATH: /hop/
      VIRTUAL_DEST: /
      VIRTUAL_PORT: "8080"
      LETSENCRYPT_HOST: ${DOMAIN_NAME}
      LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
      AWS_ACCESS_KEY_ID: zcby8I0PeG1uprpYO4KR
      AWS_SECRET_ACCESS_KEY: xyaCmOf86QWiyGM3L5BfKFv5WQxS70pjKKAbqQIN
      AWS_REGION: us-east-1
      AWS_ENDPOINT: http://minio:9000
      AWS_PATH_STYLE: <q>true</q>
    networks:
      - observatory_net
    depends_on:
      - postgres
</pre>

<pre>
  minio:
    image: minio/minio:latest
    container_name: minio
    restart: always
    networks:
      - observatory_net
    ports:
      - "9000"
      - "9001"
    volumes:
      - ./services/minio/data:/data
    env_file:
      - .env
      - ./services/minio/.env
    environment:
      VIRTUAL_HOST: ${DOMAIN_NAME}
      VIRTUAL_PATH: /minio/
      VIRTUAL_DEST: /
      VIRTUAL_PORT: "9001"
      MINIO_BROWSER_REDIRECT_URL: https://unitapedia.univ-unita.eu/minio
    command: server /data --console-address ":9001"
</pre>

* <code>phpmyadmin</code>, <code>pgadmin</code>, <code>nginx-proxy</code>, and <code>acme-companion</code> follow similar patterns for image, ports, volumes, networks, and virtual-host environment variables.

== Makefile Configuration ==
The <code>Makefile</code> is designed to automate common tasks involved in managing the UNITApedia deployment. By reading settings from an <code>.env</code> file and an <code>extensions.config</code> file, it enables consistent builds, extension installation, maintenance operations, and backups.

=== Environment and Extension Configuration ===
* <q>Environment Inclusion</q>:  
  The <code>Makefile</code> begins by including the <code>.env</code> file and <code>./services/mediawiki/.env</code>, so that environment-specific variables (e.g., database credentials, domain names) are available throughout the build process.

* <q>Extensions Configuration</q>:  
  The <code>extensions.config</code> file lists extension names and versions. Although the cloning logic is commented out, the Makefile can use tools like <code>awk</code> to extract <code>EXTENSION_NAMES</code> and <code>EXTENSION_VERSIONS</code> for automated fetching of MediaWiki extensions.

=== Core Targets ===
* <code>help</code>: Show available commands and descriptions.  
* <code>up</code>: Start all containers (<code>$(DC) up -d</code>).  
* <code>down</code>: Stop all containers (<code>$(DC) down</code>).  
* <code>restart</code>: Restart all containers.  
* <code>logs</code>: Follow container logs with the last 100 lines.  
* <code>clean</code>: Remove local build & backup artifacts, reset extensions directory, and prune unused Docker objects.  
* <code>build</code> / <code>build-no-ext</code>: Build full stack and initialize MediaWiki extensions and services.  
* <code>mw-install</code>: Install Composer dependencies and run <code>maintenance/update.php</code> inside the MediaWiki container.  
* <code>mw-initialize</code>: First-time Composer update (no scripts) and post-install scripts, then run <code>maintenance/update.php</code>.  
* <code>mw-dev-copy</code>: Copy the MediaWiki container’s <code>/var/www/html</code> contents into a local folder for development.  
* <code>backup</code>: Run both <code>backup-mariadb</code> and <code>backup-postgres</code>.  
* <code>backup-mariadb</code>: Dump the MariaDB database into a timestamped file under <code>services/mariadb/backups</code>.  
* <code>backup-postgres</code>: Dump the PostgreSQL database into a timestamped file under <code>services/postgres/backups</code>.  

<pre>
# Load environment variables
include .env
include ./services/mediawiki/.env

DC = docker-compose
DEFAULT_EXT_VERSION = REL1_39

.DEFAULT_GOAL := help

help: ## Show help
	@echo "Available commands:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'

# ───── Docker Lifecycle ─────

up: ## Start all containers
	$(DC) up -d

down: ## Stop all containers
	$(DC) down

restart: ## Restart all containers
	$(DC) down && $(DC) up -d

logs: ## Show container logs
	$(DC) logs -f --tail=100

clean: ## Remove local build & backup artifacts
	rm -rf mediawiki_container_folder services/**/backups
	rm -rf services/mediawiki/extensions && mkdir -p services/mediawiki/extensions
	docker system prune -a --force

build: mw-extensions ## Build full stack, install MediaWiki extensions, and start everything
	$(DC) build
	make mw-initialize

build-no-ext: ## Build full stack, install MediaWiki extensions, and start everything
	$(DC) build
	make mw-initialize

# ───── MediaWiki ─────

mw-install: ## Install composer and update mediawiki (running maintenance script)
	$(DC) up -d
	sleep 10
	$(DC) exec mediawiki composer install
	$(DC) exec mediawiki php maintenance/update.php

mw-initialize: ## First-time Composer install with no scripts (safe for fresh builds)
	$(DC) up -d
	sleep 10
	@echo "📦 Composer update (no-scripts)..."
	$(DC) exec mediawiki composer update --no-dev --prefer-dist --optimize-autoloader --no-scripts
	@echo "⚙️ Running post-install/update scripts manually (if any)..."
	$(DC) exec mediawiki composer run-script post-update-cmd || true
	@echo "🧹 Running MediaWiki update.php..."
	$(DC) exec mediawiki php maintenance/update.php

mw-dev-copy: ## Copy MediaWiki container contents locally (for dev)
	rm -rf mediawiki_container_folder
	$(DC) cp mediawiki:/var/www/html/. mediawiki_container_folder/

# ───── Database Backups ─────

backup: ## Backup all databases
	make backup-mariadb
	make backup-postgres

backup-mariadb:
	mkdir -p services/mariadb/backups
	$(DC) exec database sh -c "mysqldump -u$$MARIADB_USER -p$$MARIADB_PWD $$MEDIAWIKI_DB_NAME" > services/mariadb/backups/backup_$(shell date +%F_%T).sql

backup-postgres:
	mkdir -p services/postgres/backups
	$(DC) exec datawarehouse pg_dump -U $$DATABASE_USERNAME $$DATABASE_NAME > services/postgres/backups/backup_$(shell date +%F_%T).sql
</pre>