Hyppo-Compte

English

Français

English

Français

Appearance

Installation & deployment ​

Hyppo-Compte can be installed in three independent ways. Choose the one that fits your situation:

Docker — pre-built image ​

Prerequisites ​

  • A Linux server or VM with Docker and the Docker Compose plugin installed.
  • A domain name pointing to this server if you plan to expose the application on the Internet (see below).

1. Get the code ​

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

This repository provides the configuration files (docker-compose.prod.yml, docker/nginx/default.conf...) needed even when using a pre-built image — these files aren't part of the image itself.

2. Configure the environment ​

Copy the production configuration template and fill in your own values:

bash
cp .env.production.example .env.production

The .env.production.example file documents, in comments, every value to fill in (public URL, database, SMTP...). In particular, generate your own application key before the first launch:

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

Put the displayed value into APP_KEY= in the .env.production file.

Never share this file

.env.production contains passwords and must stay local to your server — it is deliberately ignored by Git.

3. Start the application ​

Set the GitLab registry address for the Hyppo-Compte project and the desired version, then start without rebuilding:

bash
export CI_REGISTRY_IMAGE=<Hyppo-Compte project's GitLab registry>
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

This command starts three containers: the application, an nginx web server, and the MySQL database. On startup, the application automatically applies database migrations and caches its configuration — no additional manual command is needed. The application is then accessible on port 80 of the server.

First steps after installation ​

There is no public registration page: since Hyppo-Compte is meant for a small circle of users (family, roommates...), an account can only be created via an invitation link generated by an administrator. On a fresh installation, no administrator exists yet — so create the very first account from the command line:

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

The command asks for a name, an email and a password, and refuses to run if an account already exists (it's only meant to be used once, for the very first account).

Then log in with this account, go to the Invitations menu, and invite other people by email. The generated registration link is shown on screen, in addition to being emailed — useful if the SMTP settings in .env.production don't work: you can simply pass this link along manually (by message, for example) until you fix the MAIL_* values.

Updating to a new version ​

Update IMAGE_TAG, then repeat the pull and up -d:

bash
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

The database is not affected by the application update: it keeps running in its own container throughout the operation.

Back up before updating

An update may include database migrations. Regularly back up your database (docker compose ... exec mysql mysqldump ...) before any update, so you can roll back in case of a problem.

Exposing the application on the Internet ​

The web container only handles plain HTTP on port 80. For use outside a local network, put a reverse proxy in front that handles the HTTPS certificate — for example Caddy or Traefik, both able to automatically renew a Let's Encrypt certificate.

Docker — building from source ​

Prerequisites ​

  • A Linux server or VM with Docker and the Docker Compose plugin installed.
  • A domain name pointing to this server if you plan to expose the application on the Internet (see below).

1. Get the code ​

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

2. Configure the environment ​

Copy the production configuration template and fill in your own values:

bash
cp .env.production.example .env.production

The .env.production.example file documents, in comments, every value to fill in (public URL, database, SMTP...). In particular, generate your own application key before the first launch:

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

Put the displayed value into APP_KEY= in the .env.production file.

Never share this file

.env.production contains passwords and must stay local to your server — it is deliberately ignored by Git.

3. Start the application ​

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

This command builds the image locally, without relying on a registry, then starts the three containers (application, nginx, MySQL). On startup, the application automatically applies database migrations and caches its configuration. The application is then accessible on port 80 of the server.

First steps after installation ​

There is no public registration page: since Hyppo-Compte is meant for a small circle of users (family, roommates...), an account can only be created via an invitation link generated by an administrator. On a fresh installation, no administrator exists yet — so create the very first account from the command line:

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

The command asks for a name, an email and a password, and refuses to run if an account already exists (it's only meant to be used once, for the very first account).

Then log in with this account, go to the Invitations menu, and invite other people by email. The generated registration link is shown on screen, in addition to being emailed — useful if the SMTP settings in .env.production don't work: you can simply pass this link along manually (by message, for example) until you fix the MAIL_* values.

Updating to a new version ​

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

The database is not affected by the application update: it keeps running in its own container throughout the operation.

Back up before updating

An update may include database migrations. Regularly back up your database (docker compose ... exec mysql mysqldump ...) before any update, so you can roll back in case of a problem.

Exposing the application on the Internet ​

The web container only handles plain HTTP on port 80. For use outside a local network, put a reverse proxy in front that handles the HTTPS certificate — for example Caddy or Traefik, both able to automatically renew a Let's Encrypt certificate.

Home Assistant app ​

If your Home Assistant instance is already running (Supervisor required — HAOS or a Supervised installation, not Home Assistant Core alone), Hyppo-Compte can be installed as an additional app, integrated directly into the sidebar. No container to manage manually, no .env file to edit: the configuration is done entirely from the HA interface.

Prerequisites ​

This app doesn't include a database server: it relies on the community MariaDB app, which must be installed and started beforehand (official Home Assistant app store).

Once MariaDB is installed, create a dedicated database and user for Hyppo-Compte, for example from the MariaDB app's configuration tab:

yaml
databases:
  - hyppo_compte
logins:
  - username: hyppo_compte
    password: choose-a-strong-password
rights:
  - username: hyppo_compte
    database: hyppo_compte

Installation ​

  1. In Home Assistant: Settings → Add-ons → Add-on store, ⋮ menu in the top right → Repositories, add this repository's URL (https://gitlab.com/koleos_6/hyppo-compte).
  2. Install the Hyppo-Compte app, which then appears in the list.
  3. In the app's Configuration tab, fill in db_host (core-mariadb by default), db_database, db_username, db_password with the values created in the previous step.
  4. Start the app. It then appears in the sidebar.

First steps ​

Unlike Docker installations, no manual step is needed: simply open the application from the sidebar. The account is created automatically from your Home Assistant identity, on first opening — no password, no registration, no invitation to manage. The first person to open the application automatically becomes an administrator; any other person logged into that same Home Assistant instance who then opens the application gets their own account, without administrator rights by default.

The application is visible in the sidebar of all Home Assistant users, not only administrators (everyone can hide that entry from their profile). Since an account only exists from the first opening, someone who has never opened the application appears in no sharing list: to share an account or a budget with them, ask them to open it once. Up to version 1.3.0, the entry was only visible to administrators: after updating the app, reload the Home Assistant page to see it appear for the other users.

Updating ​

An update works like for any other Home Assistant app: from its page under Settings → Add-ons, an update button appears as soon as a new version is published to this repository.

Backups ​

The application's own data (accounts, operations, categories) lives in the MariaDB database — back it up like any other database managed by that app. Files uploaded within the application (bank logos, imports) are stored in this app's /data folder, included in standard Home Assistant backups.