Installation troubleshooting

The installer checks every step and prints one line per check:

PASS  NET-01  ims.my-company.ma resolves to this server
WARN  PRE-06  the clock is not NTP-synchronized
FAIL  KC-01   the authentication service advertises another address

The identifier (NET-01, KC-01…) means the same thing everywhere. Quote it in any support request. The package's TROUBLESHOOTING.md gives the detailed cause and the fix commands for each one; this page gives the meaning and the first action.

Run the diagnosis

The diagnosis changes nothing and can run in production. It runs every check without stopping at the first error, and exits with code 0 when everything is fine, 1 otherwise, so it can be scheduled.

Linux

./install.sh --doctor

Windows

.\install.ps1 -Doctor

Run it after a reboot, an upgrade, a certificate renewal, or whenever something looks wrong.

Rules that prevent most failures

• Do not edit derived configuration values by hand (authentication addresses, allowed origins). Change the host name or protocol by running the installer again: it rewrites everything that depends on them.
• Never change the database passwords in .env.
• Always run commands from the installation directory.

PRE · Requirements

Identifier	What is checked	First action
PRE-01	Docker answers	Start Docker (on Windows, Docker Desktop only starts after sign-in)
PRE-02	Docker Compose v2 is present	Install the Compose v2 plugin; the old docker-compose is not enough
PRE-03	4 GB of memory for Docker	Add memory; on Windows, raise the memory allocated to WSL2
PRE-04	20 GB of free disk space	Free space (old images, old backups)
PRE-05	Ports 80 and 443 free	Stop the service using them (another web server, IIS, VPN)
PRE-06	Clock synchronized	Enable NTP synchronization: a drifting clock makes sign-ins fail
PRE-07	Databases from a previous installation	Keep the data by reusing the old credentials, or delete it only after a backup
PRE-08	Licence server reachable	Allow outbound HTTPS, or use a licence file
PRE-09	Package integrity	Copy the package again: a file was altered in transfer
PRE-10	Traces of a previous installation	Informational on recent versions

CFG · Configuration

Identifier	What is checked	First action
CFG-01	Configuration written from the template	Use the installer and template from the same package
CFG-02	No unresolved variable	Run the installer again; it rewrites derived values
CFG-03	Missing answer (unattended install)	Complete the answers file
CFG-04	Summary and answers saved	Run the installer as a user who can write to the directory
CFG-05	Invalid answer	Correct the value shown (host name, e-mail, time zone…)
CFG-06	Configuration matches the version	Run the installer again: it adds what is missing and keeps secrets
CFG-07	Derived values match the host name	Run the installer again; do not fix these values one by one
CFG-08	The HTTPS site uses the right host name	Run the installer again after a host name change
CFG-09	Server-sharing settings consistent	Applies to servers hosting several installations; contact support

IMG · Images

Identifier	What is checked	First action
IMG-01	Images loaded from the package	Check disk space and package integrity
IMG-02	Image download	For a server without registry access, ask for a package with embedded images
IMG-03	Version images present	Load exactly the version shown; never switch to "latest"

TLS · Certificates

Identifier	What is checked	First action
TLS-01	Let's Encrypt certificate obtained	Check that the DNS name points to the server and port 80 is reachable from the internet
TLS-02	Existing certificate in place	Put the certificate and key where expected
TLS-03	Configuration for HTTPS handled by your proxy	Provide your proxy configuration
TLS-04	Certificate validity	Run the renewal again; warning 21 days before expiry
TLS-05	Automatic renewal running	Restart the renewal service

RUN · Startup

Identifier	What is checked	First action
RUN-00	Application startup	Read the reported cause: port in use, missing value, missing image
RUN-01	All components started	—
RUN-02	Every component exists	Run commands from the installation directory
RUN-03	Every component is healthy	Wait during the first start (3 to 5 minutes), then read the logs

API, DB, KC, WEB · Application

Identifier	What is checked	First action
API-01	Application services answer	Read the services log: the first error names the cause
API-02	The browser is allowed to call the API	Run the installer again (see CFG-07)
DB-01	Database migrations succeeded	Stop using the installation: restore the pre-upgrade backup and contact support
DB-02	Database matches the version	Change nothing by hand; contact support
DB-03	Databases can be rebuilt	Restore the original database credentials
KC-01	Address advertised by authentication	Run the installer again (see CFG-07): this causes endless sign-in failures
KC-02	Authentication prepared at first start	Read the first-start log
KC-03	The web console is known to authentication	Follow the fix in TROUBLESHOOTING.md
WEB-01	The web console answers	Check that the console is running

LIC, SEC, NET · Licence, access, network

Identifier	What is checked	First action
LIC-00	Licence file supplied at install	Activate the licence after sign-in
LIC-01	Licence active	Sign in as administrator and activate the licence; without it, the application stays restricted
LIC-02	Licence storage	Put the licence file back; check write permissions
SEC-01	Addresses allowed for the admin consoles	Informational: with no address, they stay closed
SEC-02	Allowlist present	Restore it from the package: without it, the whole site is down
NET-01	The host name points to this server	Fix the DNS record; the name must also resolve from the server itself

UPG · Upgrade

Identifier	What is checked	First action
UPG-01	The target is an installation	Point the upgrade at the installation directory, not at the package
UPG-02	The upgrade goes to a newer version	Use the newest package; downgrades are refused
UPG-03	Authentication is never downgraded	Nothing to do
UPG-04	Backup before upgrade	Free space; nothing was changed
UPG-05	Package files replaced	Fix space or permissions, then run again
UPG-06	Configuration merged	Read the message; then run the diagnosis
UPG-07	HTTPS configuration updated	If you had edited it by hand, carry over the new version's changes

See Upgrades and backups to return to the previous version.

Contact support

Include in your request:

• the FAIL or WARN identifiers from the diagnosis;
• the installed version (VERSION file);
• the log of the run concerned, in install/logs/.

Never send .env or install-summary.txt: they contain secrets.