Getting Started

You need five things installed before you can run LAMISPlus locally: Node.js 20, pnpm, Java 21, PostgreSQL, and Maven. The setup takes about 20 minutes on a fresh machine.

Prerequisites

Tool	Minimum	Install
Node.js	20.x	nvm recommended
pnpm	9.x	npm install -g pnpm
Java	21	SDKMAN recommended
PostgreSQL	14+	Homebrew or apt
Maven	3.9+	Bundled if using your IDE, or via SDKMAN
RAM	8 GB min	16 GB recommended

# Quick install via NVM + SDKMAN
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
nvm install 20 && nvm use 20
npm install -g pnpm
curl -s "https://get.sdkman.io" | bash
sdk install java 21.0.1-open

Clone and install frontend dependencies

git clone <repository-url>
cd Lamisplus3.0/ui
pnpm install    # installs all workspace packages in one go

Set up the database

sudo -u postgres psql << 'EOF'
CREATE DATABASE lamisplus_db;
CREATE USER lamisplus_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE lamisplus_db TO lamisplus_user;
EOF

Configure the backend

Export these before running, or put them in a .env file:

export DB_USERNAME=lamisplus_user
export DB_PASSWORD=your_secure_password
export JWT_SECRET=your-256-bit-base64-encoded-secret-key
export PLUGIN_STORAGE_PATH=/opt/lamisplus/plugins

Create the plugin storage directory:

mkdir -p /opt/lamisplus/plugins

The plugin storage directory must not be inside target/. Maven's clean phase will delete everything in target/, including installed plugin JARs. You'd have to re-upload them every time you clean-built. /opt/lamisplus/plugins is a safe choice.

Start the backend

cd api/lamisplus-core
mvn spring-boot:run \
  -Dspring-boot.run.profiles=dev \
  -Dspring-boot.run.jvmArguments="-Dplugins.storage.path=/opt/lamisplus/plugins"

The API starts on http://localhost:8789. Liquibase runs migrations automatically on first start, you don't need to create tables manually.

Start the frontend

Open a separate terminal for each app you want to run. Core must always start first.

# Terminal 1, always required
pnpm dev:core

# Terminal 2+, only start what you need
pnpm dev:ehr                    # EHR / outpatient
pnpm dev:pbh                    # Public health (HIV/ART, TB…)
pnpm dev:appointments           # Appointment scheduling
pnpm dev:inpatient              # Inpatient and ward management
pnpm dev:invoicing_and_billing  # Billing and invoices
pnpm dev:reports                # Reporting

Open the application at http://localhost:3000.

All workspace commands

Run these from the ui/ directory:

Command	What it does
pnpm dev:core	Start the Core shell
pnpm dev:ehr	Start the EHR plugin
pnpm dev:pbh	Start the Public Health plugin
pnpm dev:appointments	Start the Appointments plugin
pnpm dev:inpatient	Start the Inpatient plugin
pnpm dev:invoicing_and_billing	Start the Billing plugin
pnpm dev:reports	Start the Reports plugin
pnpm dev:remote	Start all plugin remotes in parallel
pnpm dev:docs	Start this documentation site
pnpm restart:core	Kill and restart Core
pnpm kill:ports	Kill all dev server ports
pnpm build	Production build of all apps
pnpm typecheck	Type-check everything
pnpm lint	Lint all apps

Scaffold a new plugin

cd ui
./create-plugin.sh <name> [port]

# Example
./create-plugin.sh radiology 3007

The script creates the plugin folder, registers it with Core, and adds the pnpm scripts. See Creating Plugins for the full guide.

Troubleshooting

Port already in use

pnpm restart:core   # kills 3000 and restarts
pnpm kill:ports     # kills all app ports

Module not found with @/ imports
Check that tsconfig.json and rspack.config.ts have matching paths / alias entries, then restart the dev server.

Changes not showing in Core after editing a plugin
Restart Core. Module Federation caches remote manifests, Core won't pick up changes to a plugin's exposed modules until it restarts.

Plugin missing after backend restart
If PLUGIN_STORAGE_PATH was inside target/ and you ran mvn clean, the JARs are gone. Re-upload them via the admin panel and set a persistent path for next time.