Installation & déploiement

Hyppo-Compte peut s'installer de trois façons indépendantes. Choisissez celle qui correspond à votre situation :

• Docker — image déjà construite — la plus rapide, sans rien compiler vous-même.
• Docker — construction depuis le code source — fonctionne dans tous les cas, y compris sans image pré-construite accessible.
• App Home Assistant — si vous utilisez déjà Home Assistant, l'application s'intègre directement dans son menu latéral, sans conteneur ni fichier de configuration à gérer séparément.

Docker — image déjà construite

Prérequis

• Un serveur ou une VM Linux avec Docker et le plugin Docker Compose installés.
• Un nom de domaine pointant vers ce serveur si vous comptez exposer l'application sur Internet (voir plus bas).

1. Récupérer le code

git clone https://gitlab.com/koleos_6/hyppo-compte.git
cd hyppo-compte

Ce dépôt fournit les fichiers de configuration (docker-compose.prod.yml, docker/nginx/default.conf...) nécessaires même en récupérant une image déjà construite — ces fichiers ne font pas partie de l'image elle-même.

2. Configurer l'environnement

Copiez le modèle de configuration de production et renseignez vos propres valeurs :

cp .env.production.example .env.production

Le fichier .env.production.example détaille, en commentaire, chaque valeur à renseigner (URL publique, base de données, SMTP...). Générez notamment votre propre clé d'application avant le premier lancement :

docker compose -f docker-compose.prod.yml --env-file .env.production run --rm app php artisan key:generate --show

Reportez la valeur affichée dans APP_KEY= du fichier .env.production.

Ne jamais partager ce fichier

.env.production contient des mots de passe et doit rester local à votre serveur — il est volontairement ignoré par Git.

3. Démarrer l'application

Indiquez l'adresse du registre GitLab du projet Hyppo-Compte et la version voulue, puis démarrez sans reconstruire :

export CI_REGISTRY_IMAGE=<registre GitLab du projet Hyppo-Compte>
export IMAGE_TAG=v1.0.0

docker compose -f docker-compose.prod.yml --env-file .env.production pull
docker compose -f docker-compose.prod.yml --env-file .env.production up -d

Cette commande démarre trois conteneurs : l'application, un serveur web nginx, et la base de données MySQL. Au démarrage, l'application applique automatiquement les migrations de base de données et met en cache sa configuration — aucune commande manuelle supplémentaire n'est nécessaire. L'application est alors accessible sur le port 80 du serveur.

Premiers pas après l'installation

Il n'existe pas de page d'inscription publique : Hyppo-Compte étant destiné à un cercle restreint d'utilisateurs (famille, colocataires...), la création d'un compte se fait uniquement via un lien d'invitation généré par un administrateur. Sur une installation neuve, aucun administrateur n'existe encore — créez donc le tout premier compte en ligne de commande :

docker compose -f docker-compose.prod.yml --env-file .env.production exec app php artisan app:create-first-admin

La commande demande un nom, un email et un mot de passe, et refuse de s'exécuter si un compte existe déjà (elle ne sert qu'une seule fois, pour le tout premier compte).

Connectez-vous ensuite avec ce compte, rendez-vous dans le menu Invitations, et invitez les autres personnes par email. Le lien d'inscription généré est affiché à l'écran, en plus d'être envoyé par email — utile si le SMTP renseigné dans .env.production ne fonctionne pas : il suffit de transmettre ce lien manuellement (par message, par exemple) en attendant de corriger les valeurs MAIL_*.

Mettre à jour vers une nouvelle version

Mettez à jour IMAGE_TAG, puis répétez le pull et le up -d :

export IMAGE_TAG=v1.1.0
docker compose -f docker-compose.prod.yml --env-file .env.production pull
docker compose -f docker-compose.prod.yml --env-file .env.production up -d

La base de données n'est pas affectée par la mise à jour de l'application : elle continue de tourner dans son propre conteneur pendant l'opération.

Sauvegardez avant de mettre à jour

Une mise à jour peut inclure des migrations de base de données. Faites régulièrement une sauvegarde de votre base (docker compose ... exec mysql mysqldump ...) avant toute mise à jour, pour pouvoir revenir en arrière en cas de problème.

Exposer l'application sur Internet

Le conteneur web ne gère que du HTTP en clair sur le port 80. Pour un usage en dehors d'un réseau local, placez un reverse-proxy devant qui gère le certificat HTTPS — par exemple Caddy ou Traefik, tous deux capables de renouveler automatiquement un certificat Let's Encrypt.

Docker — construction depuis le code source

Prérequis

• Un serveur ou une VM Linux avec Docker et le plugin Docker Compose installés.
• Un nom de domaine pointant vers ce serveur si vous comptez exposer l'application sur Internet (voir plus bas).

1. Récupérer le code

git clone https://gitlab.com/koleos_6/hyppo-compte.git
cd hyppo-compte

2. Configurer l'environnement

Copiez le modèle de configuration de production et renseignez vos propres valeurs :

cp .env.production.example .env.production

Le fichier .env.production.example détaille, en commentaire, chaque valeur à renseigner (URL publique, base de données, SMTP...). Générez notamment votre propre clé d'application avant le premier lancement :

docker compose -f docker-compose.prod.yml --env-file .env.production run --rm app php artisan key:generate --show

Reportez la valeur affichée dans APP_KEY= du fichier .env.production.

Ne jamais partager ce fichier

.env.production contient des mots de passe et doit rester local à votre serveur — il est volontairement ignoré par Git.

3. Démarrer l'application

docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build

Cette commande construit l'image localement, sans dépendre d'un registre, puis démarre les trois conteneurs (application, nginx, MySQL). Au démarrage, l'application applique automatiquement les migrations de base de données et met en cache sa configuration. L'application est alors accessible sur le port 80 du serveur.

Premiers pas après l'installation

Il n'existe pas de page d'inscription publique : Hyppo-Compte étant destiné à un cercle restreint d'utilisateurs (famille, colocataires...), la création d'un compte se fait uniquement via un lien d'invitation généré par un administrateur. Sur une installation neuve, aucun administrateur n'existe encore — créez donc le tout premier compte en ligne de commande :

docker compose -f docker-compose.prod.yml --env-file .env.production exec app php artisan app:create-first-admin

La commande demande un nom, un email et un mot de passe, et refuse de s'exécuter si un compte existe déjà (elle ne sert qu'une seule fois, pour le tout premier compte).

Connectez-vous ensuite avec ce compte, rendez-vous dans le menu Invitations, et invitez les autres personnes par email. Le lien d'inscription généré est affiché à l'écran, en plus d'être envoyé par email — utile si le SMTP renseigné dans .env.production ne fonctionne pas : il suffit de transmettre ce lien manuellement (par message, par exemple) en attendant de corriger les valeurs MAIL_*.

Mettre à jour vers une nouvelle version

git pull
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build

La base de données n'est pas affectée par la mise à jour de l'application : elle continue de tourner dans son propre conteneur pendant l'opération.

Sauvegardez avant de mettre à jour

Une mise à jour peut inclure des migrations de base de données. Faites régulièrement une sauvegarde de votre base (docker compose ... exec mysql mysqldump ...) avant toute mise à jour, pour pouvoir revenir en arrière en cas de problème.

Exposer l'application sur Internet

Le conteneur web ne gère que du HTTP en clair sur le port 80. Pour un usage en dehors d'un réseau local, placez un reverse-proxy devant qui gère le certificat HTTPS — par exemple Caddy ou Traefik, tous deux capables de renouveler automatiquement un certificat Let's Encrypt.

App Home Assistant

Si votre instance Home Assistant tourne déjà (Supervisor requis — HAOS ou installation Supervised, pas Home Assistant Core seul), Hyppo-Compte peut s'installer comme une app supplémentaire, directement intégrée au menu latéral. Aucun conteneur à gérer manuellement, aucun fichier .env à éditer : la configuration se fait entièrement depuis l'interface de HA.

Prérequis

Cette app ne contient pas de serveur de base de données : elle s'appuie sur l'app communautaire MariaDB, à installer et démarrer au préalable (dépôt d'apps officiel Home Assistant).

Une fois MariaDB installé, créez une base et un utilisateur dédiés pour Hyppo-Compte, par exemple depuis l'onglet de configuration de l'app MariaDB :

databases:
  - hyppo_compte
logins:
  - username: hyppo_compte
    password: choisissez-un-mot-de-passe-solide
rights:
  - username: hyppo_compte
    database: hyppo_compte

Installation

1. Dans Home Assistant : Paramètres → Apps → Boutique d'apps, menu ⋮ en haut à droite → Dépôts, ajoutez l'URL de ce dépôt (https://gitlab.com/koleos_6/hyppo-compte).
2. Installez l'app Hyppo-Compte qui apparaît alors dans la liste.
3. Dans l'onglet Configuration de l'app, renseignez db_host (core-mariadb par défaut), db_database, db_username, db_password avec les valeurs créées à l'étape précédente.
4. Démarrez l'app. Elle apparaît ensuite dans le menu latéral.

Premiers pas

Contrairement aux installations Docker, aucune étape manuelle n'est nécessaire : ouvrez simplement l'application depuis le menu latéral. Le compte est créé automatiquement à partir de votre identité Home Assistant, dès la première ouverture — pas de mot de passe, pas d'inscription, pas d'invitation à gérer. La première personne à ouvrir l'application devient automatiquement administratrice ; toute autre personne connectée à cette même instance Home Assistant qui ouvre ensuite l'application obtient son propre compte, sans droits d'administration par défaut.

L'application est visible dans le menu latéral de tous les utilisateurs Home Assistant, pas seulement des administrateurs (chacun peut masquer cette entrée depuis son profil). Un compte n'existant qu'à la première ouverture, quelqu'un qui n'a jamais ouvert l'application n'apparaît dans aucune liste de partage : pour lui partager un compte ou un budget, demandez-lui de l'ouvrir une première fois. Jusqu'à la version 1.3.0, l'entrée n'était visible que des administrateurs : après la mise à jour de l'app, rechargez la page Home Assistant pour la voir apparaître chez les autres utilisateurs.

Mettre à jour

Une mise à jour se fait comme pour n'importe quelle autre app Home Assistant : depuis sa page dans Paramètres → Apps, un bouton de mise à jour apparaît dès qu'une nouvelle version est publiée sur ce dépôt.

Sauvegardes

Les données de l'application elles-mêmes (comptes, opérations, catégories) vivent dans la base MariaDB — sauvegardez-la comme n'importe quelle autre base gérée par cette app. Les fichiers déposés dans l'application (logos de banques, imports) sont stockés dans le dossier /data de cette app, inclus dans les sauvegardes Home Assistant standard.