Skip to content

Installation instructions v 4.x

Jump to bottom
Anca Luca edited this page May 29, 2022 · 62 revisions

These instructions explain how to install wikidemarches (nosdemarches / monavis / observatoire), versions 4.x. Dedicated paragraphs specify operations needed for an upgrade from 3.x. Instructions are driven for and tested for an upgrade from 3.3 (not snapshot of 3.4).

This project is built to run on top of XWiki Standard , version 9.11.3 - see http://www.xwiki.org .

Build

Build the code of this repo using maven (set up as explained in http://dev.xwiki.org/xwiki/bin/view/Community/Building/#HInstallingMaven ), with

mvn clean install

then use the built artefacts to install as described under.

Installation

WAR setup

XWiki standard war, version 9.11.3, which can be downloaded from here: http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-web/9.11.3/ .

The following additional settings are required by the project:

  • Deploy XWiki to the webapps/ROOT instead of webapps/xwiki and copy xwiki.cfg, xwiki.properties and urlrewrite.xml from the sources from web/src/main/webapp/WEB-INF into the WEB-INF folder of the deployment. Then perform the following configurations:
    • in xwiki.cfg :
      • set xwiki.authentication.validationKey and xwiki.authentication.encryptionKey to safely generated random keys
    • in xwiki.properties :
      • set environment.permanentDirectory to the value corresponding to the current instance
      • set openoffice.homePath to the value corresponding to the current instance
      • if fetching data from Pingdom is needed, add pingdom.apitoken as a parameter, holding the api token obtained from the pingdom service ( https://www.pingdom.com/ )
  • Deploy xwiki-platform-legacy-oldcore-DINSICDEMA9.11.3-5ac27ae16a240b3e43376195312e34076dfe9ae4.jar as follows:
    • Checkout xwiki-platform-legacy-oldcore-DINSICDEMA9.11.3-5ac27ae16a240b3e43376195312e34076dfe9ae4.jar from the bin folder of the wikidemarches git repository
    • Copy and paste this jar into the WEB-INF/lib folder of the webapp
    • Remove xwiki-platform-legacy-oldcore-9.11.3.jar from the same folder (or any older version of this jar)
  • Deploy xwiki-platform-search-solr-api-DINSICDEMA9.11.3-45ad9b0e084d555ea5dc1361eb7edb41d61e30d0.jar as follows:
    • Checkout the jar from the bin folder of the wikidemarches git repository
    • Copy and paste this jar into the WEB-INF/lib folder of the webapp
    • Remove xwiki-platorm-search-solr-api-9.11.3.jar from that folder
  • Deploy the [xwiki-dinsic-wikidemarches-extensions-]tools-api-.jar, built or released from module extensions/tools/tools-api or extensions/tools-api (starting with 4.2) in WEB-INF/lib
  • Deploy the excel plugin in WEB-INF/lib as follows:
  • Deploy the patch for XCOMMONS-1151, as follows:
  • Deploy the patch for XWIKI-16960, as follows:
    • get jar xwiki-platform-dashboard-macro-9.11.8-XWIKI-14247-1321d264e4cc2da38c395ad46d3ff2cc388d0dbb.jar from the bin folder of this project
    • copy it in WEB-INF/lib folder
    • remove xwiki-platform-dashboard-macro-9.11.3.jar jar from that folder
  • Deploy DSFR & static ressources:
    • checkout the dsfr-scoped and the custom-wikidemarches folder from the web/src/main/webapp/uicomponents/ folder from the sources of this project
    • copy these 2 folders in the resources/uicomponents folder of the XWiki instance - if the folders are there already, empty or remove the existing ones and replace them with the new ones.

Apache configuration

  • This project runs on a standard Apache configuration, which needs to serve the file from robots-public.txt as robots.txt .
  • The Apache configuration should pass requests to tomcat for / and include the following configurations:
    • serve observatoire.numerique.gouv.fr with https and have jedonnemonavis.numerique.gouv.fr and cerfa.numerique.gouv.fr as aliases, as well as the legacy domain names nosdemarches.gouv.fr, monavis.numerique.gouv.fr and voxusagers.numerique.gouv.fr .
    • include the specific redirections described below:
    RewriteEngine On

    # Backwards compat: All nosdemarches redirects to monavis
    RewriteCond %{HTTP_HOST} "nosdemarches.gouv.fr"
    RewriteRule ^/(.*)$ https://monavis.numerique.gouv.fr/$1 [R,L,NE]

    # Backwards compat: All voxusagers redirects to jedonnemonavis
    RewriteCond %{HTTP_HOST} "voxusagers.numerique.gouv.fr"
    RewriteRule ^/(.*)$ https://jedonnemonavis.numerique.gouv.fr/$1 [R,L,NE]

    # Jedonnemonavis homepage and login redirect to observatoire
    RewriteCond %{HTTP_HOST} "jedonnemonavis.numerique.gouv.fr"
    RewriteRule ^/$ https://observatoire.numerique.gouv.fr/ [R,L,NE]
    RewriteCond %{HTTP_HOST} "jedonnemonavis.numerique.gouv.fr"
    RewriteRule ^/login(.*) https://observatoire.numerique.gouv.fr/ [R,L,NE]

    # Backwards compat for button ressources: Legacy monavis URLs: all view-mode=formulaire-avis go to jedonnemonavis
    RewriteCond %{HTTP_HOST} "^monavis.numerique.gouv.fr$"
    RewriteCond %{QUERY_STRING} view-mode=formulaire-avis
    RewriteRule ^/(.*)$ https://jedonnemonavis.numerique.gouv.fr/$1 [R,L,NE]

    # Backwards compat for button ressources: Legacy nosdemarches URLs avis form URLs but which don't contain view-mode=formulaire-avis but contain nd_mode (and will also contain nd_source in practice) go to jedonnemonavis
    RewriteCond %{HTTP_HOST} "^monavis.numerique.gouv.fr$"
    RewriteCond %{QUERY_STRING} nd_mode
    RewriteRule ^/(.*)$ https://jedonnemonavis.numerique.gouv.fr/$1 [R,L,NE]

    # Backwards compat for button ressources: all static ressources of monavis are now jedonnemonavis ressources, with the new static ressources path
    RewriteCond %{HTTP_HOST} "^monavis.numerique.gouv.fr$"
    RewriteRule ^/monavis-static/(.*)$ https://jedonnemonavis.numerique.gouv.fr/static/$1 [R,L,NE]

    # Backwards compat: all other monavis URLs (which haven't matched above, so they're not button ressources) go to observatoire
    RewriteCond %{HTTP_HOST} "^monavis.numerique.gouv.fr$"
    RewriteRule ^/(.*)$ https://observatoire.numerique.gouv.fr/$1 [R,L,NE]

    # Homepage is displayed as / whichever its actual address is
    RewriteRule "^/$" "/bin/view/Main/" [L,PT]
    RewriteRule "^/bin/view/Main/$" "/" [L,R]
    RewriteRule "^/bin/Main/$" "/" [L,R]
    RewriteRule "^/Main/$" "/" [L,R]

    # Workaround issue with an accented character being improperly encoded / handled by IE and sent as messed up value
    # This workaround can be removed if no requests are coming with the messed up character anymore, since we now encode properly all characters in the URLs and URLs are full ASCII. Check access logs before removing
    RewriteCond %{QUERY_STRING} ^nd_source=service-public.fr&nd_mode=en-ligne-enti.rement
    RewriteRule "^(.*)$" $1?nd_source=service-public.fr&nd_mode=en-ligne-entièrement [R,L]

Deployment of static ressources

Add the following in the apache configuration:

Just after the ErrorDocument settings:

Alias "/static" /var/www/static

At the end of the file, before ProxyPass /:

ProxyPass /static !

Copy the folder static from the sources to the location /var/www/static on the server. Change owner to folder and subfolders to www-data.

Out of service ressources

From the sources folder maintenance, deploy the maintenance.html and error.html as the static files to serve by Apache whenever the platform is down. Configuration of these files may depend on the installation.

Main wiki

Extensions

To be installed :

  • XWiki Livetable Exporter Macro, version 4.0 (extension id: org.xwiki.contrib:xwiki-livetable-exporter-macro)
    • this will also install Job macro extension, as a dependency
  • UIN Script Service (for creating new Avis): org.xwiki.contrib:api-uin-scriptservice version 2.0
  • Open Sans font as webjar: Using advanced search, install the following extension org.webjars.bower:open-sans version 1.1.0
  • Query Generator and Query Macro, version 1.4.1 (extension id: org.xwiki.contrib:application-querygenerator )
    • edit rights on page Macros.QueryGenerator and give 'view' right only to Admin group (local admin group)
  • AppWithin Minutes Charts and Data, version 1.2.2 (extension id: org.xwiki.contrib:appwithinminutes-charts
  • OpenCSV (for exporting data in CSV): com.opencsv:opencsv version 3.10
  • Chart.js Integration ( org.xwiki.contrib:application-chartjs-ui ), version 1.5
  • org.webjars:datatables version 1.10.19
  • org.webjars:datatables-fixedheader version 3.1.4
  • org.webjars:requirejs-domready, version 2.0.1-2
  • org.webjars:require-css, version 0.1.7
  • org.xwiki.contrib.membership:application-membership-profile, version 1.0.7
  • Matomo Application (org.xwiki.contrib:application-piwik-extension), version 1.3.1
  • JSON Storage API (org.xwiki.contrib:api-jsonstore) version 1.0

To be removed :

  • Help Center Application 1.2, Sandbox application 9.11.3, Help Application 9.11.3
  • XWiki Platform - Distribution - Flavor - Tour 9.11.3 : org.xwiki.platform:xwiki-platform-distribution-flavor-tour - check all boxes for deleting all pages when asked
  • Tour Application 1.1 : org.xwiki.contrib:application-tour-ui - check all boxes for deleting all pages when asked

Custom code

First install

  • Delete the french translation of the Main.WebHome page, as follows:
    • Go to wiki administration
    • Enable multilanguage, setup english and french as available languages
    • Save
    • Go on the main page, in french language, and manually change the url the delete action URL with parameter ?language=fr (/xwiki/bin/delete/Main/WebHome?language=fr)
    • Confirm delete, accept to delete pages from the extension "XWiki Platform - Distribution - Flavor - Common" (click "sélectionner tout", there's a bug in the platform)
    • Restore the wiki in French language only
  • Import xwiki-dinsic-wikidemarches-wikis-main-.xar

Upgrade from a previous version

  • For the first installation of a version 4.1+: Existing dashboard attachments upgrade
    • Download existing JSON data from [email protected]
    • Download existing PDF file from observatoire.WebHome@observatoire-de-la-dematerialisation-juin-2019.pdf
    • Edit the JSON file in UTF8 encoding and add the following property to the root object: "metadata":{"date":"2019-06-30","schema":"1.0"}
  • Using Administration->Content->Import, import the artifact xwiki-dinsic-wikidemarches-wikis-main-upgrade-.xar
  • Manually remove from the wiki the pages that were deleted from the repo since the last install
  • Manually upgrade the non-upgradable pages that were modified since last install
  • For the first installation of a version 4.1+: Create a named dashboard "2019-juin" and attach to it as "data.json" the JSON file modified in the first action of this paragraph, and the downloaded PDF as the dashboard PDF in the dashboard PDF dedicated field, using the XWiki attachment selector.

Configuration of Analytics (whenever/if required)

  • In Adminitstration -> Autre -> Piwik configure the following settings:
    • url piwik : the URL of the Matomo server that is to collect the information
    • Methode de tracking : tracking par Javascript
    • Id du site : the site id obtained from the Matomo server that is to collect the information
    • Tracking des utilisateurs : Non
    • Tracking multi-domaine : Non
    • URL du domaine : leave empty

Data import (whenever required)

  • Install the following jars, in WEB-INF/lib (or update them to the specified version if already present). Note: if these jars are installed with extension manager, remove them first from extension manager.
    • opencsv api version 3.10 (the dependency of xwiki-batchimport-api v2.3)
    • xwiki-batchimport-api, version 2.3
    • xwiki-batchimport-postprocessors-listidentifier version at least 2.4-SNAPSHOT with head above d523e277112839e10cc3e3305cc35fc6f0584006
    • xwiki-dinsic-wikidemarches-extensions-batch-imports-api version current version
  • Using extension manager in the UI, install:
    • xwiki-batchimport-application version 2.3
  • Using the standard xar import:
    • xwiki-dinsic-wikidemarches-extensions-batch-imports-ui current version
  • Prepare the import file:
    • remove the first "Nom" column, the one containing emoji in the values
    • remove the comments column
    • replace the sunglasses emoji and the rocket header in the column headers with the "[private] " key
  • Proceed to import data from this file:
    • Go to page "Administration.Top250Reset" and set the top250 value to all demarches to be imported to 0
      • Upon import, check that mappings are all still valid with the columns names from the file
      • For the deduplication options step, choose "Ignore" as a value for the "duplicate values in file" option and "Mise à jour" for the "duplicate values on the wiki" option.
    • Go to Demarches homepage and manually edit the remaining demarches marked "top250" to remove the flag
    • Go to page "Administration.TopDemarchesImport", upload the top démarches file and proceed with its batch import.
      • Upon import, check that mappings are all still valid with the columns names from the file
      • For the deduplication options step, choose "Ignore" as a value for the "duplicate values in file" option and "Mise à jour" for the "duplicate values on the wiki" option.
    • Go to page "Administration.TopDemarchesImportEdiOnly", upload the top démarches file and proceed with its batch import.
      • Upon import, check that mappings are all still valid with the columns names from the file
      • For the deduplication options step, choose "Ignore" as a value for the "duplicate values in file" option and "Mise à jour" for the "duplicate values on the wiki" option.
  • only for versions lower than 4.4 - Go to page "Administration.TopDemarchesPingdomScoreImport", upload the file obtained from top démarches file (sheet with pingdom data) and proceed with its batch import. Make sure all mappings are still valid.

Generate data for the observatoire dashboard (whenever required) - only for versions lower than 4.1

This operation is to be executed whenever the data of the dashboard needs to be refreshed from live platform data, e.g. after an import.

  • Go to page "Demarches.Code.Top" and click the button "Generate json data and attach it to this page".
Clone this wiki locally