Customer onboarding guide

This guide is for an integrator standing up vibe_erp for a new customer end-to-end. It is written from a Tier 1 perspective: no plug-in code is required to follow it. Where Tier 2 plug-ins are useful, the guide says so.

For the architectural background, see ../architecture/overview.md. For the full v1.0 cut line, see section 11 of ../superpowers/specs/2026-04-07-vibe-erp-architecture-design.md.

Honest scope note

vibe_erp is a framework, not a turnkey product. The Tier 1 customization UIs (custom field designer, form designer, BPMN designer, list view editor, role editor) are v1.0 deliverables. The current build ships only the underlying API surface — the metadata tables, the REST endpoints, the seed data — without the polished UIs on top of them. Until v1.0 ships, the steps below that say "use the Customize UI" mean "POST to the metadata REST endpoints" or "edit a YAML seed file in your plug-in JAR". See PROGRESS.md for the current per-feature status.

This guide is written against the v1.0 experience. Where the current build deviates, the step is annotated (current: API only).

1. Install the host

vibe_erp ships as a single Docker image with PostgreSQL as the only mandatory external dependency.

docker run -d --name vibe-erp \
  -p 8080:8080 \
  -v /srv/vibeerp:/opt/vibe-erp \
  -e DB_URL=jdbc:postgresql://db.internal:5432/vibeerp \
  -e DB_USER=vibeerp \
  -e DB_PASSWORD=... \
  ghcr.io/vibeerp/vibe-erp:1.0.0

What happens on first boot:

1. The host connects to Postgres.
2. Liquibase runs every core PBC's migrations (plus flowable_* once that lands).
3. A bootstrap admin user is created and its one-time password is printed to the boot log.
4. The metadata loader walks the host classpath and seeds metadata__entity / metadata__permission / metadata__menu from each PBC's YAML file.
5. Each plug-in JAR is linted, migrated, metadata-loaded, and started in turn.
6. The host is ready in under 30 seconds.

The mounted volume /srv/vibeerp (mapped to /opt/vibe-erp inside the container) holds:

/opt/vibe-erp/
├── config/vibe-erp.yaml      single config file (closed key set)
├── plugins/                  drop *.jar to install
├── i18n-overrides/           operator translation overrides
├── files/                    file store (if not using S3)
└── logs/

Customer extensions live entirely outside the image. Upgrading the host is docker rm plus docker run with the new image tag — extensions and config stay put. vibe_erp is single-tenant per instance: this container serves exactly one company. Hosting a second customer means provisioning a second container with its own Postgres.

2. Log in as the bootstrap admin

Open http://<host>:8080/, log in with admin and the one-time password from the boot log, and change the password immediately. Configure OIDC (Keycloak-compatible) at this point if the customer has an existing identity provider — built-in JWT auth is live today; OIDC is P4.2 in the implementation plan and not yet wired.

3. Configure the instance

Set the company name, default locale, default currency, and default time zone in vibe-erp.yaml under vibeerp.instance.*. There is no "create a tenant" step — this entire instance belongs to one company.

4. Use the Customize UI to model the customer's reality

This is where most of the integrator's time is spent. Everything here is Tier 1: rows in metadata__* tables, tagged source = 'user'. No build, no restart, no deploy. (current: API only — POST to the metadata endpoints; the UIs ship in v1.0.)

Custom fields

Add custom fields to existing entities (item, partner, order, work order, …). Each custom field is a row in metadata__custom_field and a JSON key in the entity's ext JSONB column at runtime. A GIN index on ext keeps custom fields queryable. The form designer, list views, OpenAPI spec, and AI-agent function catalog all auto-update from the metadata.

For the rare hot-path field, an operator can promote a JSON key to a real generated column via an auto-generated Liquibase changeset. This is an optimization, not the default.

Custom forms

Define how each entity is displayed and edited. Forms are JSON Schema (data shape) plus UI Schema (layout and widgets), stored in metadata__form. Forms can reference custom fields by their key. See the form authoring guide.

Custom workflows

Draw the customer's process flow in the BPMN designer. Workflows are stored in metadata__workflow and deployed to the embedded Flowable engine. User tasks render forms; service tasks call typed TaskHandler implementations registered by plug-ins. See the workflow authoring guide.

Custom list views, rules, menus, reports

• List views (metadata__list_view): which columns, which filters, which default sort.
• Rules (metadata__rule): simple "if X then Y" automations for the cases that do not warrant a full BPMN workflow.
• Menus (metadata__menu): the navigation tree the user sees.
• Reports (metadata__report): JasperReports templates the customer can run on demand or on a schedule.

5. Import master data

vibe_erp accepts master data through two paths:

• CSV import through the Customize UI for one-off bulk loads (catalog items, partners, opening stock, chart of accounts). (current: API only.)
• REST API for ongoing integration with the customer's existing systems. Every entity, including custom fields, is exposed through OpenAPI-documented REST endpoints. The OpenAPI spec auto-updates as you add custom fields and custom entities, so the integration code is never out of date.

6. Configure roles and permissions

Define the customer's roles (e.g. sales clerk, production planner, warehouse operator, finance reviewer) and assign permissions. Permissions are auto-discovered from:

• Core PBCs.
• Plug-ins (each plug-in registers its own permissions through api.v1.security.PermissionCheck).
• Custom entities (each generates a standard CRUD permission set).

Bind users to roles. Once OIDC (P4.2) lands, roles can also be bound via the identity provider's group claims.

7. Add Tier 2 plug-ins as needed

When Tier 1 metadata is not expressive enough — for example, a printing-specific entity like plate spec with its own validation logic, or a workflow service task that calls an external MIS — install a Tier 2 plug-in.

To install a plug-in:

1. Drop the JAR into /opt/vibe-erp/plugins/.
2. Restart the host (docker restart vibe-erp). Hot reload is on the v1.2+ roadmap.
3. The plug-in loader scans the JAR, validates the manifest, runs the plug-in linter, runs the plug-in's Liquibase migrations in plugin_<id>__*, seeds the plug-in's metadata, and starts the plug-in.
4. Verify the plug-in shows up under /actuator/health and in the boot log.

The reference printing-shop plug-in (reference-customer/plugin-printing-shop/) is a worked example of a non-trivial Tier 2 plug-in. It expresses the workflows in raw/业务流程设计文档/ using only api.v1 and is built and CI-tested on every PR. It is not loaded by default — drop its JAR into ./plugins/ to use it.

A guiding principle: anything a Tier 2 plug-in does should also become possible as Tier 1 over time. Tier 2 is the escape hatch where Tier 1 is not yet expressive enough. When you find yourself reaching for a plug-in to do something a metadata row could express, file an issue against the framework.

8. Go-live checklist

• Backups configured against the Postgres instance. Customer data lives there exclusively (plus the file store).
• Audit log enabled for PII fields if the customer is subject to GDPR or equivalent.
• DSAR export and erasure jobs tested against a non-production copy.
• Locale, currency, time zone defaults set in vibe-erp.yaml.
• OIDC integration tested with the customer's identity provider (once P4.2 lands).
• Health check (/actuator/health) wired into the customer's monitoring.
• Documented upgrade procedure for the operator: docker rm plus docker run with the new image tag, plug-ins and config stay put.

What this guide deliberately does not cover

• Plug-in development. That is the plug-in author getting-started guide.
• Hosted operations (provisioning many independent vibe_erp instances, one per customer; billing; an operator console). vibe_erp is single-tenant per instance — hosting many customers means running many independent containers with their own databases. The provisioning console is a post-v1.0 deliverable.
• MCP / AI-agent endpoint. v1.1 deliverable. The seam exists today; the endpoint does not.