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.

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 'un-mot-de-passe-long-et-aleatoire' CREATEDB;
CREATE DATABASE kewos OWNER kewos;
SQL

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

PGPASSWORD='un-mot-de-passe-long-et-aleatoire' 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

En archive

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

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-erp-<version>.tar.gz.sha256
# kewos-erp-<version>.tar.gz : Réussi

Puis installez-le dans son propre répertoire de version :

sudo mkdir -p /opt/kewos/releases/<version>
sudo tar -xzf kewos-erp-<version>.tar.gz -C /opt/kewos/releases/<version> --strip-components=1
sudo chown -R kewos:kewos /opt/kewos/releases/<version>
sudo ln -sfn /opt/kewos/releases/<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é.

En conteneur

docker login registry.kewos.io
docker pull registry.kewos.io/erp:<version>

Le reste de cette page décrit l’installation en archive. Pour le conteneur, les mêmes clés de configuration se passent en variables d’environnement, et les mêmes volumes correspondent : /etc/kewos en lecture seule et /var/lib/kewos/storage en écriture.

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

# --- Obligatoire ---------------------------------------------------------
KEWOS_ENV=production
KEWOS_MASTER_DATABASE_URL=postgresql+psycopg://kewos:MOT_DE_PASSE@127.0.0.1:5432/kewos
KEWOS_REDIS_URL=redis://127.0.0.1:6379/0
KEWOS_SECRETS_MASTER_KEY=...
KEWOS_LICENSE_PUBLIC_KEY=...          # fournie par Kewos avec votre licence
KEWOS_PUBLIC_BASE_URL=https://erp.votre-domaine.fr

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

# --- Réseau --------------------------------------------------------------
KEWOS_HOST=127.0.0.1
KEWOS_PORT=8080

# --- Signature des liens -------------------------------------------------
KEWOS_ATTACHMENT_SIGNING_SECRET=...
KEWOS_PORTAL_SIGNING_SECRET=...

# --- Premier administrateur (lu au premier démarrage seulement) -----------
KEWOS_ADMIN_LOGIN=admin
KEWOS_ADMIN_EMAIL=admin@votre-domaine.fr
KEWOS_ADMIN_PASSWORD=...

# --- Recommandé ----------------------------------------------------------
KEWOS_LOG_LEVEL=INFO
KEWOS_MAIL_FROM=no-reply@votre-domaine.fr
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) \
     ./bin/kewos-server 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) \
     ./bin/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 votre-licence.token /etc/kewos/license.token

cd /opt/kewos/current
sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./bin/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) \
     ./bin/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 ./bin/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/bin/kewos-server
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/bin/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.votre-domaine.fr {
  encode zstd gzip
  request_body {
    max_size 60MB
  }
  reverse_proxy 127.0.0.1:8080
}

nginx

server {
    listen 443 ssl http2;
    server_name erp.votre-domaine.fr;

    ssl_certificate     /etc/letsencrypt/live/erp.votre-domaine.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/erp.votre-domaine.fr/privkey.pem;

    # Les pièces jointes et les imports peuvent être volumineux : une valeur
    # trop basse ici renvoie un 413 avant que l'application ne voie la requête.
    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.votre-domaine.fr/health/live
# {"status":"alive"}

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

curl -o /dev/null -w '%{http_code}\n' https://erp.votre-domaine.fr/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. Sauvegarder AVANT.
sudo -u postgres pg_dump -Fc kewos > /var/backups/kewos-$(date +%F).dump

# 2. Installer la nouvelle version à côté de l'ancienne.
sudo mkdir -p /opt/kewos/releases/<nouvelle>
sudo tar -xzf kewos-erp-<nouvelle>.tar.gz -C /opt/kewos/releases/<nouvelle> --strip-components=1
sudo chown -R kewos:kewos /opt/kewos/releases/<nouvelle>

# 3. Basculer, aligner le schéma, redémarrer.
sudo ln -sfn /opt/kewos/releases/<nouvelle> /opt/kewos/current
sudo systemctl stop kewos kewos-worker
cd /opt/kewos/current && sudo -u kewos env $(grep -v '^#' /etc/kewos/kewos.env | xargs) \
     ./bin/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/<ancienne> /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.