Installing on a server

This page is meant to be followed end to end, with nothing left to guess. It installs Kewos ERP on a Linux server, as a permanent service, behind your own reverse proxy.

Before you start

You need your licence token, your download credentials and the licence public key. The three are issued together. If you do not have them, start with Getting a licence.

What the server needs

Operating system	Debian 12 / 13, Ubuntu 22.04 / 24.04, or equivalent, 64-bit.
CPU	Four cores to begin with.
Memory	8 GB. Plan for 16 GB beyond twenty concurrent users.
Disk	20 GB for the product, plus room for your attachments and your backups.
Database	PostgreSQL 16 or 17.
Queue	Redis 6 or later.
Network	A domain name and a proxy terminating TLS.

System packages

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

Rendering PDF documents relies on a few native libraries:

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

Without them the application starts and printing a document fails at the moment somebody needs it. Install them now.

Document reading (optional)

If your users upload scanned invoices or delivery notes and you want the text out of them without the documents going anywhere:

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

tesseract-ocr reads images, the language data is picked per language (-fra, -deu, adapt it), and poppler-utils provides pdftoppm, which turns a scanned PDF into images before reading.

It is optional on purpose. Without these packages the application runs exactly the same: the matching engines do not register, the Settings → Integrations → Document reading screen does not offer them, and nothing fails on the first click. A PDF that already carries a text layer (an invoice from accounting software, an e-invoice) is read without any of these packages, exactly, and that is the common case.

1. The service account and the layout

The application never runs as 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

Path	Contents
/opt/kewos/current	The release in service (a symlink into /opt/kewos/releases/).
/opt/kewos/releases/	Installed releases. Keep two or three so you can go back.
/etc/kewos/kewos.env	The configuration. Holds secrets: root:kewos, mode 640.
/etc/kewos/license.token	Your licence token.
/var/lib/kewos/storage	Attachments and generated documents. Back this up.
/var/log/kewos	Logs.

2. The database

The role needs CREATEDB: the application creates its own database and, in advanced multi-company setups, those of the extra entities.

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

Check the connection before going further:

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

Set up backups now

Add the database to your backup plan now, before the first real record. See Go live.

3. Fetch your release

Kewos ships as one .zip carrying everything: the application binary (the API and the interface in a single process), the built interface, the modules tree, a docker-compose for Postgres and Redis, a configuration template, and an installer. No Python, no Node, no build toolchain is required on the target host.

Kewos hands you a download identifier and a password with your licence. They are for this and nothing else, and they are not your application credentials.

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

curl asks for the password: do not put it in the command, it would stay in your shell history.

Check the digest before deploying. A package that does not match its own is not a Kewos package.

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

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

The directory does not browse

You download the version Kewos named for you. There is no listing: the catalogue of versions is not public, and a directory URL answers like a URL with no credentials.

You get:

kewos                         the binary: the application AND the command-line tool
install.sh                    the one-shot installer
ui/                           the built interface, served by the same process
modules/                      the modules tree, browsable and extensible on site
docker-compose.onprem.yml     Postgres 16 + Redis 7, if you do not have them already
.env.example                  the configuration template
VERSION                       the bundle's version
INSTALL.md                    the same procedure, offline

The binary can say what it is, which saves picking the wrong one on a host carrying two:

./kewos --version
# kewos 0.9.27

The short way: the installer

sudo ./install.sh

It copies the bundle to /opt/kewos, creates a dedicated service user, puts kewos on the PATH, installs shell completion, drops the configuration for you to edit and writes the two systemd services (the application and the worker). It starts nothing: editing the configuration comes first.

On a host without systemd (a container, another service manager) it says so, skips the unit files and gives you the two processes to run yourself. Everything else is installed and works.

After it, four gestures remain: edit /opt/kewos/.env, bring up Postgres and Redis, run kewos provision, start it. The sections below detail them.

The long way: by hand

If you would rather own the layout, or deploy versions side by side with an instant rollback:

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

The symlink is not decoration: it is what makes an upgrade and a rollback immediate, without ever leaving the application half-copied.

If you deploy in a container

The archive has everything needed to build your own image: the same configuration keys are passed as environment variables, /etc/kewos mounts read-only and /var/lib/kewos/storage read-write.

We publish no image registry. One distribution path, signed and checksum-verifiable, beats two to keep up to date, and it leaves you in charge of the base your image is built on.

4. Configuration

Create /etc/kewos/kewos.env. It is the only file you have to write.

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

Generating the secrets

Three values must be random and yours. Generate them once:

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)"

The master key cannot be lost

KEWOS_SECRETS_MASTER_KEY encrypts the secrets the application stores: SMTP passwords, connector tokens, bank details. Losing it means losing them: there is no recovery, and that is the point.

Keep it somewhere other than this server, and know that restoring a backup requires it. A backup without its key is not a backup.

The file, in full

# --- 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

What each key does

Key	Role
KEWOS_ENV	production on a server. Any other value enables development conveniences, including hot schema application.
KEWOS_MASTER_DATABASE_URL	The database address. The postgresql+psycopg:// prefix is required.
KEWOS_REDIS_URL	The job queue and the cache. Without it no background work runs.
KEWOS_SECRETS_MASTER_KEY	Encrypts stored secrets. Irreplaceable.
KEWOS_LICENSE_PUBLIC_KEY	The key your licence token is verified against. Without it the application refuses to start in production.
KEWOS_PUBLIC_BASE_URL	The public address. Used to build absolute links in emails and PDFs; without it images do not appear in sent documents.
KEWOS_MODULES_ROOT	Where the modules live. Point at the current symlink, not a fixed release.
KEWOS_STORAGE_ROOT	Where attachments live. Back this up with the database.
KEWOS_LOG_DIR	Enables the rotating file log. Without it everything goes to standard output.
KEWOS_HOST / KEWOS_PORT	What it listens on. Stay on 127.0.0.1: the proxy does the exposing.
KEWOS_ATTACHMENT_SIGNING_SECRET	Signs attachment links. Changing it invalidates links already sent.
KEWOS_PORTAL_SIGNING_SECRET	Signs external portal access. Same caveat.
KEWOS_ADMIN_PASSWORD	The first administrator’s password, applied on first boot.
KEWOS_MAIL_FROM	Default sender for outbound mail.
KEWOS_RATE_LIMIT_PER_MINUTE	Request budget per actor per minute.
KEWOS_LOG_LEVEL	INFO in service, DEBUG only while diagnosing.

Set KEWOS_ADMIN_PASSWORD before the first boot

If that key is missing on first boot, the application creates the admin account with the password admin and forces a change at first login. That leaves a window during which the account is predictable.

Never expose a fresh installation to the internet before setting it. Once the account exists the key is no longer read: a restart does not reset the password you chose.

5. First boot

This registers the installation, creates the schema and the administrator. It is idempotent: running it again does no harm.

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

Then align the schema. A fresh installation reports drift until this is done, because the tables are created in one go without the migrations being stamped. The command is additive: it creates what is missing and never destroys.

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. Apply your licence

The application serves nothing until this is done:

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

sudo install -o root -g kewos -m 640 your-licence.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

Check it:

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

If your licence is machine-bound

sudo -u kewos ./kewos license fingerprint

Send the value to Kewos, which issues a token bound to this server.

In a container, provide a stable identifier

The command answers no machine-id available on this host in a minimal image: those images carry no /etc/machine-id. Mount the host’s read-only (-v /etc/machine-id:/etc/machine-id:ro), or generate one and keep it: an identifier regenerated on every start invalidates the licence on every restart.

7. The services

Two services: the application, and the worker that drains the queue. Both are required. Without the worker, emails, imports and documents wait with no error message.

/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 is the same unit with ExecStart=/opt/kewos/current/kewos worker --threads 8 and no LimitNOFILE.

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

Startup takes about ten seconds. A check run too early fails while everything is fine.

8. The 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. Check it

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

A 401 on the API is a good sign: it is closed.

What you see	What it means	What to do
The login screen	All good.	Go live.
The service does not start	Missing licence, missing public key, or unreachable database.	journalctl -u kewos -n 50 --no-pager
A blank page, API responding	The package is incomplete.	Download again and check the digest.
/health/schema says drifted	The schema lags the code.	Run reconcile --confirm, then restart.
Emails do not go out	The worker is not running.	sudo systemctl status kewos-worker

10. Upgrading, and going back

An upgrade means installing a release beside the current one and moving the symlink.

# 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>.zip -d /opt/kewos/releases/
sudo chown -R kewos:kewos /opt/kewos/releases/kewos-<new>

# 3. Switch, align the schema, restart.
sudo ln -sfn /opt/kewos/releases/kewos-<new> /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

Rolling back is the same move in reverse:

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

Rolling back does not undo a migration

The code goes back, the schema stays. That is deliberate: undoing a migration destroys data. If a release added columns, the older one ignores them and everything works. If you genuinely need the data back, that is what the backup from step 1 is for.

Next

Go live: the settings to get right before you open the door.