> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise Self-Hosted Deployment

> Deploy Alforse on customer-controlled infrastructure with an enterprise self-hosted license.

Alforse ships two public deployment paths. They use different operating assumptions and should
not share secrets or environment files:

* **Alforse Cloud** — the hosted product at `*.alforse.com`. Tenant access is created through
  assisted onboarding or a redemption code; see [Quickstart](/quickstart).
* **Enterprise self-hosted** — a customer-operated runtime for organizations with a signed
  enterprise self-hosted license. This page covers the public deployment sequence for that
  licensed package.

<Note>
  The self-hosted runtime (`EDITION=self_hosted`) requires the `self_hosted` commercial plan
  and a signed license file. It is not the internal Alforse engineering runtime. See
  [Plans & Editions](/concepts/plans-and-editions) before preparing infrastructure.
</Note>

## Prerequisites

* Enterprise self-hosted license file and public verification key from Alforse.
* A customer-controlled deployment host or container platform.
* Docker and Docker Compose, or equivalent orchestration for the API, PostgreSQL, Redis, and
  S3-compatible object storage.
* PostgreSQL 15+ for system metadata and PostgreSQL 15+ for tenant data. Keep these databases
  separate.
* Redis for sessions, rate limits, and request nonces.
* S3-compatible object storage for contract originals, invoice evidence, and payment proof.
* TLS-terminated public origins for the API and user-facing applications.
* SMTP or an approved transactional email provider for password reset, invitations, and MFA
  backup codes.
* A file scanning service if downloadable files must require a clean security scan.

## 1. Confirm the licensed package

Before deployment, confirm that your package includes:

* The API container image or source mirror authorized for your license.
* `apps/api/docker-compose.self-hosted.yml` or the equivalent orchestration manifest.
* A signed license file for the intended tenant, plan, and expiry window.
* The environment variable list reviewed for your infrastructure.
* The onboarding instructions for creating the first tenant administrator.

## 2. Configure environment variables

Self-hosted deployments use the same variable names documented in
[Configuration](/configuration), but the values must point to customer-managed infrastructure.
Do not reuse the hosted SaaS values.

At minimum, prepare:

* `EDITION=self_hosted`
* `NODE_ENV=production`
* `LICENSE_FILE`
* `LICENSE_PUBLIC_KEY`
* `PLATFORM_DATABASE_URL` and `PLATFORM_APP_DATABASE_URL`
* `TENANT_DATABASE_URL` and `TENANT_APP_DATABASE_URL`
* `REDIS_URL`
* `OSS_ENDPOINT`, `OSS_BUCKET`, `OSS_ACCESS_KEY`, `OSS_SECRET_KEY`, `OSS_REGION`
* `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`, `MFA_SECRET_KEY`, `API_HMAC_SECRET`
* `API_PUBLIC_URL`, `WEB_PUBLIC_URL`, `DEALS_PUBLIC_URL`, `CONSOLE_PUBLIC_URL`
* Email, Turnstile, file scanning, OCR, and SSO values required by your operating model

<Warning>
  Treat every value marked **Secret** in [Configuration](/configuration) as production
  credentials. Store them in your secret manager or a protected environment file with restricted
  access.
</Warning>

## 3. Prepare infrastructure

If you use the provided Compose file, it starts the API with PostgreSQL, Redis, and
S3-compatible object storage. For a managed platform, map the same services into your own
orchestrator and keep the database split intact:

* System metadata database: tenants, plans, subscriptions, licenses, and integration metadata.
* Tenant data database: contracts, payments, files, dynamic fields, audit events, and workflow
  state.
* Object storage bucket: original documents, invoice files, and evidence files.
* Redis: sessions, refresh-token revocation, request signatures, and rate limiting.

<Accordion title="Running without Docker">
  Point these variables at your managed services, then continue with the database setup:

  * `PLATFORM_DATABASE_URL`, `PLATFORM_APP_DATABASE_URL`
  * `TENANT_DATABASE_URL`, `TENANT_APP_DATABASE_URL`
  * `REDIS_URL`
  * `OSS_ENDPOINT`, `OSS_BUCKET`, `OSS_ACCESS_KEY`, `OSS_SECRET_KEY`, `OSS_REGION`

  For file-scan confirmation, set `FILE_SCAN_MODE=external` with `FILE_SCAN_ENDPOINT` and
  `FILE_SCAN_API_KEY`.
</Accordion>

## 4. Set up the databases

Alforse uses two Prisma schemas — `prisma/platform` and `prisma/tenant` — that must both be
generated and migrated:

```bash theme={null}
npm run prisma:generate
npm run prisma:migrate
npm run db:seed
```

`db:seed` creates system plans, default roles, the permission matrix, and workflow controls
that the app expects to exist.

## 5. Start the licensed runtime

```bash theme={null}
cd apps/api
docker compose -f docker-compose.self-hosted.yml up -d --build
```

The API listens on `PORT` and mounts every route under `/api/v1`. Put it behind your approved
TLS proxy or ingress before inviting tenant users.

## 6. Create the first tenant administrator

Coordinate first-tenant creation with your Alforse implementation contact or the licensed
onboarding flow included with your package. The first tenant administrator should be created
after plan, license, MFA, password-reset, and recovery settings are confirmed.

## 7. Verify the deployment

```bash theme={null}
curl https://api.your-company.example/api/v1/health
```

A healthy response looks like this:

```json theme={null}
{
  "status": "ok",
  "edition": "self_hosted",
  "platformDb": "up",
  "tenantDb": "up",
  "time": "2026-07-03T12:00:00.000Z",
  "isolate": "a1b2c3"
}
```

`status: "degraded"` with `platformDb` or `tenantDb` set to `"down"` means the API can't reach
one of the two databases. Recheck the database URLs, network access, TLS settings, and
credentials from step 2.

## Operational checks

Before going live, verify:

* Tenant admins must enroll MFA when required.
* Password reset, invitation, and backup-code emails are delivered.
* File uploads cannot be downloaded until scan policy requirements pass.
* Object storage lifecycle and backup policies meet your retention requirements.
* API request signing is enabled for non-browser integrations.
* Monitoring polls `GET /health` and alerts on `degraded`.
* Database backups and restore procedures have been tested.