docs(sitmun.github.io): update docs, add Troubleshooting, restructure archive

- Move docs/archive.md to _archive/archive.md
- Add docs/troubleshooting.md
- Remove docs/demo.md
- Update multiple pages: API, Architecture, Configuration, Design, Features (client/server),
  Getting Started, Index, License, Management, Roadmap (and subpages)
- Update mkdocs.yml navigation to reflect changes
- Add .python-version for local toolchain
- Update poetry.lock

Author: fjlopez

.python-version

@@ -0,0 +1 @@
+3.11.10

docs/archive.md _archive/archive.mddocs/archive.md renamed to _archive/archive.md

@@ -34,26 +34,18 @@ Pero hay información que posiblemente no está documentada en otros sitios.
 > towards open source projects, we migrated to GitHub Actions. These configuration files are thus currently the GitHub
 > Actions workflows in the .github/workflows directory in each repository. These files will generally use `npm` and `ng`
 > for the front-end libraries and applications, and gradle for the back-end components. They use `sonarcloud` for static
-> code analysis, `compodoc` to create the angular libraries documentation (accessible then in <https://sitmun.github.io/>)
-> etc. They also deploy some applications and components (currently to GitHub pages and Heroku) for testing.
+> code analysis, `compodoc` to create the angular libraries documentation (published on a static site)
+> etc. They also deploy some applications and components (e.g., to GitHub pages) for testing.
 >
 > The scripts require a number of values that are different for each developer / build environment, and other values
 > which are secrets that can't be shared in the repositories. If you want to build locally, those values generally
 > must be in environment variables. Depending on the repository and your needs your environment will need to have
 > defined:
 >
 > - `JAVA_HOME`: Make sure it points to a proper installation of the required version of Java.
-> - `USERNAME`: Your GitHub user. Required to access to the packages in the GitHub registry, and to publish packages
->   there, with the proper access token (see next point).
-> - `GITHUB_API_KEY`: A GitHub personal access token, created for `USERNAME` and with, at least, the required scopes.
->   These scopes are, in a nutshell, `read:packages` to download and install packages from GitHub packages and
->   `write:packages` to upload and publish. Your GitHub user needs also read permissions on the repository to
->   download packages, and write permission to publish them.
 > - `SONAR_TOKEN`: A SonarCloud authentication token is required for the sonarqube Gradle task to work on your computer.
 >
-> The CI build scripts need values for these too. Those are stored as secrets associated to the SITMUN organization in
-> GitHub and currently are: `SONAR_TOKEN`, `TOKEN_FOR_WORKFLOWS` (the `GITHUB_API_KEY`), `USERNAME_FOR_WORKFLOWS` (`USERNAME`),
-> `HEROKU_TOKEN` and `HEROKU_EMAIL` (currently used for the automatic deployment of the back-end to Heroku for testing purposes).
+>
 >
 > Regarding the libraries which are published to the GitHub packages registry, they are published only on tagged commits.
 > So you can push changes to a library as you like, but if you want that to be published as a package by the CI server,
@@ -71,12 +63,6 @@ Pero hay información que posiblemente no está documentada en otros sitios.
 >
 > Each repository has a `sonar-project.properties` file with the proper configuration to make it possible to analyze its
 > code on SonarCloud.
->
-> **Programming languages, runtimes and tools**
->
-> Some repositories use only Java (e.g. the backend-core), others use only Node.js and others use both.
-> For the required versions, again the CI server configuration files should be taken as the canonical ones.
-> You also need the Git client.
 
 ## Documentación del código
 
@@ -90,5 +76,6 @@ tan solo lo esencial y tratar de mantener eso razonablemente actualizado.
 > `git push` to master is done to the repository. The tools currently used are:
 >
 > - Compodoc for the Typescript/Angular code.
-> - Swagger2markup for the REST API.
 > - Javadoc for the Java classes in the server.
+
+

docs/api.md

@@ -1,53 +1,41 @@
 # Referencia
 
-## API de Autenticación
+## API de Autenticación {#api-de-autenticacion}
 
-La **[API de Autenticación](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Autenticaci%C3%B3n)** expone vía una API Web mecanismos para interactuar con el sistema de seguridad de SITMUN.
+La API de Autenticación expone vía una API Web mecanismos para interactuar con el sistema de seguridad de SITMUN.
 Esta API se ha creado para que la **aplicación de administración** y los **visores de mapas obtengan**,
-tras pasar las credenciales de usuario obtengan un token de acceso [JSON web token](https://jwt.io/) (JWT) necesario para operar con el resto de las API.
+tras pasar las credenciales de usuario obtengan un token de acceso JSON web token (JWT) necesario para operar con el resto de las API.
 
-[Explorar API de Autenticación :simple-openapiinitiative:](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Autenticaci%C3%B3n){ .md-button }
+## API de Configuración y Autorización {#api-de-configuracion-y-autorizacion}
 
-## API de Configuración y Autorización
-
-La **[API de Configuración y Autorización](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Configuraci%C3%B3n%20y%20Autorizaci%C3%B3n)**
-expone vía una API Web mecanismos para obtener una configuración derivada del estado actual de los objetos de dominio
+La API de Configuración y Autorización expone vía una API Web mecanismos para obtener una configuración derivada del estado actual de los objetos de dominio
 en función de la identidad y rol del que solicita la información.
 Esta API se ha creado para que los **visores de mapas** y el **proxy** puedan configurarse.
 
-La **API de Configuración y Autorización** se compone de dos tipos de endpoints:
+La API de Configuración y Autorización se compone de dos tipos de endpoints:
 
 - **Configuración y Autorización de Visor de mapas**.
-  La petición pueden autenticarse usando un esquema de *autenticación por portador*
-  ([*Bearer authentication*](https://swagger.io/docs/specification/authentication/bearer-authentication/))
-  usando un token que se ha obtenido previamente mediante la **[API de Autenticación][api-de-autenticacion]**.
+  La petición pueden autenticarse usando un esquema de autenticación por portador (Bearer authentication)
+  usando un token que se ha obtenido previamente mediante la API de Autenticación.
   Si no se autentica, se asume que la petición se ha realizado por un usuario que en el dominio de **SITMUN 3** se denomina
   *usuario público*.
 - **Configuración y Autorización de Proxy**.
   La petición debe autenticarse usando una API key enviada mediante la cabecera denominada `X-SITMUN-Proxy-Key`.
   El uso de una API key específica para el endpoint **Configuración y Autorización de Proxy** es una decisión de seguridad.
-  Evita que a un cliente malicioso le pueda bastar el uso del token obtenido de la **[API de Autenticación][api-de-autenticacion]**
+  Evita que a un cliente malicioso le pueda bastar el uso del token obtenido de la API de Autenticación
   para obtener secretos vía el endpoint **Configuración y Autorización de Proxy**.
 
-[Explorar API de Configuración y Autorización :simple-openapiinitiative:](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Configuraci%C3%B3n%20y%20Autorizaci%C3%B3n){ .md-button }
-
-## API de Proxy
+## API de Proxy {#api-de-proxy}
 
-La **[API de Proxy](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20del%20Proxy)**
-permite acceder a los visores de mapas a servicios remotos y bases de datos.
+La API de Proxy (Proxy Middleware) permite acceder a los visores de mapas a servicios remotos y bases de datos.
 
-Los **visores de mapas** pueden autenticarse usando un esquema de *autenticación por portador*
-([*Bearer authentication*](https://swagger.io/docs/specification/authentication/bearer-authentication/))
+Los **visores de mapas** pueden autenticarse usando un esquema de autenticación por portador (Bearer authentication)
 usando un token que se ha obtenido previamente mediante la API de Autenticación.
 Si no se autentica, se asume que la petición se ha realizado por un usuario que en el dominio de **SITMUN 3** se denomina
 *usuario público*.
 
-[Explorar API de Proxy :simple-openapiinitiative:](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20del%20Proxy){ .md-button }
+## API de Administración {#api-de-administracion}
 
-## API de Administración
-
-La **[API de Administración](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Administraci%C3%B3n)** expone vía una API Web mecanismos para modificar el estado de los objetos de dominio
+La API de Administración expone vía una API Web mecanismos para modificar el estado de los objetos de dominio
 de **SITMUN 3** por parte de la **aplicación de administración**.
-La **aplicación de administración** debe autenticarse con un JSON Web Token obtenido de la **[API de Autenticación][api-de-autenticacion]**.
-
-[Explorar API de Administración :simple-openapiinitiative:](https://sitmun-backend-core.herokuapp.com/swagger-ui/index.html?urls.primaryName=API%20de%20Administraci%C3%B3n){ .md-button }
+La **aplicación de administración** debe autenticarse con un JSON Web Token obtenido de la API de Autenticación.

docs/architecture.md

@@ -27,7 +27,7 @@ Las aplicaciones de usuario final de **SITMUN 3** interactúan relativamente poc
 
 Esto conviene tenerlo en cuenta cuando estemos dimensionando el hardware que necesitamos para el despliegue, y cómo lo vamos a repartir.
 
-**SITMUN 3** tiene una arquitectura de 3-tiers. Las aplicaciones web se desarrollan con Angular, Spring Boot se usa en el tier web, y una base de datos relacional (Oracle o PostgreSQL a día de hoy, pero se pueden usar otras) en el tier de datos.
+**SITMUN 3** tiene una arquitectura de 3-tiers. Las aplicaciones web se desarrollan con Angular 16, Spring Boot 3 se usa en el tier web, y una base de datos relacional (PostgreSQL 16, Oracle 23c, o H2 para desarrollo a día de hoy, pero se pueden usar otras) en el tier de datos.
 
 ## Principales componentes
 
@@ -61,7 +61,7 @@ rectangle appadmin [
 ]
 
 database configdb [
-  <color:Crimson><$oracle> / <color: RoyalBlue><$postgresql> (PostgreSQL)
+  <color:Crimson><$oracle> (Oracle 23c) / <color: RoyalBlue><$postgresql> (PostgreSQL 16) / <color: Green>H2 (Desarrollo)
   
   --
   
@@ -117,7 +117,7 @@ component privatewms #PapayaWhip [
 ]
 
 database territdb #PapayaWhip [
-  <$lock_protected{scale=0.5}> <color:Crimson><$oracle> / <color: RoyalBlue><$postgresql> (PostgreSQL)
+  <$lock_protected{scale=0.5}> <color:Crimson><$oracle> (Oracle 23c) / <color: RoyalBlue><$postgresql> (PostgreSQL 16)
   
   --
   
@@ -778,16 +778,6 @@ together {
 }
 
 together {
-  package "Despliegue en Heroku" <<application, dev>> as ":deploy:heroku-dev-full" #ffa500  {
-    
-  }
-
-  note top of ":deploy:heroku-dev-full"
-    Configuración adaptada para
-    su despliegue en **Heroku**
-    usando **Heroku postgres**
-    para persistencia
-  end note
 
   package "Schema Export" <<tool, dev>> as ":cli" #ffa500  {
     
@@ -801,8 +791,7 @@ together {
 }
 
 
-":deploy:heroku-dev-full" ..> ":app" : <<import>>
-":deploy:heroku-dev-full" .[norank].> ":legacy" : <<import>>
+
 
 ":cli" .r.> ":app" : <<import>>
 

docs/configuration.md

@@ -5,7 +5,7 @@
 
 ## Backend
 
-### API de Autenticación
+### API de Autenticación {#configuration-api-de-autenticacion}
 
 Estas propiedades se utilizan para configurar el acceso al servidor LDAP para autenticar a los usuarios.
 
@@ -18,39 +18,38 @@ Estas propiedades se utilizan para configurar el acceso al servidor LDAP para au
 | `sitmun.authentication.ldap.url`             | Localización del servidor LDAP                                            |                   |
 | `sitmun.authentication.ldap.base-dn`         | Contexto raíz para todas las operaciones LDAP                             |                   |
 | `sitmun.authentication.ldap.user-dn-pattern` | Patrón que identifica el usuario                                          |                   |
-| `sitmum.authentication.ldap.username`        | El nombre de usuario a utilizar cuando se autentique con el servidor LDAP | nulo              |
-| `sitmum.authentication.ldap.password`        | La contraseña a utilizar cuando se autentique con el servidor LDAP        | nulo              |
+| `sitmun.authentication.ldap.password`        | La contraseña a utilizar cuando se autentique con el servidor LDAP        | nulo              |
 
-### API de Configuración y Autorización
+### API de Configuración y Autorización {#configuration-api-de-configuracion-y-autorizacion}
 
-| Propiedad                                         | Descripción                                           | Valor por defecto |
-|---------------------------------------------------|-------------------------------------------------------|-------------------|
-| `sitmun.proxy.config-response-validity-in-secons` | Duración máxima del token de acceso que admite la API | `3600`            |
-| `sitmun.authentication.middleware.secret`         | Token que usa el componente proxy para autenticarse   |                   |
+| Propiedad                                                 | Descripción                                                        | Valor por defecto |
+|-----------------------------------------------------------|--------------------------------------------------------------------|-------------------|
+| `sitmun.proxy-middleware.config-response-validity-in-seconds` | Duración máxima (en segundos) de validez de la respuesta de configuración | `3600`            |
+| `sitmun.proxy-middleware.secret`                          | Secreto que usa el componente proxy para autenticarse               |                   |
 
 Mediante las siguientes propiedades se puede forzar la reescritura de las URI de los servicios en las repuestas de
 configuración para clientes de mapas para que apunten al componente Proxy.
 
-| Propiedad            | Descripción                       | Valor por defecto |
-|----------------------|-----------------------------------|-------------------|
-| `sitmun.proxy.force` | Fuerza el uso del proxy de SITMUN | `false`           |
-| `sitmun.proxy.url`   | Localización del proxy de SITMUN  |                   |
+| Propiedad                         | Descripción                       | Valor por defecto |
+|-----------------------------------|-----------------------------------|-------------------|
+| `sitmun.proxy-middleware.force`   | Fuerza el uso del proxy de SITMUN | `false`           |
+| `sitmun.proxy-middleware.url`     | Localización del proxy de SITMUN  |                   |
 
 ## Proxy
 
 | Propiedad                                 | Descripción                                                                                                                | Valor por defecto |
 |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|-------------------|
-| `sitmun.config.url`                       | Ruta al endpoint de configuración del **proxy** en la API de configuración y autorización                                  |                   |
-| `sitmun.authentication.middleware.secret` | Token que usa el proxy para autenticarse (ver [API de configuración y autorización](#api-de-configuracion-y-autorizacion)) |                   |
+| `sitmun.backend.config.url`               | Ruta al endpoint de configuración del **proxy** en la API de configuración y autorización                                  |                   |
+| `sitmun.backend.config.secret`            | Secreto que usa el proxy para autenticarse (ver API de configuración y autorización)                                       |                   |
 
 ## Visor de mapas
 
-| Propiedad | Descripción                                       | Valor por defecto                           |
-|-----------|---------------------------------------------------|---------------------------------------------|
-| `apiUrl`  | La URL pública donde se despliega el **backend**. | `https://sitmun-backend-core.herokuapp.com` |
+| Propiedad | Descripción                                       | Valor por defecto               |
+|-----------|---------------------------------------------------|---------------------------------|
+| `apiUrl`  | La URL pública donde se despliega el **backend**. | `http://localhost:9000/backend` |
 
 ## Administrador
 
-| Propiedad    | Descripción                                       | Valor por defecto                            |
-|--------------|---------------------------------------------------|----------------------------------------------|
-| `apiBaseURL` | La URL pública donde se despliega el **backend**. | `https://sitmun-backend-core.herokuapp.com`  |
+| Propiedad    | Descripción                                       | Valor por defecto                |
+|--------------|---------------------------------------------------|----------------------------------|
+| `apiBaseURL` | La URL pública donde se despliega el **backend**. | `http://localhost:9000/backend`  |

docs/demo.md

@@ -196,7 +196,7 @@ La petición que el **proxy** realizaría al endpoint `/api/config/proxy` de la
 {
   "appId": 1,
   "terId": 34,
-  "type": "wms",
+  "type": "WMS",
   "typeId": 1,
   "method": "GET",
   "parameters": {
@@ -219,14 +219,14 @@ La respuesta podría ser como sigue:
 
 ```json
 {
-  "type": "wms",
+  "type": "OgcWmsPayload",
   "exp": 1623340800,
   "payload": {
-    "uri": "https://geoserveis.icgc.cat/icgc_bm5m/wms/service",
-    "method": "GET",
     "vary": [
       "BBOX"
     ],
+    "uri": "https://geoserveis.icgc.cat/icgc_bm5m/wms/service",
+    "method": "GET",
     "parameters": {
       "SERVICE": "WMS",
       "REQUEST": "GetMap",
@@ -261,3 +261,8 @@ GET /icgc_bm5m/wms/service?SERVICE=WMS&REQUEST=GetMap
     &WIDTH=498&HEIGHT=594
 Host: geoserveis.icgc.cat
 ```
+
+[api-de-autenticacion]: api.md#api-de-autenticacion
+[api-de-configuracion-y-autorizacion]: api.md#api-de-configuracion-y-autorizacion
+[api-de-proxy]: api.md#api-de-proxy
+[servicio-de-proxy]: design.md#servicio-de-proxy

docs/design.md

@@ -153,3 +153,13 @@
 ## Aplicación de Administración
 
 !!! warning "Documentación en desarrollo"
+
+[api-de-autenticacion]: api.md#api-de-autenticacion
+[api-de-configuracion-y-autorizacion]: api.md#api-de-configuracion-y-autorizacion
+[api-de-proxy]: api.md#api-de-proxy
+
+## Canonical Link References
+
+- [API de autenticación][api-de-autenticacion]
+- [API de configuración y autorización][api-de-configuracion-y-autorizacion]
+- [API de Proxy][api-de-proxy]