Native installation (dedicated server)

Native installation on Linux, without containers (see Requirements). The reference deployment used to install BIAM at customers is the container installation; this page is the alternative for those who prefer php-fpm + nginx on the server itself.

BIAM includes a Moodle-style web install wizard: the database and the first administrator are configured from the browser, not by editing files.

1. Prepare the system

# Ubuntu 24.04 — base packages
sudo apt install nginx postgresql-client \
  php8.4-fpm php8.4-pgsql php8.4-ldap php8.4-mbstring php8.4-xml \
  php8.4-curl php8.4-zip php8.4-intl php8.4-bcmath php8.4-opcache

On the database VM, create the database and role:

CREATE ROLE biam LOGIN PASSWORD '...';
CREATE DATABASE biam OWNER biam;

2. Deploy the code

# Backend
cd /opt/biam/backend
composer install --no-dev --optimize-autoloader

# SPA (skip if the release ships the build)
cd /opt/biam/frontend
npm ci && npm run build

The SPA is served alongside the backend, same origin (no CORS): nginx points its root at backend/public.

Permissions: storage/ and bootstrap/cache/ writable by the php-fpm user.

3. Services

• Cron (mandatory — lifecycle windows and connector health depend on it):

* * * * * cd /opt/biam/backend && php artisan schedule:run >> /dev/null 2>&1

• Queue worker (systemd):

[Service]
ExecStart=/usr/bin/php /opt/biam/backend/artisan queue:work --tries=3
Restart=always
User=www-data

4. Bootstrap .env

Start from backend/.env.example. The database connection is written by the wizard; what must be in place before opening it:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://biam.mycompany.com     # e-mail links are built from it
APP_TIMEZONE=America/La_Paz
APP_LOCALE=en

# Keys OWNED by this installation: the lines must exist. Generate APP_KEY BEFORE
# opening the browser — without it no page loads, the wizard's included.
APP_KEY=
JWT_SECRET=

# `file` while the wizard runs (the `cache` table does not exist yet);
# `database` afterwards, followed by `php artisan config:cache`
CACHE_STORE=file
SESSION_DRIVER=array
QUEUE_CONNECTION=database
DB_CONNECTION=main

BIAM_HUB_URL=https://hub.b-iam.com
BIAM_HUB_PUBLIC_KEY=<printed by `php artisan hub:public-key` on the Hub>
BIAM_HANDLERS_PATH=/opt/biam/backend/storage/app/handlers   # RPA handlers uploaded as zip, outside the code tree

cd /opt/biam/backend
sudo -u www-data php artisan key:generate --force   # replaces the APP_KEY= line (it must exist)
sudo -u www-data php artisan jwt:secret --force
sudo -u www-data php artisan storage:link

SMTP, the LDAP/AD connection and the license do not go in .env: they are configured from the console and stored encrypted in the database. Keys are never copied from another instance: with the same APP_KEY two installations share the key that encrypts credentials, and with the same JWT_SECRET a session is valid on both.

5. Install wizard

Open https://biam.mycompany.com/install and follow the three steps:

1. Database — the wizard tests the credentials before saving them and writes the DB_* variables to .env (if JWT_SECRET was left blank, it is generated here).
2. Migration — creates the schema and initial catalogs.
3. Administrator — creates the first root user with credentials you choose and closes the wizard in the same step.

There is no default username/password: until step 3 completes, nobody can log in; after it, the wizard locks itself (retries return INIT101W).

6. Post-install

cd /opt/biam/backend
sudo sed -i 's/^CACHE_STORE=.*/CACHE_STORE=database/' .env
sudo -u www-data php artisan config:cache      # required: closing the wizard left the config cached
sudo systemctl restart biam-queue              # the worker must start with the cache in the database
sudo -u www-data php artisan biam:handlers-migrate   # seeds BIAM_HANDLERS_PATH with the release handlers

Any later .env change follows the same rule: edit → config:cache as the php-fpm user → restart the worker.

• Backups: pg_dump of the database + storage/app/ (installed connector packages and the install marker live there).
• Optional: at-rest .env encryption with php artisan env:encrypt (an ops task).
• Configure the LDAP/AD connection from the console (Settings) — it is stored encrypted in the database, not in .env.