Add GeoGirafe to an existing GeoMapFish project
This guide describes one way to install GeoGirafe, but other methods may also work for your geoportal.
Choose a name for your GeoGirafe instance that will be used as its URL path. For example, if you name it v2, the frontend will be accessible at my.domain.com/v2. Throughout this tutorial, we use <gg-instance-name> as a placeholder.
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 next
This creates a /front folder. Add it to your .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
To choose a specific GeoGirafe version, edit package.json and run npm update. At the time of writing, x 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.js 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.
...
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 /tmp/config/ /tmp/config/
COPY /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:
...
&& 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:
...
services:
config:
extends:
file: docker-compose-lib.yaml
service: config
build:
args:
VISIBLE_ENTRY_POINT: ${VISIBLE_ENTRY_POINT}
Add this to your .dockerignore:
!front/public
!front/src
!front/*.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:
managed_files:
- ...whatever you have...
- \.dockerignore
- Dockerfile
To use your new interfaces, add them to your vars.yaml:
interfaces:
- name: desktop
default: True
- name: mobile
- name: iframe_api
- name: <gg-instance-name>
type: custom
html_filename: index.html
- name: <gg-instance-name>_mobile
type: custom
html_filename: mobile.html
- name: <gg-instance-name>_iframe
type: custom
html_filename: iframe.html
- name: <gg-instance-name>_api
type: custom
html_filename: api.html
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 <gg-instance-name> with your chosen entrypoint.
Check your console for any additional domains or rules you may need. An adaption example for geo admin WMTS Service is provided below.
global_headers:
# Needed for Cesium.js and data: images
- pattern: '^/<gg-instance-name>(?:_iframe|_mobile)?$'
headers:
Content-Security-Policy: "default-src 'self'
https://sitn.ne.ch
https://wmts.geo.admin.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
https://wmts.geo.admin.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/. Add the base_href in the <head> section and redirect the mobile to the mobile URL:
<base href="%BASE_URL%">
<meta name="redirect-url" content="<gg-instance-name>_mobile" />
Do the same thing on every html file you have in your front, like api.html, iframe.html, mobile.html, etc.
Then rebuild everything:
./build
docker compose down
docker compose up -d
That's it! Go to https://<your.geoportal>/<gg-instance-name> to see GeoGirafe running. If you open the console, chances are that there are some errors. Follow the next steps to fix them.
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": ""
},
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](/docs/functionalities and concepts/authentication#3-configure-the-cors).
Whitelist demo domains
Some tools will not work if you don't whitelist the domain where they are running. Let's say we want to make everything work at https://demo.geogirafe.org. In your vars you need to add or create some keys:
vars:
...
allowed_hosts:
- ...
- 'demo.geogirafe.org'
...
authorized_referers:
- ...
- 'demo.geogirafe.org'
...
shortener:
...
allowed_hosts:
- ...
- 'demo.geogirafe.org'
...
headers:
...
themes: &auth_header
...
access_control_allow_origin:
- ...
- 'https://demo.geogirafe.org'
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.
interfaces:
- name: desktop
- name: mobile
- name: iframe_api
- name: <gg-instance-name>
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.
Clean it up
If you don't need them, you can remove custom.css and custom.html files and delete their reference in vite.congig.js
rollupOptions: {
input: {
desktop: resolve(__dirname, 'index.html'),
- custom: resolve(__dirname, 'custom.html'),
You can also delete the mock folder if you've configured an URL for themes.