On-Premises Setup

AI Installation, Step by Step

Run bash ai/install.sh from your deployment folder, or .\ai\install.ps1 in PowerShell. The installer switches to its own AI directory, creates the required folders, and writes ai/.env. You do not need to change directories during an installation prompt.

1. 1. Choose where AI runs

   On the same server, keep apis and ai as sibling deployment folders. The installer reuses available ERP URLs, configured authentication, the public key, and externally reachable database settings. Your existing AI settings and explicit overrides take precedence.

   On another server, use addresses reachable from the AI container. A Docker service name such as postgres on the ERP server, or localhost inside AI, does not automatically reach that server. Download the AI image before generating a short-lived pairing code.

   Copy

   docker pull korobosta/ai:latest

2. 2. Choose Platform authentication

   If authentication is not already configured, the installer offers three choices. A Platform internal token is for operator-owned deployments and must match Platform API. Installation ID and key are for one enrolled tenant. ERP pairing is recommended for customer-hosted AI and keeps ERP installation credentials off the AI server.

   For pairing, sign in to the ERP Business app as a tenant administrator. Open AI > Settings > Connect AI Server, select Generate Pairing Code, use its copy button, and paste the code into the waiting installer. The code lasts five minutes and works once. Generate it only when the AI server is ready to start. These controls remain available even while AI is offline.

   Pairing securely provides a dedicated relay credential and the ERP JWT public key. Shared SaaS hosts require explicit approval by the enrolled host's super administrator; an ordinary tenant code remains tenant-scoped. Do not share Platform tokens, installation keys, or pairing codes in support tickets.

3. 3. Supply the ERP public key when needed

   Pairing supplies the public key automatically. Otherwise, the installer first looks for the sibling ERP's apis/keys/public.pem. If it cannot find it, it accepts either an absolute local file path or a pasted public PEM.

   To export the existing key, run this in a second terminal on the ERP server, from the main deployment directory:

   Copy

   # Linux / macOS
   ./manage.sh export-public-key
   
   # PowerShell
   .\manage.ps1 -Command export-public-key

   The command creates erp-public.pem. Open it and copy the complete block, including -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, into the AI installer. Alternatively, transfer the file and enter its absolute path. The installer validates it and creates ai/keys/public.pem for the read-only container mount. Never transfer private.pem, generate a replacement key pair, or use licence_public.pem for JWT verification.

4. 4. Confirm database and storage

   Enter database credentials only if they could not be reused. Enter the real password without manually URL-encoding it: the installer generates encoded database connection values. Choose Local disk, an explicitly built or approved MinIO image, or External S3-compatible storage. Do not assume minio/minio:latest is available.

   For Google Cloud Storage, use https://storage.googleapis.com as the endpoint, koro-erp as the default bucket, and GCS HMAC access credentials. The bucket name is separate from the endpoint; do not append it to the URL. Existing custom settings remain unchanged.

5. 5. Preserve settings and verify startup

   The installer generates the BYOK encryption key once and preserves it on reruns. Back up ai/.env securely: replacing that key makes saved provider credentials unreadable. Legacy .env.ai is copied only when .env does not exist. Local models, datasets, and pairing state use persistent volumes; do not delete them during updates.

   From the AI deployment directory, check startup and logs:

   Copy

   docker compose --env-file .env -f docker-compose.yml up -d
   docker compose --env-file .env -f docker-compose.yml logs --tail 100 ai

   Add --profile minio if you selected bundled MinIO. A started container is not proof of application readiness: check the logs and AI's /health endpoint. Before recreating older containers, back up any files in /app/storage that were not already on a persistent volume.

6. 6. Link ERP to the AI server

   For a separate AI server, configure its HTTPS address and run the link command on the main ERP server:

   Copy

   ./manage.sh link-ai https://ai.your-domain.com
   
   # PowerShell
   .\manage.ps1 -Command link-ai -AiUrl https://ai.your-domain.com

   The ERP gateway forwards Business app AI requests to this server. Wallet calls use your selected direct Platform credentials or the paired ERP relay. Provider selection and managed API keys remain on Platform; they are not entered in the AI key-file prompt.

Detailed reference: AI deployment guide. Installation files: Linux installer and PowerShell installer.