Local start: run the backend and the portal, sign in, install a service

Run every command in a WSL bash terminal, from the root of the repository (~/projects/deploy7/navin-entreprise-ai), unless stated otherwise.

1. Essential services: make install, make start

Needed on the machine: Python 3.11+, Node.js 20+, redis-server (sudo apt install redis-server) and Java 21 (already in ~/.local/toolchains). No Docker needed.

make docker-env      # once: deploy/compose/.env and services/control-plane/local.env
make install         # control plane (.venv), portal dependencies (npm install), Keycloak 26.8.1
make start           # PostgreSQL, Redis, Keycloak, migrations, API :8080, worker, portal :3300
make status          # state of each component
make logs            # logs (Ctrl-C to quit)
make stop            # stops what make started

Component	Address	Started by make start
PostgreSQL	EAI_DATABASE_URL	only when it does not answer yet (else used as is)
Redis	EAI_REDIS_URL	same, with the password of the URL
Keycloak	http://localhost:8081	same, realm enterprise-ai imported, console http://localhost:8081/admin
API	http://127.0.0.1:8080	yes, after the migrations
Worker	-	yes
Portal	http://localhost:3300	built when needed (npm run build), then served

Keycloak console password: KEYCLOAK_ADMIN_PASSWORD of deploy/compose/.env (user admin). First passwords of the sample users of the realm: .run/keycloak/users (to change at the first sign in). make start COMPONENTS=portal PORTAL_BUILD=1 builds the portal again; PORTAL_PORT changes its port.

2. Portal in development mode (optional)

cd portal
npm run dev                      # http://localhost:3300 (.next-dev folder), stop the portal of make start first

npm run dev and npm run build use different folders (.next-dev and .next): a build run while the development server runs no longer breaks the scripts of the page. After a new build, reload the page (Ctrl-F5): an old file name gets a clean 404 instead of an HTML page.

3. Sign in

Login and password (installation account)

Open http://localhost:3300/login, Login tab: navin / navin (settings EAI_BOOTSTRAP_ADMIN_USERNAME, EAI_BOOTSTRAP_ADMIN_PASSWORD of local.env and deploy/compose/.env). The account has the roles platform_admin and tenant_admin on the organisation default. The portal asks for a new password at the first sign in; the installation password stops working afterwards.

Keycloak, and LDAP / Active Directory through Keycloak

1. make start starts Keycloak and connects it to the API and the portal (EAI_OIDC_ISSUER, EAI_OIDC_JWKS_URL, EAI_OIDC_AUDIENCE of local.env, already set): the Sign in with SSO button shows on the sign in page. To do without it, comment these three lines out, then make restart.

2. Directory: set EAI_LDAP_URL, EAI_LDAP_BIND_DN, EAI_LDAP_BIND_CREDENTIAL, EAI_LDAP_USERS_DN and EAI_LDAP_GROUPS_DN in deploy/compose/.env before the first Keycloak start (to change them later: make stop COMPONENTS=keycloak, delete .run/keycloak/h2, then make start). Keycloak reads the directory read only and imports its groups.

3. Administration rights, given by the groups (Keycloak or directory):

   Group	Role given
   navin-platform-admins	platform_admin (platform administrator)
   navin-admins-<organisation slug>, for example navin-admins-default	tenant_admin of that organisation

   The realm creates both sample groups. Add a user in the Keycloak console (http://localhost:8081/admin, realm enterprise-ai, Users, Groups, Join), or create groups with these names in the directory. To keep the group names of your directory, change EAI_OIDC_PLATFORM_ADMIN_GROUPS (comma separated list) and EAI_OIDC_TENANT_ADMIN_GROUP_PREFIX. Names are compared without case. An administrator of several organisations needs the Keycloak attribute tenant to choose one. An unknown organisation is refused.

4. Install a service from the platform

The Platform Manager (navin-manager) installs the infrastructure services on the servers it manages. Start with the Platform Manager, Getting started page of the portal (role platform_admin): it shows the state of the platform, of the Manager connection, of the clusters and of the machines, and guides each step (machines added by SSH or by the enrollment command of the agent, checks). Then Service manager, Install a service installs any service of the catalog (tabs AI services, On demand jobs, Developer packages, Infrastructure) or connects a service that already exists: choose the cluster, the service, the mode (standalone, cluster, replication, sentinel... depending on the service), the method, the servers of each component (minimum and maximum count shown) and the configuration, then Validate (Manager errors per field, for example a required parameter to add with Add a parameter) and Install (operation id, followed in Operations). The same screen starts, stops, restarts, reinstalls and changes the mode of an installed service (ADR-0128).

1. Manager sandbox, without root and without Docker:

   export NM_SANDBOX_ADMIN_PASSWORD='choose-a-password'
   navin-manager/packaging/sandbox/sandbox.sh up
   # archives of the services to install (a service missing from the mirror is refused: artifact_missing); with
   # NM_SANDBOX_ADMIN_PASSWORD, the Manager reloads its mirror at once
   navin-manager/packaging/sandbox/sandbox.sh bundle opa,openfga,prometheus,alertmanager

   The Manager console stays available on http://127.0.0.1:8460 (account navin / navin, to change at the first sign in, cluster sandbox).
2. Connect the portal to the Manager:
   • in the Manager console, Users: create the user named after your portal login (navin for the installation account), role cluster_admin or admin;
   • signed in as this user, Profile, API tokens: create a token with auth:delegate, cluster:read, operations:read, configs:read, services:install, services:operate, alerts:read, hosts:manage (machines, enrollment, checks), clusters:create (first cluster), cluster:manage (support bundles), backup:read, restore:execute, dr:manage (backup, restore and DR), connections:read and connections:manage (connections to running services); GET /v1/platform-manager/setup returns this list. The effective rights are the token rights crossed with the rights of the delegated user;
   • store it as a secret of the organisation (session navin, role tenant_admin): POST /v1/secrets with {"path": "platform-manager/token", "value": "<token>"}; GET /v1/me gives the tenant_id;
   • in services/control-plane/local.env:

     EAI_PLATFORM_MANAGER_URL=http://127.0.0.1:8460
     EAI_PLATFORM_MANAGER_TOKEN_REF=secret://<tenant_id>/platform-manager/token

     then make restart. The Getting started page then shows the Manager connection and the Test the connection button. Every call carries the identity of the portal user (X-NM-On-Behalf-Of): its login (navin for the installation account, the preferred_username of a Keycloak or LDAP sign in). The Manager must know a user with that name, and its rights (services:install to install), approvals and stop rules apply.
3. Stop the sandbox: navin-manager/packaging/sandbox/sandbox.sh down (sandbox.sh status shows its state).