Quick Start

Get Loopar running in under 5 minutes with a single command:

npx loopar-install my-project

That's it. The installer handles everything:

Clones the Loopar framework
Installs all dependencies with Yarn
Sets up PM2 process manager
Configures Caddy for production deployments
Creates the default dev site
Starts the development server

Once complete, open your browser:

http://localhost:3000

The setup wizard will guide you through database configuration and admin account creation. After that, you'll have access to the Desk — Loopar's visual development environment.

Note: Loopar uses PM2 as its process manager. All tenants (sites) are managed through PM2, providing process monitoring, automatic restarts, and centralized control.

Prerequisites

Before installing Loopar, ensure your system meets the following requirements:

Required

Requirement	Version	Notes
Node.js	22+	LTS version recommended
Yarn	1.x.x	Required — Loopar only works with Yarn Classic

⚠️ Important: Loopar requires Yarn 1.x.x (Classic). Yarn 2+ (Berry) and npm are not supported for the main project installation.

Automatically Installed

The loopar-install command automatically installs these dependencies:

Package	Purpose
PM2	Process manager for all sites
Caddy	Reverse proxy with automatic SSL (production)

If automatic installation fails, see Manual Dependencies Installation.

Database (one of the following)

Database	Version	Recommended For
MySQL	8.0+	Production environments
PostgreSQL	14+	Advanced features & scalability
MariaDB	10.6+	MySQL-compatible alternative
SQLite	3.x	Development & small deployments

Verify Your Environment

# Check Node.js version (must be 22+)
node --version

# Check Yarn version (must be 1.x.x)
yarn --version

Installing Node.js

If you need to install or update Node.js:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
nvm alias default 22

Or visit nodejs.org for direct downloads.

Installing Yarn Classic

# Install Yarn 1.x globally
npm install -g yarn@1

# Verify version
yarn --version
# Should output: 1.22.x

Installation

Automatic Installation (Recommended)

The fastest way to get started. One command does everything:

npx loopar-install my-project

The installer will:

✅ Clone the Loopar framework
✅ Install all dependencies with Yarn
✅ Install PM2 globally (if not present)
✅ Install Caddy (if not present)
✅ Create the default dev site
✅ Configure PM2 ecosystem
✅ Start the development server

After completion, open your browser at http://localhost:3000 to continue with the graphical setup wizard.

Manual Installation

For more control over the setup process or if automatic installation fails.

1. Clone the Repository

git clone https://github.com/alphabit-technology/loopar-framework.git my-project
cd my-project

2. Install Dependencies

yarn install

⚠️ Important: You must use Yarn 1.x.x. Do not use npm or Yarn 2+.

3. Start Development Server

npm run dev

This starts PM2 with the development ecosystem configuration.

Verify Installation

Once started, open your browser:

http://localhost:3000

You should see the Loopar setup wizard to configure your database and create your admin account.

Manual Dependencies Installation

If the automatic installer fails to install PM2 or Caddy, follow these instructions.

Installing PM2

PM2 is the process manager that runs all Loopar sites.

# Install PM2 globally
npm install -g pm2

# Verify installation
pm2 --version

Enable PM2 Startup (Optional)

To have PM2 start automatically on system boot:

pm2 startup
# Follow the instructions provided

# Save current process list
pm2 save

Installing Caddy

Caddy is required for production deployments with automatic SSL.

Ubuntu/Debian

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

CentOS/RHEL/Fedora

sudo dnf install 'dnf-command(copr)'
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy

macOS

brew install caddy

Windows

Download from caddyserver.com/download or use Chocolatey:

choco install caddy

Verify Installation

caddy version
# Output: v2.x.x

Start Caddy as Service

# Linux (systemd)
sudo systemctl enable caddy
sudo systemctl start caddy

# Check status
sudo systemctl status caddy

Note: Caddy is only required for production deployments. For local development, you can skip Caddy installation.

Setup Wizard

After running npx loopar-install, navigate to http://localhost:3000 to complete the setup.

Step 1: Database Configuration

Select your database type and provide connection details:

Field	Description	Example
Database Type	MySQL, PostgreSQL, SQLite, or MariaDB	MySQL
Host	Database server address	localhost
Port	Database port	3306
Database Name	Name of the database	loopar_db
Username	Database user	root
Password	Database password	•••••••

Tip: For quick development, use SQLite — it only requires a file path and works out of the box.

Step 2: Administrator Account

Create your admin credentials:

Field	Description
Full Name	Your display name
Email	Login email address
Password	Secure password (min. 8 characters)

Step 3: Project Information

Field	Description
Project Name	Display name for your application
Project Description	Brief description of your project

Completing Setup

After clicking Finish:

Loopar creates the database schema automatically
Core entities and system apps are installed
The dev site is fully configured
You're redirected to the login page

Architecture Overview

Loopar uses a multi-tenant architecture where all sites are managed from a central development site.

┌─────────────────────────────────────────────────────────────┐
│                     LOOPAR ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   sites/                                                    │
│   ├── dev/              ← Development & Admin Site          │
│   │   ├── Develop apps                                      │
│   │   ├── Manage tenants (create, start, stop)              │
│   │   ├── Assign domains                                    │
│   │   └── Deploy to production                              │
│   │                                                         │
│   ├── tenant-1/         ← Production Site                   │
│   │   └── domain: myapp.com                                 │
│   │                                                         │
│   └── tenant-2/         ← Production Site                   │
│       └── domain: client.com                                │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                         PM2                                 │
│   Manages all site processes independently                  │
├─────────────────────────────────────────────────────────────┤
│                        CADDY                                │
│   Automatic SSL & domain routing for production sites       │
└─────────────────────────────────────────────────────────────┘

Key Concepts

Concept	Description
Dev Site	The main development site where you build apps and manage tenants
Tenant	An independent site with its own database, domain, and configuration
PM2	Process manager that runs all sites independently
Caddy	Reverse proxy that handles SSL certificates and domain routing

Project Structure

Understanding Loopar's directory structure helps you navigate and extend your project effectively.

my-project/
├── apps/                    # Shared applications
│   └── loopar/              # Core Loopar app
│       ├── modules/         # Grouped entities by module
│       │   └── core/        # Core module
│       │       ├── entity/  # Entity definitions
│       │       │   ├── entity.json
│       │       │   ├── entity.js
│       │       │   └── entity.jsx
│       │       └── .../
│       └── public/          # Static assets (part of app)
├── sites/                   # Tenant sites
│   ├── dev/                 # Development site
│   │   ├── .env             # Site configuration
│   │   ├── installed-apps.json
│   │   ├── public/uploads/  # User uploads (site-specific)
│   │   └── sessions/
│   └── [tenant-name]/       # Other tenants
├── packages/                # Internal packages
│   ├── core/                # Server-side core
│   ├── components/          # React components library
│   └── tailwind/            # Tailwind configuration
├── loopar.ecosystem.config.mjs  # PM2 configuration
├── package.json
└── vite.config.js

Key Directories

Directory	Purpose
`apps/`	Shared applications available to all tenants
`sites/`	Individual tenant configurations and data
`sites/[tenant]/public/uploads/`	User-uploaded files (tenant-specific)
`packages/`	Internal framework packages

File Types

File	Purpose
`entity.json`	Field definitions, metadata, and structure
`entity.js`	Server-side controller (optional)
`entity.jsx`	Client-side React component (optional)
`.env`	Site-specific environment variables
`installed-apps.json`	Apps installed on this tenant

PM2 Commands

Loopar uses PM2 to manage all site processes. Here are the essential commands:

Development

# Start all sites in development mode
yarn dev

# View running processes
pm2 list

# View logs for all sites
pm2 logs

# View logs for specific site
pm2 logs dev

# Restart all sites
pm2 restart all

# Stop all sites
pm2 stop all

Managing Individual Sites

# Restart specific site
pm2 restart dev
pm2 restart tenant-name

# Stop specific site
pm2 stop tenant-name

# Start specific site
pm2 start tenant-name

# Delete site from PM2 (doesn't delete files)
pm2 delete tenant-name

Monitoring

# Real-time monitoring dashboard
pm2 monit

# Show detailed info for a site
pm2 show dev

# Show environment variables
pm2 env dev

Process Status

Status	Description
`online`	Site is running normally
`stopped`	Site was manually stopped
`errored`	Site crashed (check logs)
`launching`	Site is starting up

Tip: Most tenant management (start, stop, create, assign domain) can be done directly from the Desk interface in the dev site, without using the command line.

Tenant Management

All tenant operations are performed from the dev site through the Tenant Manager interface.

Accessing Tenant Manager

Navigate to http://localhost:3000/desk
Go to Core → Tenant Manager
View all tenants and their status

Creating a New Tenant

Click New Tenant in the Tenant Manager
Fill in the tenant details:
- Name: Unique identifier (e.g., my-client)
- Port: Unique port number (e.g., 3001)
- Apps: Select which apps to install
Save the tenant
The tenant is created in sites/[tenant-name]/

Tenant Actions

Action	Description
Start	Start the tenant process in PM2
Stop	Stop the tenant process
Restart	Restart the tenant process
Set Domain	Assign a domain for production
Deploy	Send to production with Caddy integration

Tenant Lifecycle

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Create    │ →   │  Development │ →   │  Production  │
│   (in dev)   │     │   (testing)  │     │ (with domain)│
└──────────────┘     └──────────────┘     └──────────────┘
                            ↓                     ↓
                     localhost:3001        myapp.com
                     NODE_ENV=dev         NODE_ENV=prod

Production Deployment

Deploying a tenant to production is done entirely from the dev site interface.

Prerequisites

Caddy running on your server
Domain configured to point to your server IP
Ports 80/443 open for HTTP/HTTPS traffic

Deploying a Tenant

Step 1: Configure the Tenant

Open Tenant Manager in the dev site
Select the tenant you want to deploy
Fill in production settings:
- Domain: myapp.com or subdomain.myapp.com
- Production Mode: Enable

Step 2: Deploy

Click Set on Production (or Deploy)
Loopar will automatically:
- Register the domain in Caddy
- Configure automatic SSL via Let's Encrypt
- Restart the tenant with NODE_ENV=production
- Enable production optimizations

What Happens Behind the Scenes

┌─────────────────────────────────────────────────────────────┐
│                  DEPLOYMENT PROCESS                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Validate domain configuration                           │
│                    ↓                                        │
│  2. Register domain in Caddy reverse proxy                  │
│                    ↓                                        │
│  3. Caddy obtains SSL certificate (Let's Encrypt)           │
│                    ↓                                        │
│  4. Update tenant environment (NODE_ENV=production)         │
│                    ↓                                        │
│  5. Restart PM2 process with production config              │
│                    ↓                                        │
│  6. Tenant is live at https://myapp.com                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Production vs Development

Aspect	Development	Production
NODE_ENV	`development`	`production`
HMR (Hot Reload)	✅ Enabled	❌ Disabled
Watch Mode	✅ Enabled	❌ Disabled
Bundle	Unoptimized	Minified & optimized
SSL	Not required	Automatic via Caddy
Domain	localhost:PORT	Custom domain

Independent Tenant Modes

Each tenant can run in its own mode independently:

sites/
├── dev/        → NODE_ENV=development (always)
├── staging/    → NODE_ENV=development (testing)
├── client-a/   → NODE_ENV=production  (live)
└── client-b/   → NODE_ENV=production  (live)

This allows you to have some tenants in production while others remain in development mode for testing.

Troubleshooting

Common issues and their solutions.

Yarn Version Issues

Error: This project requires Yarn 1.x.x

Solution: Install Yarn Classic:

npm install -g yarn@1
yarn --version
# Should output: 1.22.x

If you have Yarn 2+ installed globally, you can use corepack:

corepack disable
npm install -g yarn@1

PM2 Process Not Starting

# Check PM2 logs for errors
pm2 logs dev --lines 100

# Check if port is already in use
lsof -i :3000

# Restart with fresh state
pm2 delete all
yarn dev

Database Connection Failed

Error: Access denied for user 'root'@'localhost'

Solutions:

Verify database credentials in the setup wizard
Ensure the database server is running
Check that the database user has proper permissions:

CREATE DATABASE loopar_db;
GRANT ALL PRIVILEGES ON loopar_db.* TO 'user'@'localhost';
FLUSH PRIVILEGES;

PM2 Not Found

Command 'pm2' not found

Solution: Install PM2 manually:

npm install -g pm2
pm2 --version

Caddy Not Registering Domain

# Check if Caddy is running
sudo systemctl status caddy

# Check Caddy logs
journalctl -u caddy -f

# Verify Admin API is accessible
curl http://localhost:2019/config/

Common causes:

Caddy not running
Port 2019 blocked
Domain DNS not pointing to server

SSL Certificate Not Generated

Requirements for automatic SSL:

Domain must resolve to your server's IP
Ports 80 and 443 must be open
Caddy must be able to reach Let's Encrypt

# Test domain resolution
dig myapp.com

# Check if ports are open
sudo ufw status

Tenant Shows "Stopped" Status

# Check tenant logs
pm2 logs tenant-name --lines 50

# Restart the tenant
pm2 restart tenant-name

# Or restart from Desk interface

Node Version Mismatch

Error: The engine "node" is incompatible

Solution: Update Node.js to version 22+:

# Using nvm
nvm install 22
nvm use 22
nvm alias default 22

Next Steps

Congratulations! You have Loopar running. Here's what to explore next:

Learn the Fundamentals

Concepts — Understand Entities, Apps, Modules, and Builders
Learn — Step-by-step tutorials for building applications

Build Your First App

Navigate to http://localhost:3000/desk
Go to App → New App
Create your first Entity
Design a form using drag-and-drop
View your data in the auto-generated list view

Create Your First Tenant

Go to Core → Tenant Manager
Create a new tenant with a unique port
Install your app on the tenant
Test in development mode
When ready, assign a domain and deploy to production

Explore the Desk

Section	Purpose
App	Create and manage applications
Module	Organize entities into modules
Entity	Define data models and views
Page	Build custom pages and layouts
Tenant Manager	Create and manage tenant sites
Settings	Configure system settings

Join the Community

⭐ Star us on GitHub
🐛 Report issues or request features
🤝 Contribute to the project

Tip: The best way to learn Loopar is by building. Start with a simple app in the dev site, then create a tenant and deploy it. The visual environment makes it easy to experiment!