Skip to main content
This quickstart guide will help you set up MicroCBM locally and access the platform. By the end, you’ll have the application running and be able to log in to the dashboard.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20.x or higher installed
  • npm or your preferred package manager (yarn, pnpm, bun)
  • Access to the backend API URL (provided by your system administrator)
  • A valid user account and credentials
MicroCBM requires a running backend API. Without it, authentication will fail and data-dependent pages will show errors. Contact your system administrator for API access.

​
Quick Setup

1

Clone or download the repository

Get the source code for MicroCBM:
git clone <repository-url>
cd microcbm
2

Install dependencies

Install all required packages:
npm install
This will install all dependencies listed in package.json, including:
  • Next.js 15 and React 19
  • Form libraries (React Hook Form, Zod)
  • UI components (Radix UI, Recharts)
  • State management (Zustand, TanStack Query)
3

Configure environment variables

Create a .env.local file in the root directory with the following variables:
.env.local
NEXT_PUBLIC_API_URL=https://your-api-url.com
SESSION_SECRET=your-secret-key-here
Replace https://your-api-url.com with your actual backend API URL. The SESSION_SECRET should be a random string used for session encryption.
Environment Variables Explained:
  • NEXT_PUBLIC_API_URL: The base URL for your backend REST API (required)
  • SESSION_SECRET: A secret key for JWT session management (required)
4

Start the development server

Launch the application:
npm run dev
The application will start on http://localhost:3000. You should see output like:
▲ Next.js 15.5.9
- Local:        http://localhost:3000
- Ready in 2.1s
5

Access the application

Open your browser and navigate to:
http://localhost:3000
You’ll be automatically redirected to the login page at /auth/login.
6

Log in with your credentials

Enter your email and password on the login form:
  1. Enter your registered email address
  2. Enter your password (minimum 8 characters)
  3. Click Login
The login process uses server actions defined in src/app/actions/auth.ts:
src/app/actions/auth.ts
export async function loginService(payload: {
  email: string;
  password: string;
}): Promise<ApiResponse> {
  return handleApiRequest(`${commonEndpoint}/login`, payload);
}
7

Verify OTP code

After successful login credentials verification, you’ll be prompted to enter a 6-digit OTP code:
  1. Check your email for the OTP code
  2. Enter the 6-digit code in the OTP verification screen
  3. The code will auto-submit when all 6 digits are entered
The OTP verification is implemented in src/app/auth/components/OTPVerification.tsx and uses the verifyOTPService server action.
Once verified, you’ll be redirected to the dashboard at /.

​
Verify Installation

After logging in, you should see: ✅ Dashboard page with summary cards showing:
  • Asset analytics (total count, by criticality)
  • Alarm analytics (active alarms, by severity)
  • Recommendations summary
  • Sample trend charts
✅ Navigation sidebar with access to:
  • Dashboard
  • Assets
  • Samples
  • Alarms
  • Recommendations
  • RCA (Root Cause Analysis)
  • Organizations & Sites
  • User Management
✅ User menu in the top right corner

​
Common Issues

Problem: “Unable to connect to server” error messageSolution:
  • Verify NEXT_PUBLIC_API_URL is correct in .env.local
  • Check that the backend API is running and accessible
  • If using a free tier service (like Render), allow 30-60 seconds for cold start
Problem: No OTP email after loginSolution:
  • Check your spam/junk folder
  • Verify your email address is registered in the system
  • Contact your system administrator to check email service configuration
Problem: Pages show “You do not have permission” messagesSolution:
  • Verify your user account has the appropriate role assigned
  • Contact your system administrator to grant necessary permissions
  • Check the browser console for specific permission errors
Problem: Warnings during npm run dev or npm run buildSolution:
  • Warnings about dynamic routes using cookies are expected and harmless
  • Warnings about useFormContext in CheckboxCells.tsx are pre-existing and safe to ignore

​
Next Steps

Now that you have MicroCBM running:

Explore Features

Learn about asset management, samples, alarms, and more

Understand Architecture

Dive into the application structure and design patterns

Development Guide

Start developing and customizing MicroCBM

Deployment

Deploy MicroCBM to production environments

​
Available Scripts

Here are the key commands for working with MicroCBM:
package.json
# Start development server
npm run dev

# Build for production
npm run build

# Start production server (after build)
npm run start

# Run linter
npm run lint

# Update Iconify icons
npm run update-icons
For detailed installation instructions including Docker setup, advanced configuration, and troubleshooting, see the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us