En

Installation with External PostgreSQL#

This guide applies to a new installation of Sherpa Orchestrator with a PostgreSQL database on a separate server. When upgrading an existing installation, use the upgrade process and prepare a backup in advance.

Before You Begin#

  • Prepare a PostgreSQL server version 13 or newer with a database in UTF-8 encoding.
  • Allow connections to it from the Docker network of the Orchestrator server: configure listen_addresses, the host rule in pg_hba.conf, and the firewall. Check the address and port available from the container, not just from the host.
  • Choose a name for the working role, database, and a separate password. The working role will need CREATE rights in the database: migrations will automatically create the orchestrator and orchestrator_archive schemas.
  • If the role and database have already been created by the PostgreSQL administrator, the installer does not need administrative credentials. Otherwise, prepare a temporary administrative role with CREATEROLE and CREATEDB rights.

Installation#

  1. Unpack the client package and run sudo ./sh_scripts/install.sh, as described in the general instructions.
  2. On the Database Selection step, choose 4 — External PostgreSQL. The database container will not be started at this point.
  3. Specify the POSTGRES_PASSWORD for the working role, then POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, and POSTGRES_DBNAME. Do not leave the example password from the template in .env.
  4. If the role or database has not yet been created, fill in POSTGRES_ADMIN_USER, POSTGRES_ADMIN_PASSWORD, and if necessary, POSTGRES_ADMIN_DBNAME (default is postgres). If the role and database have been created in advance, leave the administrative role empty.
  5. Wait for the connection check before starting the system. The installer will check the server's availability and the working role's login, create the role and database if necessary, and then check for CREATE rights.
  6. If the check fails, perform the indicated actions on the PostgreSQL server and select r — Retry Check. The e option allows you to correct the connection parameters. Do not skip the check with option s: Orchestrator will not start while the database or role is unavailable.
  7. Complete the remaining steps of the installer and open the Orchestrator interface. Check the login and create a test object in a section accessible to your role.

If the Check Fails#

  • Server Unavailable: check POSTGRES_HOST, POSTGRES_PORT, routing from Docker, listen_addresses, pg_hba.conf, and the firewall.
  • Role or Database Missing: create them on the PostgreSQL server or temporarily provide the installer with administrative credentials. After creating the database, grant the working role CREATE rights.
  • Working Role Login Error: check its password in .env and the allowing rule in pg_hba.conf. If the role existed before, its password may differ from the one specified for the new installation.

The orchestrator and orchestrator_archive schemas are created by migrations. For a new installation, do not load a dump from another system into them.