PluginEnv

Two layers of configuration: process env / base .env for infrastructure (Postgres, Redis), and plugin-scoped Env via @InjectEnv — persisted in the env table with isPublic / isSecret flags.

Two configuration layers

Base process env — DB_*, Redis, MODE, paths from base/backend/.env or Docker Compose; read with process.env (e.g. @Database options)
Plugin Env (@InjectEnv) — key/value scoped to the current plugin; loaded from Postgres on boot; editable from the ERP env UI / /env API
Do not put secrets in git — keep them in .env (local) or the env table (runtime)
Full base process-env catalog — see Environment variables

Base environment (.env)

Infrastructure connection settings for the base app and workers. Typical keys live in base/backend/.env and are wired through Docker Compose. For the complete key list, open Environment variables.

DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_SCHEMA — Postgres
DB_SYNC — optional TypeORM synchronize flag (dev only)
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD — cache, queues, BullMQ cron
In Compose, DB_HOST is usually the service name db (not localhost inside containers)
On the host for local psql / module seed, use localhost / 127.0.0.1

TSbase/backend/.env (example)

DB_HOST=db
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_SCHEMA=quan_erp
DB_SYNC=false
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

@InjectEnv

Inject the Env helper on a module, service, workflow node, or other DI-resolved class. The instance is scoped to the current plugin — get/set only see that plugin’s keys.

TSXinject

import {
  Env,
  InjectEnv,
  Module,
  OnInit,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class PaymentConfigService {
  @InjectEnv()
  private env: Env;

  getApiKey() {
    return this.env.get("API_KEY");
  }
}

@Module({
  name: metadata.name,
  providers: [PaymentConfigService],
  controllers: [],
  entities: [],
})
export class MyPluginModule {
  @InjectEnv()
  env: Env;

  @OnInit()
  async init() {
    // seed defaults — see below
  }
}

Env API

get(key) — read a plugin-scoped value (secrets decrypted)
set(key, value, options?) — write; defaults from injection: { isPublic: false, sync: true, isSecret: false }
sync() — persist the in-memory registry to the env table
onChanged(key, callback) — react when that key changes (UI update, set, etc.)
clear() — wipe this plugin’s env entries and clear DB via EnvService
all() — all keys for this plugin with value / isPublic / isSecret

TSXget / set / sync

import { Env, InjectEnv, OnInit, Service } from "@quan-erp/shared-backend-core";

@Service()
export class IntegrationSettingsService {
  @InjectEnv()
  private env: Env;

  @OnInit()
  async init() {
    if (!this.env.get("API_BASE_URL")) {
      await this.env.set("API_BASE_URL", "https://api.example.com", {
        isPublic: true,
        isSecret: false,
        sync: true,
      });
    }

    if (!this.env.get("API_KEY")) {
      await this.env.set("API_KEY", "", {
        isPublic: false,
        isSecret: true,
        sync: true,
      });
    }

    this.env.onChanged("API_KEY", () => {
      // reload clients that cache the key
    });
  }

  async rotateKey(next: string) {
    await this.env.set("API_KEY", next, {
      isSecret: true,
      sync: true,
    });
  }
}

set() options

sync (default true via InjectEnv proxy) — write through to Postgres immediately
isPublic — exposed on GET /env/public for frontend / unauthenticated public env
isSecret — encrypted at rest; masked in owner env listings (maskSecret)
Prefer isSecret: true for API keys, tokens, and passwords
Prefer isPublic: true only for non-sensitive values the UI must read without owner rights

Persistence & boot

On startup the core loads rows from the env table into PluginEnvConfigManager. Changes via set({ sync: true }) or env.sync() upsert through EnvService. Uninstall / clear removes plugin-scoped entries.

Table: env (EnvEntity) — pluginName, key, value, isPublic, isSecret
Boot: PluginEnvConfigManager.loadFromDB()
Secrets stored encrypted (base64 of encrypt JSON); get() decrypts for the owning plugin
Admin UI / API can bulk-update and may broadcast a restart status after /env/many

HTTP surface (core)

GET /env — owner; all plugins’ env with secrets masked
GET /env/public — public keys only (isPublic: true)
GET /env/db — owner; raw rows from EnvService
PUT /env — set one key (plugin, key, val) with sync
PUT /env/many — bulk set then syncToDB
Plugin code should use @InjectEnv() rather than calling these HTTP routes

When to use which

process.env / .env — hosts, ports, Redis, compose wiring, @Database connection options
@InjectEnv — per-tenant or per-plugin settings operators change from the ERP UI without redeploy
DeveloperConfigService — typed plugin developer config (different from Env); see Builtin Services
SettingEntity / SettingService — user or system settings UI; not the same as plugin Env

Local-only operations

Module table seeding and similar setup scripts that read DB_* from .env must target local/dev hosts only (localhost / 127.0.0.1). Never run against UAT or production.

See Module seed for the local INSERT pattern
If DB_HOST is a remote UAT/prod host, stop

Package versions

Align @quan-erp/* versions in plugin package.json with the base image / shared-backend-core version so Env injection and crypto helpers stay compatible.

Checklist

Keep infrastructure secrets in base/backend/.env — not in source
Inject with @InjectEnv() on property (constructor injection unsupported)
Seed missing keys in @OnInit with explicit isPublic / isSecret / sync
Mark API keys isSecret: true
Use isPublic only for safe, UI-readable values
Call sync() (or sync: true) after writes you need persisted across restart