Installer sur un serveur

Cette page est prévue pour être suivie de bout en bout, sans rien deviner. Elle installe Kewos ERP sur un serveur Linux, en service permanent, derrière votre proxy.

Avant de commencer

Vous avez besoin de votre jeton de licence, de vos identifiants de téléchargement et de la clé publique de licence. Les trois vous sont remis ensemble. Si vous ne les avez pas, commencez par Obtenir une licence.

Ce qu’il vous faut

Système	Debian 12 / 13, Ubuntu 22.04 / 24.04, ou équivalent 64 bits.
Processeur	4 cœurs pour démarrer.
Mémoire	8 Go. Comptez 16 Go au-delà de vingt utilisateurs simultanés.
Disque	20 Go pour le produit, plus la place de vos pièces jointes et de vos sauvegardes.
Base de données	PostgreSQL 16 ou 17.
File d’attente	Redis 6 ou plus.
Réseau	Un nom de domaine et un proxy qui termine le TLS.

Les paquets système

sudo apt update
sudo apt install -y postgresql redis-server ca-certificates curl

Le rendu des documents PDF s’appuie sur quelques bibliothèques natives :

sudo apt install -y libpango-1.0-0 libpangoft2-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 \
                    libffi8 shared-mime-info fonts-dejavu-core

Sans elles, l’application démarre, et l’impression d’un document échoue au moment où quelqu’un en a besoin. Installez-les maintenant.

La lecture de documents (facultatif)

Si vos utilisateurs déposent des factures ou des bons de livraison scannés et que vous voulez en extraire le texte sans envoyer les documents nulle part :

sudo apt install -y tesseract-ocr tesseract-ocr-fra poppler-utils

tesseract-ocr lit les images, la donnée de langue se choisit par langue (-fra, -deu, à adapter), et poppler-utils fournit pdftoppm, qui transforme un PDF scanné en images avant lecture.

C’est facultatif à dessein. Sans ces paquets, l’application tourne exactement pareil : les moteurs correspondants ne s’enregistrent pas, l’écran Réglages → Intégrations → Lecture de documents ne les propose pas, et rien n’échoue au premier clic. Un PDF qui porte déjà une couche de texte (une facture produite par un logiciel de comptabilité, une facture électronique) se lit sans aucun de ces paquets, exactement, et c’est le cas le plus fréquent.

1. Le compte de service et l’arborescence

L’application ne tourne jamais en root.

sudo useradd --system --home-dir /opt/kewos --shell /usr/sbin/nologin kewos

sudo mkdir -p /opt/kewos /etc/kewos /var/lib/kewos/storage /var/log/kewos
sudo chown -R kewos:kewos /opt/kewos /var/lib/kewos /var/log/kewos
sudo chmod 750 /etc/kewos

Chemin	Contenu
/opt/kewos/current	La version en service (un lien vers /opt/kewos/releases/<version>).
/opt/kewos/releases/	Les versions installées. On en garde deux ou trois pour pouvoir revenir.
/etc/kewos/kewos.env	La configuration. Contient des secrets : root:kewos, mode 640.
/etc/kewos/license.token	Votre jeton de licence.
/var/lib/kewos/storage	Les pièces jointes et les documents générés. À sauvegarder.
/var/log/kewos	Les journaux.

2. La base de données

Le rôle a besoin du droit CREATEDB : l’application crée sa base et, en multi-société avancé, celles des entités supplémentaires.

sudo -u postgres psql <<'SQL'
CREATE ROLE kewos LOGIN PASSWORD 'a-long-random-password' CREATEDB;
CREATE DATABASE kewos OWNER kewos;
SQL

Vérifiez la connexion avant d’aller plus loin :

PGPASSWORD='a-long-random-password' psql -h 127.0.0.1 -U kewos -d kewos -c 'select 1'

Sauvegardez tout de suite

Ajoutez la base à votre plan de sauvegarde maintenant, avant la première donnée réelle. Voir Mettre en service.

3. Récupérer votre version

Kewos se livre en une archive .zip qui contient tout : le binaire de l’application (l’API et l’interface dans un seul processus), l’interface construite, l’arborescence des modules, un docker-compose pour Postgres et Redis, un modèle de configuration, et un installateur. Aucun Python, aucun Node, aucune chaîne de compilation n’est requis sur la machine cible.

Kewos vous remet un identifiant et un mot de passe de téléchargement avec votre licence. Ils ne servent qu’à ça, et ils ne sont pas vos identifiants d’application.

cd /tmp
curl -u '<votre-identifiant>' -O https://download.kewos.io/erp/kewos-<version>.zip
curl -u '<votre-identifiant>' -O https://download.kewos.io/erp/kewos-<version>.zip.sha256

curl demande le mot de passe : ne l’écrivez pas dans la commande, il resterait dans l’historique de votre shell.

Vérifiez l’empreinte avant de déployer. Un paquet qui ne correspond pas à la sienne n’est pas un paquet Kewos.

sha256sum -c kewos-<version>.zip.sha256
# kewos-<version>.zip: OK

unzip -q kewos-<version>.zip
cd kewos-<version>

Le répertoire ne s’explore pas

Vous téléchargez la version que Kewos vous a nommée. Il n’y a pas de listing : le catalogue des versions n’est pas public, et une URL de répertoire répond comme une URL sans identifiants.

Vous obtenez :

kewos                         le binaire : l'application ET l'outil en ligne de commande
install.sh                    l'installateur en une passe
ui/                           l'interface construite, servie par le même processus
modules/                      l'arborescence des modules, consultable et extensible sur place
docker-compose.onprem.yml     Postgres 16 + Redis 7, si vous ne les avez pas déjà
.env.example                  le modèle de configuration
VERSION                       la version du paquet
INSTALL.md                    la même procédure, hors ligne

Le binaire sait dire ce qu’il est, ce qui évite de se tromper de version sur une machine qui en porte deux :

./kewos --version
# kewos 0.9.27

La voie courte : l’installateur

sudo ./install.sh

Il copie le paquet dans /opt/kewos, crée un compte de service dédié, met kewos dans le PATH, installe la complétion du shell, dépose la configuration à éditer et écrit les deux services systemd (l’application et le travailleur). Il ne démarre rien : c’est à vous d’éditer la configuration d’abord.

Sur une machine sans systemd (un conteneur, un autre gestionnaire de services), il le dit, saute les fichiers d’unité et vous donne les deux processus à lancer vous-même. Le reste est installé et fonctionne.

Après lui, il reste quatre gestes : éditer /opt/kewos/.env, lever Postgres et Redis, lancer kewos provision, démarrer. Ils sont détaillés dans les sections suivantes.

La voie longue : à la main

Si vous préférez maîtriser l’arborescence, ou déployer en versions côte à côte avec un retour arrière immédiat :

sudo mkdir -p /opt/kewos/releases/<version>
sudo unzip -q /tmp/kewos-<version>.zip -d /opt/kewos/releases/
sudo chown -R kewos:kewos /opt/kewos/releases/<version>
sudo ln -sfn /opt/kewos/releases/kewos-<version> /opt/kewos/current

Le lien symbolique n’est pas une coquetterie : c’est ce qui rend la mise à jour et le retour arrière immédiats, sans jamais laisser l’application dans un état à moitié copié.

Et si vous déployez en conteneur

L’archive contient tout ce qu’il faut pour construire votre propre image : les mêmes clés de configuration se passent en variables d’environnement, /etc/kewos se monte en lecture seule et /var/lib/kewos/storage en écriture.

Nous ne publions pas de registre d’images. Une voie de distribution unique, signée et vérifiable par empreinte, vaut mieux que deux à tenir à jour, et elle vous laisse maître de la base sur laquelle votre image est construite.

4. La configuration

Créez /etc/kewos/kewos.env. C’est le seul fichier à écrire.

sudo install -o root -g kewos -m 640 /dev/null /etc/kewos/kewos.env
sudo editor /etc/kewos/kewos.env

Générer les secrets

Trois valeurs doivent être aléatoires et vous appartenir. Générez-les une fois :

echo "KEWOS_SECRETS_MASTER_KEY=$(openssl rand -base64 32)"
echo "KEWOS_ATTACHMENT_SIGNING_SECRET=$(openssl rand -hex 32)"
echo "KEWOS_PORTAL_SIGNING_SECRET=$(openssl rand -hex 32)"

La clé maîtresse ne se perd pas

KEWOS_SECRETS_MASTER_KEY chiffre les secrets stockés par l’application (mots de passe SMTP, jetons de connecteurs, coordonnées bancaires). La perdre, c’est les perdre : il n’existe aucune récupération, et c’est le but.

Conservez-la ailleurs que sur ce serveur, et sachez qu’une restauration de sauvegarde la réclame. Une sauvegarde sans sa clé n’est pas une sauvegarde.

Le fichier, en entier

# --- Required ------------------------------------------------------------
KEWOS_ENV=production
KEWOS_MASTER_DATABASE_URL=postgresql+psycopg://kewos:PASSWORD@127.0.0.1:5432/kewos
KEWOS_REDIS_URL=redis://127.0.0.1:6379/0
KEWOS_SECRETS_MASTER_KEY=...
KEWOS_LICENSE_PUBLIC_KEY=...          # issued by Kewos with your licence
KEWOS_PUBLIC_BASE_URL=https://erp.example.com

# --- Paths ---------------------------------------------------------------
KEWOS_MODULES_ROOT=/opt/kewos/current/modules
KEWOS_STORAGE_ROOT=/var/lib/kewos/storage
KEWOS_LOG_DIR=/var/log/kewos

# --- Network -------------------------------------------------------------
KEWOS_HOST=127.0.0.1
KEWOS_PORT=8080

# --- Link signing --------------------------------------------------------
KEWOS_ATTACHMENT_SIGNING_SECRET=...
KEWOS_PORTAL_SIGNING_SECRET=...

# --- First administrator (read on first boot only) -----------------------
KEWOS_ADMIN_LOGIN=admin
KEWOS_ADMIN_EMAIL=admin@example.com
KEWOS_ADMIN_PASSWORD=...

# --- Recommended ---------------------------------------------------------
KEWOS_LOG_LEVEL=INFO
KEWOS_MAIL_FROM=no-reply@example.com
KEWOS_RATE_LIMIT_PER_MINUTE=100
KEWOS_HTTP_TIMEOUT_SECONDS=20
KEWOS_DB_TIMEOUT_SECONDS=30
KEWOS_JOB_TIMEOUT_SECONDS=900

Ce que chaque clé fait

Clé	Rôle
KEWOS_ENV	production sur un serveur. Toute autre valeur active des facilités de développement, dont l’application de schéma à chaud.
KEWOS_MASTER_DATABASE_URL	L’adresse de la base. Le préfixe postgresql+psycopg:// est requis.
KEWOS_REDIS_URL	La file de travaux et le cache. Sans elle, aucun traitement de fond ne s’exécute.
KEWOS_SECRETS_MASTER_KEY	Chiffre les secrets stockés en base. Irremplaçable.
KEWOS_LICENSE_PUBLIC_KEY	La clé avec laquelle votre jeton de licence est vérifié. Sans elle, l’application refuse de démarrer en production.
KEWOS_PUBLIC_BASE_URL	L’adresse publique. Sert à fabriquer les liens absolus des courriels et des PDF ; sans elle, les images n’apparaissent pas dans les documents envoyés.
KEWOS_MODULES_ROOT	Où sont les modules. Pointez le lien current, pas une version figée.
KEWOS_STORAGE_ROOT	Où vivent les pièces jointes. À sauvegarder avec la base.
KEWOS_LOG_DIR	Active le journal en fichier, avec rotation. Sans elle, tout va sur la sortie standard.
KEWOS_HOST / KEWOS_PORT	L’écoute. Restez sur 127.0.0.1 : c’est le proxy qui expose.
KEWOS_ATTACHMENT_SIGNING_SECRET	Signe les liens de pièce jointe. Changer cette valeur invalide les liens déjà envoyés.
KEWOS_PORTAL_SIGNING_SECRET	Signe les accès du portail externe. Même remarque.
KEWOS_ADMIN_PASSWORD	Le mot de passe du premier administrateur, appliqué au premier démarrage.
KEWOS_MAIL_FROM	L’expéditeur par défaut des courriels sortants.
KEWOS_RATE_LIMIT_PER_MINUTE	Le budget de requêtes par acteur et par minute.
KEWOS_LOG_LEVEL	INFO en service courant, DEBUG seulement le temps d’un diagnostic.

Renseignez KEWOS_ADMIN_PASSWORD avant le premier démarrage

Si cette clé est absente au premier démarrage, l’application crée le compte admin avec le mot de passe admin et impose son changement à la première connexion. Cela laisse une fenêtre pendant laquelle le compte est prévisible.

Ne branchez jamais une installation neuve sur Internet avant d’avoir fait ce réglage. Une fois le compte créé, cette clé n’est plus lue : un redémarrage ne réinitialise pas le mot de passe que vous avez choisi.

5. Le premier démarrage

Cette commande enregistre l’installation, crée le schéma et l’administrateur. Elle est idempotente : la rejouer ne fait pas de dégât.

cd /opt/kewos/current
sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./kewos provision

provisioned tenant 'main' + admin 'admin' (created)

Puis alignez le schéma. Une installation neuve se déclare en dérive tant que ce n’est pas fait, parce que les tables sont créées d’un bloc sans que les migrations soient marquées. La commande est additive : elle crée ce qui manque et ne détruit jamais.

sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./kewos reconcile --confirm --modules-root /opt/kewos/current/modules

main [active]: reconciled (37 migration(s), 0 column(s))
done: 1 tenant(s), 0 failed

6. Poser votre licence

sudo install -o root -g kewos -m 640 license.token /etc/kewos/license.token

cd /opt/kewos/current
sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./kewos license install \
       --tenant main \
       --database-url "$KEWOS_MASTER_DATABASE_URL" \
       --token-file /etc/kewos/license.token

Vérifiez :

sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./kewos license show --database-url "$KEWOS_MASTER_DATABASE_URL"

status:    valid
tenant:    main
plan:      on-prem
users:     1 / 25
companies: 1 / 3
expires:   2027-09-03T11:28:38+00:00

Sans cette étape, le démarrage se termine par :

refusing to start: tenant(s) without a valid license: main=missing

Si votre licence est liée à une machine

sudo -u kewos ./kewos license fingerprint

Envoyez la valeur affichée à Kewos, qui émet un jeton lié à ce serveur.

En conteneur, donnez un identifiant stable

La commande répond no machine-id available on this host dans une image minimale : ces images ne portent pas de /etc/machine-id. Montez celui de l’hôte en lecture seule (-v /etc/machine-id:/etc/machine-id:ro), ou générez-en un et conservez-le : un identifiant régénéré à chaque démarrage invalide la licence à chaque redémarrage.

7. Les services

Deux services : l’application, et le travailleur qui draine la file. Les deux sont nécessaires. Sans le travailleur, les courriels, les imports et les documents attendent sans message d’erreur.

/etc/systemd/system/kewos.service :

[Unit]
Description=Kewos ERP
After=network-online.target postgresql.service redis-server.service
Wants=postgresql.service redis-server.service

[Service]
Type=simple
User=kewos
Group=kewos
WorkingDirectory=/opt/kewos/current
EnvironmentFile=/etc/kewos/kewos.env
ExecStart=/opt/kewos/current/kewos
Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/kewos /var/log/kewos
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

/etc/systemd/system/kewos-worker.service :

[Unit]
Description=Kewos ERP background worker
After=network-online.target redis-server.service kewos.service
Wants=redis-server.service

[Service]
Type=simple
User=kewos
Group=kewos
WorkingDirectory=/opt/kewos/current
EnvironmentFile=/etc/kewos/kewos.env
ExecStart=/opt/kewos/current/kewos worker --threads 8
Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/kewos /var/log/kewos

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kewos kewos-worker
sudo systemctl status kewos kewos-worker --no-pager

Le démarrage prend une dizaine de secondes. Une vérification lancée trop tôt échoue alors que tout va bien.

8. Le proxy

Caddy

erp.example.com {
  encode zstd gzip
  request_body {
    max_size 60MB
  }
  reverse_proxy 127.0.0.1:8080
}

nginx

server {
    listen 443 ssl http2;
    server_name erp.example.com;

    ssl_certificate     /etc/letsencrypt/live/erp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/erp.example.com/privkey.pem;

    # Attachments and imports can be large: too low a value here returns 413
    # before the application ever sees the request.
    client_max_body_size 60m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

9. Vérifier

curl -fsS https://erp.example.com/health/live
# {"status":"alive"}

curl -fsS https://erp.example.com/health/schema
# {"status":"ok","tenants_checked":1,"drifted":{}}

curl -o /dev/null -w '%{http_code}\n' https://erp.example.com/api/v1/about
# 401

Un 401 sur l’API est un bon signe : elle est fermée.

Puis ouvrez l’adresse dans un navigateur et connectez-vous.

Ce que vous voyez	Ce que ça veut dire	Ce qu’il faut faire
L’écran de connexion	Tout va bien.	Mettre en service.
Le service ne démarre pas	Licence manquante, clé publique absente, ou base injoignable.	journalctl -u kewos -n 50 --no-pager
Une page vide, l’API répond	Le paquet est incomplet.	Reprenez le téléchargement et vérifiez l’empreinte.
/health/schema répond drifted	Le schéma est en retard sur le code.	Relancez reconcile --confirm, puis redémarrez.
Les courriels ne partent pas	Le travailleur ne tourne pas.	sudo systemctl status kewos-worker

10. Mettre à jour, et revenir en arrière

Une mise à jour consiste à installer une version à côté et à déplacer le lien.

# 1. Back up FIRST.
sudo -u postgres pg_dump -Fc kewos > /var/backups/kewos-$(date +%F).dump

# 2. Install the new release next to the old one.
sudo unzip -q /tmp/kewos-<new-version>.zip -d /opt/kewos/releases/
sudo chown -R kewos:kewos /opt/kewos/releases/kewos-<new-version>

# 3. Switch, align the schema, restart.
sudo ln -sfn /opt/kewos/releases/kewos-<new-version> /opt/kewos/current
sudo systemctl stop kewos kewos-worker
cd /opt/kewos/current && sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./kewos reconcile --confirm --modules-root /opt/kewos/current/modules
sudo systemctl start kewos kewos-worker

Le retour arrière est le même geste, dans l’autre sens :

sudo ln -sfn /opt/kewos/releases/kewos-<previous-version> /opt/kewos/current
sudo systemctl restart kewos kewos-worker

Un retour arrière ne défait pas une migration

Le code revient, le schéma reste. C’est voulu : défaire une migration détruit des données. Si une version a ajouté des colonnes, l’ancienne les ignore, et tout fonctionne. Si vous devez vraiment revenir en arrière sur les données, c’est la sauvegarde de l’étape 1 qui sert.

Et ensuite

Mettre en service : les réglages à faire avant d’ouvrir aux utilisateurs.