# Installation in Minutes

MemberJunction is an open-source platform designed to help organizations efficiently manage data, build applications, and leverage AI for better insights. This installation guide will walk you through the complete setup process, from initial requirements to final configuration.

<br />

# Installation in Minutes

MemberJunction is an open-source platform for managing data, building applications, and leveraging AI. This guide gets you from zero to a running MemberJunction installation as quickly as possible.

## Prerequisites

1. **SQL Server 2022+** — Local instance (including Docker) or Azure SQL. You do **not** need to create a database ahead of time.
   > If using a local SQL Server with a self-signed certificate (common with Docker), the installer will ask if you want to trust it. Azure SQL handles this automatically.

2. **Node.js 22+** (Node.js 24 recommended) — Install from [nodejs.org](https://nodejs.org)

3. **At least 2 GB of free disk space**

4. **An empty working directory** — We recommend making it a Git repo so you can track your customizations.

***

## Choose Your Installation Method

You can install MemberJunction using either the **VSCode Extension** (recommended — visual, guided) or the **CLI** (for scripting or terminal-only environments). Both methods run the same installer under the hood.

***

## Option A: Install with the VSCode Extension (Recommended)

The VSCode extension provides a visual wizard that walks you through every step.

### 1. Install the Extension

Open Visual Studio Code (v1.85.0 or higher) and install the MemberJunction extension:

* Open the **Extensions** view (`Ctrl+Shift+X` / `Cmd+Shift+X`)
* Search for **"MemberJunction"** and click **Install**

> If the extension is not yet on the Marketplace, install from a `.vsix` file: click the `...` menu in the Extensions view → **Install from VSIX...** → select the file.

### 2. Open the Installer Wizard

Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:

```
MemberJunction: Install
```

You can also click the **MJ Installer** status bar item at the bottom of VSCode, or find the **Install MemberJunction** button in the MemberJunction sidebar.

### 3. Walk Through the Wizard

The wizard guides you through 6 steps before installation begins:

**Step 1 — Welcome:** Select **Install** to start a new installation.

**Step 2 — Location & Version:** Browse to your empty working directory and choose which MemberJunction version to install (latest is selected by default).

**Step 3 — Database:** Enter your SQL Server connection details:

* Hostname (default: `localhost`), port (default: `1433`)
* Database name (default: `MemberJunction`)
* Whether to trust self-signed certificates
* CodeGen login credentials (for schema management)
* API login credentials (for runtime data access)

> You can load saved settings from a config file if you've installed before.

**Step 4 — Services & Authentication:** Choose your authentication provider:

* **Microsoft Entra (MSAL)** — enter your Tenant ID and Client ID
* **Auth0** — enter your Domain, Client ID, and Client Secret
* **Skip for now** — you can set this up later (MJExplorer won't fully work until you do)

**Step 5 — Options:** Optional flags like Fast Mode, Skip Smoke Test, Overwrite Config, etc.

**Step 6 — Review:** Review all your settings, then click **Start Installation**.

### 4. Run the Database Scripts

During installation, the wizard will show a message that SQL scripts have been generated. You need to run these manually:

1. Open `mj-db-setup.sql` (in your working directory) in SQL Server Management Studio, Azure Data Studio, or any SQL client
2. Connect as an administrator (`sa` or a `sysadmin` login)
3. Execute the script — it creates the database, schema, logins, users, and permissions
4. Optionally run `mj-db-validate.sql` to verify everything was created correctly

> **Why manual?** Creating server-level logins requires elevated permissions that the installer shouldn't hold.

Once done, the installer continues automatically through the remaining phases.

### 5. Start MemberJunction

After the installer finishes (you'll see a success banner in the wizard), open two terminal windows:

**Terminal 1 — Start the API server:**

```
npm run start:api
```

**Terminal 2 — Start the Explorer UI** (after MJAPI is running):

```
npm run start:explorer
```

Open **<http://localhost:4201>** in your browser. You should see the MJExplorer login page. That's it!

***

## Option B: Install with the CLI

If you prefer a terminal-based workflow or need to script the installation.

### 1. Install the MJ CLI

```
npm install --global @memberjunction/cli
```

Verify:

```
mj version
```

### 2. Run the Installer

Navigate to your empty working directory and run:

```
mj install
```

The installer prompts you for the same settings as the VSCode wizard (database, auth, ports) and runs through all 9 phases automatically.

### 3. Run the Database Scripts

Same as the VSCode flow — after the configure step, run `mj-db-setup.sql` manually, then the installer continues.

### 4. Start MemberJunction

Same as above — `npm run start:api` then `npm run start:explorer`, then open **<http://localhost:4201>**.

***

## What the Installer Does

Both the VSCode extension and CLI run the same 9-phase installer:

| # | Phase            | What It Does                                                                         |
| - | ---------------- | ------------------------------------------------------------------------------------ |
| 1 | **Preflight**    | Checks Node.js version, disk space, port availability, SQL Server connectivity       |
| 2 | **Scaffold**     | Downloads the selected MemberJunction release from GitHub                            |
| 3 | **Configure**    | Generates `.env`, `mj.config.cjs`, and Explorer `environment.ts` from your inputs    |
| 4 | **Database**     | Generates SQL setup scripts (you run these manually)                                 |
| 5 | **Platform**     | Applies OS-specific patches (e.g., `cross-env` on Windows)                           |
| 6 | **Dependencies** | Runs `npm install` and `npm run build` (\~170 packages)                              |
| 7 | **Migrate**      | Applies database migrations (tables, views, stored procedures, seed data)            |
| 8 | **CodeGen**      | Generates TypeScript entity classes, Angular forms, and class registration manifests |
| 9 | **Smoke Test**   | Starts MJAPI and MJExplorer to verify they launch, then shuts them down              |

***

## If Something Goes Wrong

### Resume a Failed Install

The installer saves progress after each phase. To resume:

* **VSCode:** Open the Command Palette → `MemberJunction: Resume Install`
* **CLI:** Just run `mj install` again

### Start Completely Fresh

* **VSCode:** Check **"Fresh Start"** in the Options step
* **CLI:** `mj install --no-resume`

### Run Diagnostics

* **VSCode:** Open the Command Palette → `MemberJunction: Doctor`
* **CLI:** `mj doctor`

### Generate a Diagnostic Report

```
mj doctor --report
```

Creates `mj-diagnostic-report.md` with environment info, install state, and config (passwords automatically redacted). Share this when requesting support.

For a more detailed report with config file snapshots and service startup logs:

```
mj doctor --report_extended
```

***

## Authentication Setup

MJExplorer requires an authentication provider. If you skipped this during installation, set it up now.

### Microsoft Entra (MSAL)

1. Register an app in [Azure Portal > App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
2. Note the **Application (client) ID** and **Directory (tenant) ID**
3. Under **Authentication**, add `http://localhost:4201` as a **Single-page application** redirect URI
4. Add to your `.env` (root and `packages/MJAPI/.env`):
   ```
   TENANT_ID=your-tenant-id
   WEB_CLIENT_ID=your-client-id
   ```
5. Add to `packages/MJExplorer/src/environments/environment.ts` (and `environment.development.ts`):
   ```typescript
   AUTH_TYPE: 'msal' as const,
   CLIENT_ID: 'your-client-id',
   TENANT_ID: 'your-tenant-id',
   CLIENT_AUTHORITY: 'https://login.microsoftonline.com/your-tenant-id',
   ```

### Auth0

1. Create an app in your [Auth0 Dashboard](https://manage.auth0.com/)
2. Note the **Domain**, **Client ID**, and **Client Secret**
3. Under **Settings > Application URIs**, add `http://localhost:4201` as an Allowed Callback URL
4. Add to your `.env`:
   ```
   AUTH0_DOMAIN=your-domain.us.auth0.com
   AUTH0_CLIENT_ID=your-client-id
   AUTH0_CLIENT_SECRET=your-client-secret
   ```
5. Add to **Explorer environment files**:
   ```typescript
   AUTH_TYPE: 'auth0' as const,
   AUTH0_DOMAIN: 'your-domain.us.auth0.com',
   AUTH0_CLIENTID: 'your-client-id',
   ```

After editing, restart both MJAPI and MJExplorer.

***

## Updating an Existing Installation

There is no in-place updater yet. To update to a newer version:

* **VSCode:** Check **"Fresh Start"** in the Options step and select the new version
* **CLI:** `mj install --no-resume` and select the new version
* Or delete the install directory and do a fresh install

***

## CLI Reference

| Flag                   | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| `-t v5.49.0`           | Install a specific version                                      |
| `--fast`               | Skip smoke test and optimize codegen                            |
| `--skip-db`            | Skip database phases (if DB is already set up)                  |
| `--skip-start`         | Skip the smoke test at the end                                  |
| `--overwrite-config`   | Regenerate all config files instead of preserving existing ones |
| `--no-resume`          | Ignore checkpoint and start fresh                               |
| `--dry-run`            | Preview the install plan without executing                      |
| `--verbose`            | Show detailed output                                            |
| `--yes`                | Non-interactive mode (auto-select latest, use defaults)         |
| `--config ./file.json` | Load settings from a JSON config file                           |

***

## Troubleshooting

| Problem                            | Solution                                                                                                                               |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| MJExplorer stuck on loading screen | Auth not configured — see [Authentication Setup](#authentication-setup). Also try clearing browser Local Storage for `localhost:4201`. |
| Database migrations fail           | Make sure you ran `mj-db-setup.sql` first.                                                                                             |
| `npm install` fails with ERESOLVE  | Installer retries automatically. If it persists, verify Node.js 22+.                                                                   |
| Build fails for generated packages | Expected on first install — CodeGen regenerates them automatically.                                                                    |
| Ports 4000 or 4201 in use          | Stop the conflicting process, or choose different ports during install.                                                                |
| Install failed partway through     | Resume with `mj install` (CLI) or the Resume command (VSCode). Use `--no-resume` / "Fresh Start" to start over.                        |

<br />