Ghostfolio : fonctionnalités, installation Docker, imports et sauvegarde

Quand on détient un PEA dans une banque, un compte-titres chez un courtier en ligne, de l’épargne salariale et quelques cryptomonnaies, plus personne ne sait répondre simplement à la question : « combien ai-je, où, et est-ce bien réparti ? ». Ghostfolio est un tableau de bord patrimonial open source qui consolide ces actifs, calcule la performance réelle, détecte les déséquilibres et suit les dividendes. Ce guide présente ses fonctionnalités en détail, puis l’installation auto-hébergée complète, la saisie des données, les imports, la maintenance et la restauration.

1. Ghostfolio en bref

Ghostfolio est un logiciel de gestion de patrimoine développé en TypeScript (Angular pour l’interface, NestJS pour l’API, PostgreSQL pour les données et Redis pour le cache). Il est publié sous licence AGPL-3.0. Deux modes d’utilisation existent :

Ce guide traite de l’auto-hébergement. Les données financières font partie des plus sensibles qui soient : les garder chez soi, derrière un reverse proxy maîtrisé, est précisément l’intérêt de la démarche.

2. Ce que Ghostfolio fait… et ne fait pas

Avant d’installer quoi que ce soit, il faut comprendre le positionnement de l’outil, sinon on finit par lui demander ce qu’il ne sait pas faire.

3. Tour d’horizon des fonctionnalités

3.1 Vue d’ensemble

L’écran d’accueil affiche la valeur nette, la performance du jour, le graphique d’évolution et plusieurs plages de temps : aujourd’hui, depuis le début de l’année, 1 an, 5 ans et depuis l’origine. Le mode Zen masque les montants et ne conserve que les pourcentages, pratique pour consulter son portefeuille en public ou pour s’empêcher de réagir aux variations quotidiennes.

3.2 Positions (holdings)

Chaque actif détenu apparaît avec sa quantité, sa valeur, son poids dans le portefeuille et sa performance. Un clic ouvre la fiche détaillée : historique des transactions, prix moyen d’achat, dividendes perçus et graphique de cours.

3.3 Allocations

C’est la fonctionnalité qui justifie souvent à elle seule l’adoption de l’outil. Ghostfolio ventile le portefeuille selon plusieurs axes :

• Classe d’actifs : actions, obligations, liquidités, matières premières, cryptomonnaies, immobilier ;
• Compte et plateforme : exposition par établissement, utile pour mesurer le risque de contrepartie ;
• Devise : part du patrimoine exposée au dollar, à la livre ou au franc suisse ;
• Pays, régions et marchés : marchés développés, émergents, États-Unis ;
• Secteurs : technologie, santé, finance, etc. ;
• Symboles : poids individuel de chaque ligne.

3.4 Analyse et performance

La page d’analyse compare l’évolution du portefeuille à un indice de référence, détaille les meilleures et les pires positions et présente les investissements par période. On visualise immédiatement si les apports réguliers ont été tenus et comment la valeur a évolué indépendamment de ces apports.

3.5 X-ray : l’analyse statique des risques

X-ray passe le portefeuille au crible de règles simples : concentration excessive sur un compte, une devise ou une classe d’actifs, frais trop élevés par rapport aux montants investis, liquidités en excès ou insuffisantes. Chaque règle est notée et peut être ajustée. C’est un excellent garde-fou contre la dérive progressive d’une allocation.

3.6 FIRE : projection vers l’indépendance financière

Le calculateur FIRE projette le capital dans le temps selon un taux d’épargne et un rendement annuel hypothétiques, et estime le revenu qu’une règle de retrait de 4 % permettrait de tirer du portefeuille. C’est un outil de réflexion, pas une promesse : les hypothèses de rendement doivent rester prudentes.

3.7 Activités

Toutes les transactions sont listées dans la page Activités : achats, ventes, dividendes, intérêts, frais, passifs et biens de valeur. C’est ici que l’on saisit, importe, exporte et corrige les données. La qualité de tout le reste dépend de cette page.

3.8 Fonctions complémentaires

• Watchlist pour suivre des actifs non détenus ;
• Multi-utilisateurs : chaque membre du foyer a son propre portefeuille ;
• Accès partagé en lecture seule ou en mode public, par exemple pour un conseiller ;
• Mode sombre et interface disponible en français ;
• Export JSON complet des activités ;
• API pour automatiser l’import depuis des scripts.

4. Architecture de l’installation

Internet
   │  HTTPS
   ▼
Cloudflare Tunnel / Traefik ── réseau Docker « proxy-public »
   │
   ▼
ghostfolio:3333 ──────────── réseau interne « ghostfolio-internal »
   ├── postgres:5432   données : comptes, activités, utilisateurs
   └── redis:6379      cache et files de tâches (collecte des cours)

Ressources observées pour un usage familial : environ 500 Mo à 1 Go de RAM pour l’ensemble, très peu de CPU hors collecte des cours, et quelques centaines de Mo de disque pour PostgreSQL.

5. Prérequis

• Un hôte Docker avec Docker Engine et le plugin Compose à jour ;
• Un reverse proxy fonctionnel (Traefik dans cet article) et un réseau externe partagé, ici proxy-public ;
• Un nom de domaine dédié, par exemple finance.exemple.net, avec certificat valide ;
• Un emplacement de sauvegarde situé hors de l’hôte.

6. Préparer les secrets

Le fichier d’exemple officiel .env.example définit les variables nécessaires. Toutes les valeurs sensibles doivent être générées aléatoirement.

mkdir -p /opt/stacks/ghostfolio
cd /opt/stacks/ghostfolio

cat > .env <<EOF
COMPOSE_PROJECT_NAME=ghostfolio

# CACHE
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=$(openssl rand -hex 32)

# POSTGRES
POSTGRES_DB=ghostfolio-db
POSTGRES_USER=ghostfolio
POSTGRES_PASSWORD=$(openssl rand -hex 32)

# VARIOUS
ACCESS_TOKEN_SALT=$(openssl rand -hex 32)
JWT_SECRET_KEY=$(openssl rand -hex 32)
EOF

# DATABASE_URL est ajoutée ensuite pour que le shell ne remplace pas les variables
echo 'DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?connect_timeout=300' >> .env

chmod 600 .env

7. Le fichier Compose

Le fichier ci-dessous s’appuie sur le Compose officiel du dépôt Ghostfolio, avec trois adaptations : aucun port publié sur l’hôte, deux réseaux séparés et des données stockées dans le dossier de la stack pour simplifier les sauvegardes.

cat > compose.yaml <<'EOF'
name: ghostfolio

services:
  ghostfolio:
    image: docker.io/ghostfolio/ghostfolio:latest
    container_name: ghostfolio
    restart: unless-stopped
    init: true
    stop_grace_period: 1m
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - proxy-public
      - ghostfolio-internal
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3333/api/v1/health"]
      interval: 10s
      timeout: 5s
      retries: 5

  postgres:
    image: docker.io/library/postgres:15-alpine
    container_name: gf-postgres
    restart: unless-stopped
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_READ_SEARCH
      - FOWNER
      - SETGID
      - SETUID
    security_opt:
      - no-new-privileges:true
    env_file:
      - .env
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - ghostfolio-internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d \"$${POSTGRES_DB}\" -U $${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: docker.io/library/redis:8-alpine
    container_name: gf-redis
    restart: unless-stopped
    user: "999:1000"
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    env_file:
      - .env
    command:
      - /bin/sh
      - -c
      - redis-server --requirepass "$${REDIS_PASSWORD:?REDIS_PASSWORD variable is not set}"
    networks:
      - ghostfolio-internal
    healthcheck:
      test: ["CMD-SHELL", "redis-cli --pass \"$${REDIS_PASSWORD}\" ping | grep PONG"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  proxy-public:
    external: true
  ghostfolio-internal:
    internal: true
EOF

Lecture des choix

• cap_drop: ALL et no-new-privileges : les conteneurs démarrent sans aucune capacité Linux superflue. PostgreSQL récupère uniquement celles dont il a besoin pour gérer ses fichiers.
• $${...} : le double dollar empêche Compose de remplacer la variable ; c’est le shell du conteneur qui la lit au démarrage.
• condition: service_healthy : Ghostfolio attend que PostgreSQL et Redis répondent réellement avant de démarrer, ce qui évite les erreurs de migration au premier lancement.
• Réseau internal : PostgreSQL et Redis ne sont joignables ni depuis Traefik ni depuis l’extérieur.
• stop_grace_period: 1m : laisse le temps à l’application de terminer proprement ses tâches.

8. Premier démarrage

mkdir -p data/postgres
docker compose config --quiet && echo "Compose valide"
docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f ghostfolio

Au premier lancement, Ghostfolio applique ses migrations Prisma puis démarre l’API. Dans les journaux, on doit voir l’application écouter sur le port 3333. Attendez que les trois conteneurs soient healthy :

NAME          STATUS
ghostfolio    Up 2 minutes (healthy)
gf-postgres   Up 2 minutes (healthy)
gf-redis      Up 2 minutes (healthy)

9. Publier derrière Traefik

# Configuration dynamique Traefik
http:
  routers:
    ghostfolio:
      rule: "Host(`finance.exemple.net`)"
      entryPoints:
        - websecure
      service: ghostfolio
      tls: {}
  services:
    ghostfolio:
      loadBalancer:
        servers:
          - url: "http://ghostfolio:3333"

Contrôle depuis Traefik, avant même d’ouvrir un navigateur :

docker exec traefik wget -qO- http://ghostfolio:3333/api/v1/health
# Réponse attendue : {"status":"OK"}

10. Créer le compte administrateur

Ghostfolio n’utilise pas de couple identifiant / mot de passe classique. À l’inscription, l’application génère un jeton de sécurité qui sert ensuite à se connecter. Le premier compte créé sur une instance auto-hébergée devient administrateur.

1. Ouvrir https://finance.exemple.net et choisir Démarrer.
2. Copier immédiatement le jeton de sécurité affiché et l’enregistrer dans un gestionnaire de mots de passe.
3. Accepter les conditions et accéder au tableau de bord vide.
4. Ouvrir Mon Ghostfolio → Paramètres et choisir la langue française, la devise de référence EUR et le format de date.
5. Dans Admin Control → Paramètres, désactiver l’inscription des nouveaux utilisateurs une fois les comptes du foyer créés.

11. Modéliser plateformes et comptes

C’est l’étape la plus importante, et celle que l’on regrette le plus d’avoir bâclée. Ghostfolio distingue deux notions :

• La plateforme : l’établissement qui détient vos avoirs (banque, courtier, teneur de compte d’épargne salariale, plateforme crypto) ;
• Le compte : une enveloppe précise ouverte dans cet établissement (PEA, CTO, PEE, livret, portefeuille crypto).

Cette organisation permet d’obtenir à la fois une vue par enveloppe fiscale et une vue par établissement. La seconde est souvent négligée : elle révèle par exemple que 80 % du patrimoine dépend d’un seul courtier.

12. Comprendre les types d’activités

Les frais de courtage d’un achat se saisissent dans le champ frais de l’activité BUY, pas comme une activité FEE séparée : sinon ils seraient comptés deux fois.

13. Sources de données et symboles

Chaque actif est associé à une source de données qui fournit son cours :

Cas de l’épargne salariale

Les fonds de PEE et PERCO n’ont généralement pas de cours public exploitable. Créez l’actif en source MANUAL, saisissez les achats avec la valeur liquidative de la date d’investissement, puis renseignez régulièrement la valeur liquidative dans Admin Control → Données de marché. Pour l’abondement employeur, une convention simple consiste à le saisir comme un achat dont le prix est réel mais dont l’apport ne provient pas de vous ; notez votre convention et appliquez-la toujours de la même façon.

14. Saisir ou importer les activités

14.1 Saisie manuelle

Pour quelques lignes, le bouton + de la page Activités suffit : choisir le type, rechercher l’actif, puis saisir date, quantité, prix unitaire, frais et compte.

14.2 Import CSV

Pour un historique important, l’import CSV est bien plus rapide. Le format reconnu est celui du fichier d’exemple officiel test/import/ok.csv du dépôt Ghostfolio :

Date,Code,DataSource,Currency,Price,Quantity,Action,Fee,Note
2024-01-15,CW8.PA,YAHOO,EUR,480.25,4,buy,1.99,Achat mensuel PEA
2024-02-15,CW8.PA,YAHOO,EUR,495.10,4,buy,1.99,Achat mensuel PEA
2024-03-20,AAPL,YAHOO,USD,172.30,5,buy,2.50,CTO
2024-05-16,AAPL,YAHOO,USD,0.25,5,dividend,0,Dividende trimestriel
2024-06-10,bitcoin,COINGECKO,EUR,62000,0.01,buy,1.20,Achat crypto

Le séparateur décimal doit être un point et le fichier encodé en UTF-8. L’export d’un courtier français utilise souvent le point-virgule, la virgule décimale et des dates françaises : un petit script de conversion est presque toujours nécessaire.

14.3 Convertir un export de courtier

#!/usr/bin/env python3
# Conversion d'un export CSV de courtier (format français) vers le format Ghostfolio.
# Adaptez le dictionnaire COLONNES et TYPES aux libellés de votre courtier.
import csv, sys
from datetime import datetime

COLONNES = {"date": "Date opération", "isin": "ISIN", "type": "Sens",
            "quantite": "Quantité", "prix": "Cours", "frais": "Frais"}
TYPES = {"Achat": "buy", "Vente": "sell", "Dividende": "dividend"}
SYMBOLES = {"FR0010315770": "CW8.PA"}   # ISIN -> symbole Yahoo

def nombre(texte):
    return float(texte.replace("\u00a0", "").replace(" ", "").replace(",", ".") or 0)

source, cible = sys.argv[1], sys.argv[2]
with open(source, encoding="utf-8-sig") as f, open(cible, "w", newline="", encoding="utf-8") as g:
    lecteur = csv.DictReader(f, delimiter=";")
    ecrivain = csv.writer(g)
    ecrivain.writerow(["Date", "Code", "DataSource", "Currency", "Price", "Quantity", "Action", "Fee", "Note"])
    for ligne in lecteur:
        isin = ligne[COLONNES["isin"]].strip()
        if isin not in SYMBOLES or ligne[COLONNES["type"]] not in TYPES:
            print(f"Ignoré : {ligne}", file=sys.stderr)
            continue
        date = datetime.strptime(ligne[COLONNES["date"]], "%d/%m/%Y").strftime("%Y-%m-%d")
        ecrivain.writerow([date, SYMBOLES[isin], "YAHOO", "EUR",
                           nombre(ligne[COLONNES["prix"]]), abs(nombre(ligne[COLONNES["quantite"]])),
                           TYPES[ligne[COLONNES["type"]]], nombre(ligne[COLONNES["frais"]]), isin])

Le script affiche toutes les lignes ignorées : aucune ligne ne doit disparaître silencieusement entre l’export du courtier et l’import Ghostfolio.

14.4 Méthode d’import sans regret

1. Faire une sauvegarde PostgreSQL juste avant l’import (section 18).
2. Importer un premier fichier de cinq lignes seulement.
3. Vérifier dans la boîte de dialogue d’import l’aperçu proposé : actifs reconnus, devises, comptes.
4. Après validation, contrôler les positions concernées.
5. Importer ensuite le reste, compte par compte, en commençant par le plus simple.
6. Après chaque compte, comparer les quantités avec le dernier relevé du courtier.

15. Cryptomonnaies

• Utilisez la source COINGECKO et l’identifiant CoinGecko, pas le ticker : plusieurs jetons partagent le même ticker.
• Un transfert entre deux portefeuilles qui vous appartiennent ne doit pas créer un nouvel achat : la quantité totale ne change pas, seul le compte change.
• Les récompenses de staking peuvent être saisies comme un achat à prix nul ou comme des intérêts, selon la façon dont vous voulez mesurer la performance : choisissez une convention et notez-la.
• Les frais réseau payés en crypto diminuent la quantité détenue ; contrôlez la quantité finale par actif.

16. Devises et taux de change

La devise de référence (EUR) sert à l’affichage global ; chaque actif conserve sa devise de cotation. Ghostfolio convertit en utilisant les taux de change historiques. Si une erreur indique qu’aucun taux de change n’a été trouvé pour une date, les cours de la paire concernée n’ont pas encore été collectés.

1. Ouvrir Admin Control → Données de marché.
2. Filtrer sur les devises.
3. Sélectionner la paire concernée, par exemple EURUSD.
4. Lancer la collecte des données historiques.
5. Patienter quelques minutes, puis recharger le portefeuille.

17. Contrôler la qualité des données

La performance affichée n’est pas un bon indicateur de qualité : elle dépend de trop de paramètres. Les contrôles fiables sont ailleurs :

18. Sauvegarder

La donnée critique est la base PostgreSQL. Redis n’est qu’un cache et se reconstruit seul. Le fichier .env doit accompagner chaque sauvegarde : sans lui, impossible de reconnecter les utilisateurs.

#!/usr/bin/env bash
# /opt/stacks/ghostfolio/backup-ghostfolio.sh
set -Eeuo pipefail

STACK=/opt/stacks/ghostfolio
DEST=/srv/backups/ghostfolio
STAMP=$(date +%Y%m%d-%H%M%S)
RETENTION_DAYS=30

cd "$STACK"
set -a; . ./.env; set +a
mkdir -p "$DEST"

docker compose exec -T postgres \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom \
  > "$DEST/ghostfolio-db-$STAMP.dump"

tar -czf "$DEST/ghostfolio-config-$STAMP.tar.gz" compose.yaml .env
chmod 600 "$DEST"/ghostfolio-*-"$STAMP".*

# Vérification minimale : le dump doit être lisible
docker compose exec -T postgres pg_restore --list < "$DEST/ghostfolio-db-$STAMP.dump" > /dev/null \
  && echo "Sauvegarde valide : ghostfolio-db-$STAMP.dump"

find "$DEST" -type f -mtime +"$RETENTION_DAYS" -delete

chmod 750 /opt/stacks/ghostfolio/backup-ghostfolio.sh
echo '30 2 * * * root /opt/stacks/ghostfolio/backup-ghostfolio.sh >> /var/log/backup-ghostfolio.log 2>&1' \
  > /etc/cron.d/backup-ghostfolio

19. Restaurer

cd /opt/stacks/ghostfolio
docker compose stop ghostfolio

# Base vide, puis restauration
docker compose exec -T postgres dropdb   -U ghostfolio ghostfolio-db
docker compose exec -T postgres createdb -U ghostfolio ghostfolio-db
docker compose exec -T postgres pg_restore -U ghostfolio -d ghostfolio-db --no-owner \
  < /srv/backups/ghostfolio/ghostfolio-db-AAAAMMJJ-HHMMSS.dump

docker compose start ghostfolio
docker compose logs --tail 50 ghostfolio

1. Restaurer le .env d’origine avant de démarrer la stack.
2. Démarrer PostgreSQL et Redis, puis restaurer le dump.
3. Démarrer Ghostfolio : les migrations éventuelles s’appliquent.
4. Se connecter avec le jeton de sécurité habituel.
5. Comparer quelques quantités et la valeur totale avec l’état connu.

20. Mettre à jour

1. Lire le CHANGELOG.md du dépôt pour repérer les changements importants.
2. Lancer le script de sauvegarde.
3. Modifier le tag de l’image si la version est figée.
4. Exécuter docker compose pull && docker compose up -d.
5. Surveiller docker compose logs -f ghostfolio jusqu’à l’état healthy.
6. Vérifier la valeur totale et une fiche d’actif.

Les mises à jour appliquent parfois des migrations du schéma PostgreSQL. Revenir à l’ancienne image sans restaurer la base peut alors échouer : c’est pourquoi la sauvegarde précède toujours la mise à jour. Pour PostgreSQL lui-même, un changement de version majeure (15 vers 16, par exemple) nécessite un export et une réimportation, pas un simple changement de tag.

21. Pièges fréquemment rencontrés

• Perdre ACCESS_TOKEN_SALT ou le jeton de sécurité administrateur.
• Modifier POSTGRES_PASSWORD après l’initialisation de la base.
• Confondre plateforme et compte, puis devoir tout réorganiser.
• Choisir un actif uniquement par son ticker, sur la mauvaise place de cotation.
• Saisir les frais à la fois dans l’achat et dans une activité FEE.
• Créer un achat pour un simple transfert de crypto entre ses propres portefeuilles.
• Réimporter un fichier corrigé sans supprimer le premier import.
• Sauvegarder Redis et oublier PostgreSQL.
• Monter PostgreSQL d’une version majeure en changeant simplement le tag.

22. Checklist de validation

• Les trois conteneurs sont healthy.
• Aucun port n’est publié sur l’hôte ; PostgreSQL et Redis sont sur un réseau interne.
• Le jeton administrateur et le fichier .env sont sauvegardés de manière chiffrée.
• L’inscription publique est désactivée.
• Chaque enveloppe est un compte distinct, rattaché à la bonne plateforme.
• Les quantités finales correspondent aux relevés.
• Aucun actif n’apparaît sans cours dans les données de marché.
• La sauvegarde quotidienne fonctionne et une restauration a été testée.

Sources officielles

• Dépôt officiel Ghostfolio (code, README, licence AGPL-3.0)
• Fichier Compose officiel
• Fichier .env.example officiel
• Exemple officiel de fichier d’import CSV
• Compte de démonstration officiel

Conclusion

Ghostfolio apporte une vision consolidée que ni les banques ni les courtiers ne fournissent, parce que chacun ne voit que sa propre partie du patrimoine. Sa valeur dépend toutefois entièrement de la qualité des données : une modélisation claire des plateformes et des comptes, des imports réalisés par petits lots, des quantités vérifiées et une sauvegarde testée transforment un tableau de bord séduisant en véritable outil de décision.