Difference between revisions of "User:Jtraulle/DiscourseMigration"

From Dolibarr ERP CRM Wiki
< Jean Traullé (jtraulle)User:Jtraulle/DiscourseMigration
Jump to navigation Jump to search
Tag: 2017 source edit
Tag: 2017 source edit
Line 3: Line 3:
This page gathers info about Discourse migration.
This page gathers info about Discourse migration.
For the implementation, see [[User:Jtraulle/DiscourseMigrationImplementation]]
For the implementation, see [[User:Jtraulle/DiscourseMigration/Implementation]]

Revision as of 21:47, 8 November 2019

This page gathers info about Discourse migration.

For the implementation, see User:Jtraulle/DiscourseMigration/Implementation

Context (forum migration project genesis)

Topic has been first discussed on the french speaking Dolibarr forum here : https://www.dolibarr.fr/forum/11-suggestionsnouvelles-fonctionnalites/64778-forum-quelle-solution-choisir

Topic has also been discussed on Report board meeting 20190730 teleconf

Proposed skeleton

Each newly created thread MUST be placed into a category.

Categories in bold are main categories.

Categories preceded of a bullet point are sub categories belonging to a main category.

Categories proposal
Annonces & actualités (verrouillé)

Vous trouverez dans cette catégorie des annonces et actualités en lien avec le projet Dolibarr : nouvelles versions, évènements, mise à jour des outils communautaire du projet, etc.

Installer mon Dolibarr

Obtenir de l’aide sur l’installation de Dolibarr quelque soit votre système (GNU/Linux, macOS, Windows, système NAS), votre méthode d’installation (depuis les sources, DoliWamp, DoliDeb, DoliRpm) et votre environnement (serveur local, mutualisé, dédié, cloud).

Utiliser mon Dolibarr

Obtenir de l’aide sur l’utilisation des modules fournis avec Dolibarr, suggérer des nouvelles fonctionnalités ou signaler des anomalies.

  • Modules GRC/GRF (Tiers, Contrats/Abonnements, Interventions, Commandes, Expéditions, Tickets)
  • Modules GRH (Utilisateurs, Adhérents, Congés, Notes de frais)
  • Modules PM (Produits, Services)
  • Modules financiers (Facturation, Banque/Caisse, Dons, Comptabilité, Comptabilité avancée)
  • Autres modules natifs (Projets/Travail collaboratif, GED, Outils multi-modules, etc.)
  • Modules externes du DoliStore
  • Retours d'expérience
Maintenir mon Dolibarr

Obtenir de l’aide sur la mise à jour de Dolibarr vers une version plus récente, la migration d’une instance Dolibarr vers un nouveau serveur, les opérations de sauvegarde et de restauration (fichiers et base de données) et plus généralement, tout ce qui touche à la configuration et à la maintenance système de la machine hébergeant votre instance Dolibarr (cron, permissions, etc.).

Développer pour Dolibarr

Obtenir de l’aide concernant le développement de modules spécifiques ou thèmes pour Dolibarr mais également sur la façon d’utiliser les modules API REST et SOAP pour interconnecter Dolibarr avec une application externe.

Discuter entre Dolibarriens

Cet espace de discussion vous permet d’échanger avec les autres utilisateurs de Dolibarr sur des sujets sans lien avec Dolibarr.

Each newly created thread can also have tags regardless of its category.

Transversal tags proposal
Tags type Tags proposal
Type of


Code branch

or Version


An user will also have the ability to mark an answer of the thread as the solution.

This explains why there is no Résolu tag in the proposal.

Proposed mapping between current and new skeleton

Categories are in bold and sub-categories in italic.

Current categories or sub-categories New proposed categories and sub-categories
Annonces et fonctionnement du forum Annonces & actualités (verrouillé)
Installation Installer mon Dolibarr
Installation sous Mac
Installation sous Gnu/Linux
Installation sous Windows
Installation Qnap Synology Divers
Installation Hebergeurs
Mise à Jour Maintenir mon Dolibarr
Howto / Aide Utiliser mon Dolibarr
Bugs sur la version CVS ou demo
Bugs sur la version stable courante
Bugs avec PostgreSQL
Bugs sur la version ARCHIVE
Bugs Dolibarr V6
Bugs Dolibarr V7
Bugs Dolibarr V3
Bugs Dolibarr V4
Bugs Dolibarr V5
Retours d'expériences utilisateurs/intégrateurs Retours d'expérience
Suggestions/Nouvelles fonctionnalités Utiliser mon Dolibarr
Spécifiques à un Pays
Le module que j'ai téléchargé et deployé n'apparait pas Modules externes du DoliStore
Création d'un nouveau module Développer pour Dolibarr
Hooks/Triggers/Classes Objets
Git & Github
Adhérents/Association Modules GRC/GRF
E-Commerce Modules externes du DoliStore
Agenda Autres modules natifs
WebMails Modules externes du DoliStore
Autres modules
Modules InfraS
Modules ATM
Module gestion de projets Autres modules natifs
Modeles ODT
Modules Patas Monkeys Modules externes du DoliStore
Gestion des Ressources Humaines (GRH) Modules GRH
Module utilisateurs
Demandes de congés
Notes de frais
Protection des Données
Gestion de la relation client (GRC) Modules GRC/GRF
Module Tiers
Modules Contrats/Abonnements
Module Interventions
Propositions commerciales
Gestionnaire de tickets(Expérimental)
Commandes clients
Gestion de la relation fournisseur (GRF)
Propositions commerciales fournisseurs
Modules financiers (Compta/trésorerie) Modules financiers
Comptabilité /Comptabilité (avancée)
Banques et caisses
Règlement salaires
Module Marges
Factures et avoirs clients/ factures fournisseurs
Gestion des emprunts
Gestion des Produits/Services (PM) Modules PM
Variantes de produits
Numéros de Lot/Série
Gestion des services
Gestion des produits
Gestion électronique de documents (GED) Autres modules natifs
Modules Themes Utiliser mon Dolibarr
Theme amarok
Theme Eldy
Outils multi-modules Autres modules natifs
Mass Emailing
Flux RSS
Exports / Imports de données Utiliser mon Dolibarr
Module Multidevise Autres modules natifs
Sites web et autres applications frontales Utiliser mon Dolibarr
Touch Screen POS Modules financiers
Module Sondage ou Vote Autres modules natifs
Module Caisse Modules financiers
Système Maintenir mon Dolibarr
Travaux planifiés
Interfaces avec des systèmes externes Développer pour Dolibarr
Paypal Modules financiers
Impressions Directe Autres modules natifs
Projets/Travail collaboratif
Module Ressources

Preview of new mapping after migration

Demo instance

Demo instance with migrated data is available here : https://test-dolibarr-discourse.traulle.net/ (private ; see https://www.dolibarr.fr/forum/administration-forum/64852-instance-de-test-discourse#113680 for access - restricted to forum moderators and admins)

Migration path

Migrating from Kunena to Discourse can be handled using the Discourse official import script.

A step by step guide is also available on the Discourse forum.

Old Kunena releases (3.x) can be downloaded from the JoomlaCode forge.

The original Discourse's Kunena migration script has been customized to be more aligned with the specific migration needs of the french Dolibarr forum.

It can be retrieved here : https://gist.github.com/jtraulle/a8ed0244a2a77498f29ac32fd2bc0f65

Main differences with original script :

Import Users

  • Retrieve old "anonymous" Kunena users that does not have a Joomla! account
  • Retrieve profile info
  • Retrieve avatars

Import Categories

  • Import categories hierarchy ignoring main groups (Discourse only has two levels hierarchy)
  • Categories are imported preserving the original order
  • Categories with no posts (and no subcategories) are ignored/skipped

The latest version of the custom migration script takes care of re-categorizing topics into the #Proposed_skeleton

Import Posts

  • Multiple enhancements on posts text content
    • Escape some commonly used chars (>, -, +, *) to not be wrongly parsed as Markdown
    • Block quote
      • add a line break after [quote] BBCode tag if there is none
      • Replacing old posts reference in quote blocks by new ones
      • Removing remaining posts references in quote blocks for posts that does not exists anymore
    • Unordered lists
      • Break line after [ul] only for lines that starts by [ul] and followed by [li] tag on the same line
    • Strike support
      • Replace [strike][/strike] BBCode tag by HTML equivalent for markdown parser
    • Emojis
      • Convert some emojis shortcuts to preserve custom emojis previously used
  • Thank you
    • Kunena post's "thank you" are imported as Discourse post's likes (added)

Import Attachments

Attachments to import into the new Discourse instance should be present to the local filesystem before running the task (plan about 400M disk space).

To download attachments from previous forum, start by export the URLs from the Kunena database.

SELECT CONCAT('https://www.dolibarr.fr/', folder, '/', filename) AS url FROM gvrsi_kunena_attachments ORDER BY id;

Put all the URLs into a text file (for example uploads.txt).

Next, use wget to download all attachment preserving the directory structure (yuuup, file names of multiple distinct attachments can be the same ...)

wget --no-host-directories --force-directories --input-file=uploads.txt


Permalinks offer the ability to preserve old forum links (from Kunena) and emit a HTTP 301 (Permanent Redirect) when hitting such old links for categories, topics, posts and profile links.

Categories permalinks

Kunena stores aliases for categories in the kunena_categories alias database field.

Topics permalinks

For topics URLs, this a bit more tricky since they are not stored in database (it uses standard Joomla! SEO friendly URLs generated using JRouter) and should therfore be generated on the fly in the import script.

Research showed that a "safe" alias can be generated using following Joomla! function :

  • stringUrlSafe() function in libraries/vendor/joomla/filter/src/OutputFilter.php
  • using transliterate() function in libraries/src/Language/Language.php
  • using utf8_latin_to_ascii() function in libraries/src/Language/Transliterate.php

Direct messages permalinks

Permalinks to specific messages like for example https://www.dolibarr.fr/forum/12-howto--aide/62681-wiki-dolibarr-org?start=225#113400 are even more tricky than topics permalinks because everything that is after a # in considered and anchor and, as such could be treated only on the client side (therefore using Javascript).

The permalink treatment logic for direct messages is the following :

  1. User go to https://test-dolibarr-discourse.traulle.net/forum/12-howto--aide/62681-wiki-dolibarr-org?start=225#113400 (the old permalink)
  2. Normalization permalink rule /(.*)\?.*/\1 is triggered and therefore remove part of the URL starting by ? ; the new URL to be processed become https://test-dolibarr-discourse.traulle.net/forum/12-howto--aide/62681-wiki-dolibarr-org#113400
  3. Permalink for topic is triggered and redirect the URL to https://test-dolibarr-discourse.traulle.net/forum/t/wiki-dolibarr-org/27878#113400 (keeping the original anchor with the old postid)
  4. Javascript detect that the current URL have a # part
  5. Using Javascript, we redirect to the permalink https://test-dolibarr-discourse.traulle.net/forum/old-post/113400 that redirects to https://test-dolibarr-discourse.traulle.net/forum/t/wiki-dolibarr-org/27878/227

Javascript part

This code is to paste in the Admin → Customize → Themes → Light → Edit CSS/HTML → Common → </head> section.

<script type="text/javascript">
var urlSplit = document.URL.split("#");
if (urlSplit[1]) {
    location.href = "/forum/old-post/" + urlSplit[1];


Current forum display an Ad banner (ads are currently managed in house using Joomla!

Discourse offers an Official Advertising / Ad Plugin that can be used as a replacement. See https://meta.discourse.org/t/official-advertising-ad-plugin-for-discourse/33734

Tentative design

Custom logos

Go to Admin → Customize → Settings → Branding

  • Based on Dolibarr main color #3D5F93
  • Blippo font

Logo forum discourse (proposal)

Logo to use in email notifications and mobile view

Logo forum discourse(for email and mobile view)

Custom color palette

Go to Admin → Customize → Colors

  • tertiary : #004488
  • quaternary : #3D5F93
  • danger : #B43314

Color palette proposal

Custom layout

Discourse allow to easily include a custom header and footer ; as well as custom styles.

This is a tentative custom Layout

Custom Header to add

Go to Admin → Customize → Themes → Light → Edit CSS/HTML → Desktop → Header and paste :

<div id="header" class="clearfix">
    <div id="inner-header">
    	<a id="logo" href="/">
    		<img src="https://www.dolibarr.fr/templates/dolibarr/images/bg2.png" alt="ERP et CRM Open Source pour gérer votre entreprise ou association - Portail France" width="200" height="59">
    	<div id="headermodule">
            <div class="bannergroup bannertop">
    	        <div class="banneritem">
    	            <a href="/component/banners/click/22" target="_blank" title="Partenaire ATOO.NET">
    					<img src="https://www.dolibarr.fr/images/banners/Couteau_suisse_UltimatePdf.jpg" alt="ATOONET" width="468" height="60">
    				<div class="clr"></div>
	<div id="nav">
    	<div id="decalmenu" class="backshadow">
    		<ul class="nav menu" id="mainmenu">
                <li class="item-166"><a href="https://www.dolibarr.fr/">Accueil</a></li>
                <li class="item-57"><a href="https://www.dolibarr.fr/screenshots">Screenshots</a></li>
                <li class="item-49"><a href="https://www.dolibarr.fr/demo-en-ligne">Démo en ligne</a></li>
                <li class="item-36"><a href="https://www.dolibarr.fr/telechargements">Téléchargements</a></li>
                <li class="item-64"><a href="https://www.dolibarr.fr/documentation">Documentation</a></li>
                <li class="item-79"><a href="https://www.dolibarr.fr/boutique">Boutique</a></li>
                <li class="item-59"><a href="https://www.dolibarr.fr/association">Association</a></li>
                <li class="item-207 active"><a href="https://www.dolibarr.fr/forum">Forum</a></li>
            <form id="mod-finder-searchform" action="https://www.dolibarr.fr/component/finder/search" method="get" class="form-search">
            	<div class="finder">
            		<input type="text" placeholder="Recherche..." name="q" id="mod-finder-searchword" class="search-query input-medium" size="15" value="" autocomplete="off">
            		<input type="hidden" name="Itemid" value="198">
    	<div class="backshadow arrowafterul"></div>
    	<div class="backshadow"></div>

Custom Footer to add

Go to Admin → Customize → Themes → Light → Edit CSS/HTML → Desktop → Footer and paste :

<div id="footer">
	<span itemprop="name">Dolibarr ERP &amp; CRM</span> © 2003-2017 - Gestion d'entreprise ou d'association

Custom CSS to add

Go to Admin → Customize → Themes → Light → Edit CSS/HTML → Desktop → CSS and paste :

#header {
	background-color: rgb(61,95,147);
	background-image: url(https://www.dolibarr.fr/templates/dolibarr/images/shadows/light/header-overlay.png),url(https://www.dolibarr.fr/templates/dolibarr/images/overlays/headers/header-6_dolibarr.png);
    background-repeat:repeat-x, no-repeat;
	background-position-x: 600px;

#inner-header {
	max-width: 1110px;
	height: 105px;
    margin: auto;

#main-outlet {
    box-shadow: 0 5px 10px gray;

#headermodule {
    float: right;
    margin: 10px 0;

.banneritem {
    margin-right: 8px;

#main {
    background: url(https://www.dolibarr.fr/templates/dolibarr/images/header-overlay.png) 50% -90px repeat-x !important;
    background-color: rgba(0, 0, 0, 0);
    background-color: #FFFFFF !important;

.d-header {
    background-color: inherit;
    box-shadow: inherit;

.d-header .wrap {
    box-shadow: 0 2px 4px -1px rgba(0,0,0,0.25);

.d-header .wrap .contents, #main-outlet {
    background-color: #FFFFFF;

#logo {
    float: left;
    margin: 5px 0;
    display: block;
    max-width: 100%;
	margin-left: 4px;
	margin-top: 32px;	

/* menu */
#nav {
	background-color: rgb(56,90,127) !important;
	background: linear-gradient(rgba(56,90,127,.5), rgba(56,90,127,1)),url(https://www.dolibarr.fr/templates/dolibarr/images/shadows/light/nav-overlay2.png) 50% 0 repeat-x !important; /* Standard syntax */
#nav ul {
#nav ul li {
	display: inline-block;
	margin: 0 0 0 0;
	padding: 8px 4px 4px 12px;
#nav #decalmenu {
	max-width: 1126px;
	margin: auto;
	padding: 0;
#nav ul li a {
	display: inline-block;
	color: #FFF;
	font-weight: bold;
	text-decoration: none;
	font-size: 13px;
	padding: 6px 5px 4px 5px;
	height: 26px;

.backshadow {background: url(https://www.dolibarr.fr/templates/dolibarr/images/shadows/light/nav-overlay3.png) 0% 0 repeat-x;}

#nav arrowafterul { background: url(https://www.dolibarr.fr/templates/dolibarr/images/shadows/light/menus/menutab-r.png) 0 0 no-repeat; }
#nav ul li { background: url(https://www.dolibarr.fr/templates/dolibarr/images/shadows/light/menus/menutab-r.png) 0 0 no-repeat; min-height: 36px; }
#nav ul li.active, #nav ul li.active { opacity: 0.8; }

#nav ul li:hover, #nav ul li:hover .item, #nav ul li.active:hover { 
    background-image: -webkit-gradient( linear, left top, left bottom, color-stop(0, rgba(255,255,255,.3)), color-stop(1, rgba(0,0,0,.3)) );

#mainmenu {
    display: inline-block;

#rokajaxsearch, form#mod-finder-searchform {
	display: inline-block;
	margin-right: 10px;
	margin-left: 68px;
	margin-bottom: 10px;
.roksearch_search_str {
	width: 150px;

input.search-query {
	padding-right: 14px;
	padding-right: 4px \9;
	padding-left: 14px;
	padding-left: 4px \9;
	margin-bottom: 0;
	-webkit-border-radius: 15px;
	-moz-border-radius: 15px;
	border-radius: 15px;
.finder .search-query {
	width: 132px;
.form-search .input-append .search-query,
.form-search .input-prepend .search-query {
	-webkit-border-radius: 0;
	-moz-border-radius: 0;
	border-radius: 0;
.form-search .input-append .search-query {
	-webkit-border-radius: 14px 0 0 14px;
	-moz-border-radius: 14px 0 0 14px;
	border-radius: 14px 0 0 14px;
.form-search .input-append .btn {
	-webkit-border-radius: 0 14px 14px 0;
	-moz-border-radius: 0 14px 14px 0;
	border-radius: 0 14px 14px 0;
.form-search .input-prepend .search-query {
	-webkit-border-radius: 0 14px 14px 0;
	-moz-border-radius: 0 14px 14px 0;
	border-radius: 0 14px 14px 0;
.form-search .input-prepend .btn {
	-webkit-border-radius: 14px 0 0 14px;
	-moz-border-radius: 14px 0 0 14px;
	border-radius: 14px 0 0 14px;
.form-search input,
.form-search textarea,
.form-search select,
.form-search .help-inline,
.form-search .uneditable-input,
.form-search .input-prepend,
.form-search .input-append,
.form-inline input,
.form-inline textarea,
.form-inline select,
.form-inline .help-inline,
.form-inline .uneditable-input,
.form-inline .input-prepend,
.form-inline .input-append,
.form-horizontal input,
.form-horizontal textarea,
.form-horizontal select,
.form-horizontal .help-inline,
.form-horizontal .uneditable-input,
.form-horizontal .input-prepend,
.form-horizontal .input-append {
	display: inline-block;
	*display: inline;
	*zoom: 1;
	margin-bottom: 0;
	vertical-align: middle;
.form-search .hide,
.form-inline .hide,
.form-horizontal .hide {
	display: none;
.form-search label,
.form-inline label,
.form-search .btn-group,
.form-inline .btn-group {
	display: inline-block;
.form-search .input-append,
.form-inline .input-append,
.form-search .input-prepend,
.form-inline .input-prepend {
	margin-bottom: 0;
.form-search .radio,
.form-search .checkbox,
.form-inline .radio,
.form-inline .checkbox {
	padding-left: 0;
	margin-bottom: 0;
	vertical-align: middle;
.form-search .radio input[type="radio"],
.form-search .checkbox input[type="checkbox"],
.form-inline .radio input[type="radio"],
.form-inline .checkbox input[type="checkbox"] {
	float: left;
	margin-right: 3px;
	margin-left: 0;

#footer {
    margin: auto;
    background: #e3e3e3;
    border-top: 1px solid #ccc;
    padding: 5px;
    color: #888;
    text-align: center;


Hardware requirements

To the extent possible, a VPS machine that will be dedicated to running the Discourse forum software only is the way to go.

  • modern single core CPU, dual core recommended
  • 1 GB RAM minimum (with swap)
  • 64 bit Linux compatible with Docker (I recommand 18.04 LTS Ubuntu Server to be aligned with the wiki.dolibarr.org OS).
  • 10 GB disk space minimum (SSD is a plus for the speed but not a requirement)

Refer to Hardware requirement (github.com)

Domain requirements

Discourse requires a FQDN (Fully Qualified Domain Name) : for example forum.dolibarr.fr and cannot be installed in a subdirectory.

=> We must found a solution and valid it works. Future is to have doc/wiki on https://www.dolibarr.org/wiki, an forum of https://www.dolibarr.org/forum. Forum is 2/3 of traffic received on dolibarr.org and it is important to have a lot of content trusted by Google to have dolibarr.org valorized highly on Google search engine answers.

There is a solution here using a CDN frontend like Fastly: https://meta.discourse.org/t/discourse-in-a-subfolder-multiple-servers-sharing-a-domain/30514 It is based on Fastly, be Dolibarr is using Cloudflare as CDN that may offers same features.

Another solution without CDN, using your own proxy, is suggested here https://meta.discourse.org/t/subfolder-support-with-docker/30507 but previous one seems easier.

=> Yes, it is doable using nginx or Apache2 as a reverse proxy. In fact, I am using nginx as a reverse proxy on the demo instance.

=> With Cloudflare I found this : https://blog.cloudflare.com/subdomains-vs-subdirectories-improved-seo-part-2/

Email requirements

Discourse requires connection to a valid mail server :

  • using SMTP protocol
  • accessible on a FQDN (Fully Qualified Domain Name) : for example forum.dolibarr.fr
  • with authentication (username and password)

Comparison of two possible configurations
In house mail server like Postfix External email service like Mailgun
  • Cheapest
  • Tricky to set/configure
  • Monitoring email reputation is required
  • Affordable
  • Simple and easy (no configuration)
  • Email reputation is managed by the provider

Alternative : https://forum.normandie-libre.fr/t/installation-dun-forum-discourse-avec-apache-docker-et-mailboy/25

Tips and tricks

Discourse tips and tricks

Add an Unreplied tab to the navbar : [1]

Execute migration script

./launcher enter app
# Install required dependencies to import data (gems)
su discourse -c 'export IMPORT=1; bundle install --no-deployment --path vendor/bundle --jobs 4 --without test development'
# Run import script
su discourse -c 'export IMPORT=1; bundle exec ruby script/import_scripts/kunena3.rb'

Restaure Discourse backup from command line

./launcher enter app
su discourse -c 'bundle exec ruby script/discourse restore forum-dolibarr-france-2019-08-07-080937-v20190731090219.tar'

You must of course replace forum-dolibarr-france-2019-08-07-080937-v20190731090219.tar by the backup filename to restore.

Docker tips and tricks

The main and recommended way to Install Discourse is using Docker containers system (it contains everything required to run Discourse : Ruby, Sidekiq, Redis, PostgreSQL with the appropriate version and does not mess with the host data).

The quick start guide is great for installation.

Data that should be preserved when the containers die (PostgreSQL database data files, users uploads, etc.), are persisted on the host.

The default mount point for all persisted data related to Discourse is through


PostgreSQL tips and tricks

Allow PostgreSQL to be accessed from an external application

Useful to be able to access the database from a graphical client (like pgAdmin 4, TablePlus or Postico for example).

1. Expose the 5432 TCP port from the container to the host by adding this line to the expose: section of containers/app.yml :

 - "5432:5432"

2. Rebuild the container to take into account modifications to app.yml :

 ./launcher rebuild app

3. Enter into the container, login as the default postgresql user, add a new user and grant it all perms to the database

 ./launcher enter app
 sudo -u postgres psql discourse
 CREATE USER my_username WITH PASSWORD 'my_password';
 GRANT ALL PRIVILEGES ON DATABASE discourse to my_username;

Refer to PostgreSQL - How to grant access to users? for more info.

Dumping database

Using pg_dump to dump the database

Below syntax assume that a custom pgsql account has been created prior to running the command and that port 5432 of PostgreSQL is correctly forwarded from the container to the host (following #Allow PostgreSQL to be accessed from an external application section instructions).

The below command is executed from the host.

 pg_dump -h -d discourse -U my_username -W > discourse-backup-20190801.sql
Using discourse internal backup tool

It is also possible to use Discourse internal backup tool to grab a backup (database + users uploads) of the Discourse instance.

Just go to Admin → Backup