Skip to main content

Add geogirafe to an existing GeoMapFish project

tip

This guide describes one way to install Geogirafe, but other methods may also work for your geoportal.

Prerequisites​

GeoMapFish (GMF) project version 2.9 or higher

Get geogirafe code​

At the root of your GMF project, run:

npm create @geogirafe/template@latest front

This creates a /front folder. Add it to your .gitignore:

/.gitignore
# Front
front/node_modules
front/dist

If you want to run it without Docker, follow the instructions here: https://gitlab.com/geogirafe/gg-sample

How to update geogirafe?

To choose a specific geogirafe version, edit package.json and run npm update. At the time of writing, the version is 1.0.0-0. The -0 indicates a pre-release, not intended for production.

Frequent changes may break your installation. After updating, check if new packages were added and review index.html and vite.config.json for changes.

Build Geogirafe with Docker​

In your existing Dockerfile, before the last image (usually called gmf_config), add a build step for Geogirafe and copy the resulting assets into the config image. The lines to add are highlighted below.

/Dockerfile
...
FROM node:22-slim AS front-build

WORKDIR /app
COPY front/package.json front/package-lock.json ./

RUN npm install --ignore-scripts

COPY front/ ./
ARG VISIBLE_ENTRY_POINT
RUN npm run build -- --base=${VISIBLE_ENTRY_POINT}static-frontend/

###############################################################################

FROM camptocamp/geomapfish-config:${GEOMAPFISH_MAIN_MINOR_VERSION} AS gmf_config

ARG PGSCHEMA
ENV PGSCHEMA=$PGSCHEMA

COPY --from=builder /tmp/config/ /tmp/config/
COPY --from=front-build /app/dist/app /etc/static-frontend
...

Further down in the same Dockerfile, grant permissions on the new folder and update the last line to expose the volume:

/Dockerfile
    ...
    && chmod g+w -R \
        /etc/geomapfish \
        /etc/mapserver \
        /etc/qgisserver \
        /etc/tilegeneration \
        /usr/local/tomcat/webapps/ROOT/print-apps \
        /etc/haproxy_dev \
        /etc/haproxy \
        /etc/static-frontend \
    && sed 's#bind :80#bind *:443 ssl crt /etc/haproxy_dev/localhost.pem#g' /etc/haproxy/haproxy.cfg.tmpl \
        > /etc/haproxy_dev/haproxy.cfg.tmpl \
    && echo '    http-request set-header X-Forwarded-Proto https' >> /etc/haproxy_dev/haproxy.cfg.tmpl

VOLUME /etc/geomapfish \
    /etc/mapserver \
    /etc/qgisserver \
    /etc/tilegeneration \
    /usr/local/tomcat/webapps/ROOT/print-apps \
    /etc/haproxy_dev \
    /etc/haproxy \
    /etc/static-frontend

In your docker-compose.yaml, add these three lines to declare the VISIBLE_ENTRY_POINT variable in the args section of the service configuration:

/docker-compose.yaml
...
services:
  config:
    extends:
      file: docker-compose-lib.yaml
      service: config
    build:
      args:
        VISIBLE_ENTRY_POINT: ${VISIBLE_ENTRY_POINT}

Add this to your .dockerignore:

/.dockerignore

!front/public
!front/src
!front/custom.css
!front/*.html
!front/package*.json
!front/tsconfig.json
!front/vite.config.js

Because you modified .dockerignore and Dockerfile, add these files to the managed files (i.e., files you update manually when upgrading your GeoMapFish project). In project.yaml, make sure they are listed:

/project.yaml
managed_files:
  - ...whatever you have...
  - \.dockerignore
  - Dockerfile

To use your new interface, add it to your vars.yaml:

/geoportal/vars.yaml
  interfaces:
    - name: desktop
      default: True
    - name: mobile
    - name: iframe_api
    - name: geogirafe
      type: custom
      html_filename: index.html
What about adding the interface to the admin?

You don't have to. Admin interfaces control available themes and layers. The geogirafe interface will work fine with the desktop interface in the admin.

While editing vars, configure the Content Security Policy (CSP). Replace sitn.ne.ch with your geogirafe domain, and geogirafe with your chosen entrypoint. Check your console for any additional domains or rules you may need.

/geoportal/vars.yaml
  global_headers:
    # Needed for Cesium.js and data: images
    - pattern: '^/geogirafe(?:_iframe|_mobile)?$'
      headers:
        Content-Security-Policy: "default-src 'self' https://sitn.ne.ch;
          script-src-elem 'self' 'unsafe-inline';
          script-src-attr 'self' 'unsafe-inline';
          script-src 'self' 'wasm-unsafe-eval' 'unsafe-eval';
          style-src-elem 'self' 'unsafe-inline' data:;
          style-src-attr 'self' 'unsafe-inline';
          img-src 'self' https://sitn.ne.ch data:;"

By default, a GeoMapFish project serves custom static files at /static-frontend/. That's why --base=${VISIBLE_ENTRY_POINT}static-frontend/ is passed as an argument in the Dockerfile build step.

Update front/index.html so all static file calls use /static-frontend/. Replace the two <meta name="configs"...> lines in the <head> section with:

/front/index.html
    <base href="%BASE_URL%">
    <meta name="configs" content="main,mobile">
    <link rel="config-main-url" href="config.json" />
    <link rel="config-mobile-url" href="config.mobile.json" />

Then rebuild everything:

./build
docker compose down
docker compose up -d

That's it! Go to https://<your.geoportal>/geogirafe to see geogirafe running.

Configuring geogirafe​

To configure your frontend using environment variables, use the templating provided by the config image.

Rename your config files by adding a .tmpl extension, e.g., config.json.tmpl.

You can now use ENV variables in these files. For example, to set the themes route (by default a mock JSON is served):

  "themes": {
    "url": "mock/themes.json",
    "defaultTheme": ""
  },

Delete the mock folder and update the URL:

  "themes": {
    "url": "${VISIBLE_WEB_PROTOCOL}://${VISIBLE_WEB_HOST}${VISIBLE_WEB_PORT}${VISIBLE_ENTRY_POINT}themes?background=background&interface=desktop",
    "defaultTheme": ""
  },
Pay attention to the params of that URL

Your background may not be named background, and your interface name may differ.

Also, ensure VISIBLE_WEB_HOST and VISIBLE_WEB_PORT are set correctly. For localhost, VISIBLE_WEB_HOST should not include a port, and in production, VISIBLE_WEB_PORT should be empty.

After renaming config.json to config.json.tmpl, rebuild:

./build
docker compose down
docker compose up -d

If your geogirafe instance shows a backend CORS error, you can fix it by following this doc.

Make it default​

To make geogirafe the default interface, update your vars.yaml: remove the default flag from the previous interface and set it on the custom one.

/geoportal/vars.yaml {8}
  interfaces:
    - name: desktop
    - name: mobile
    - name: iframe_api
    - name: geogirafe
      type: custom
      html_filename: index.html
      default: True

Optionally, you can delete the existing desktop interface and rename the geogirafe interface to desktop to match the admin interface name.

Add the mobile interface​

Ensure the mobile.html file exists. As with the desktop interface, add the mobile interface in vars.yaml. For example, name it geogirafe_mobile:

/geoportal/vars.yaml {8-10}
  interfaces:
    - name: desktop
    - name: mobile
    - name: iframe_api
    - name: geogirafe
      type: custom
      html_filename: index.html
    - name: geogirafe_mobile
      type: custom
      html_filename: mobile.html

Do the same for any additionnal interface you want to add like iframe for instance.

You'll then need to configure the automatic redirect, in your index.html, change existing meta tag named redirect-url, set its content attribute to the name of your mobile interface:

/front/index.html
<meta name="redirect-url" content="geogirafe_mobile" />