# Deployment Guide

This guide provides instructions for deploying the **Karma Core** and **Admin Console** applications.

## Prerequisites

- **Node.js**: v20 or higher
- **pnpm**: v8 or higher
- **Docker** (optional, for containerized deployment)

## 1. Installation

Since `node_modules` have been deleted, you must reinstall dependencies. run this command from the project root:

```bash
pnpm install
```

> **Note:** If you encounter workspace issues, ensure `pnpm-workspace.yaml` is present in the root.

## 2. building the Applications

### Admin Console (@karma/admin-console)

The Admin Console is a React application utilizing Vite.

**Build Command:**

```bash
# From root
pnpm build:admin-console

# OR from apps/admin-console
cd apps/admin-console
pnpm build
```

**Output:**
The build artifacts will be located in `apps/admin-console/dist` (or `build` depending on vite config).

**Docker Build:**

```bash
# From project root
docker build -f apps/admin-console/Dockerfile -t karma-admin-console .
```

### Core (@karma/core)

The Core application is a Hono/Node.js service.

**Build Command:**

```bash
# From root
pnpm build:core

# OR from apps/core
cd apps/core
pnpm build
```

**Output:**
The compiled JavaScript files will be located in `apps/core/dist`.

**Docker Build:**

```bash
# From project root
docker build -f apps/core/Dockerfile -t karma-core .
```

## 3. Deployment

### Using Docker (Recommended)

Both applications include comprehensive `Dockerfile` configurations optimized for production.

1.  **Build Images**: Use the Docker commands above.
2.  **Run Containers**:
    *   Ensure environment variables are set (refer to `.env.example` in respective apps).
    *   Map ports as needed (Core: 8787, Admin: 3000).

### Manual Deployment

1.  **Core**:
    *   Build the app.
    *   Run `node dist/index.js` (ensure environment variables are loaded).
    *   Process manager like PM2 is recommended: `pm2 start apps/core/dist/index.js --name karma-core`.
    *   Or start everything from the repo's process list: `pm2 start ecosystem.config.js`.
        Note that restarting core alone (`pm2 restart core`) does **not** start the
        SMTP worker — a newly added process has to be started once explicitly:
        `pm2 start ecosystem.config.js --only smtp-worker`.

2.  **Admin Console**:
    *   Build the app.
    *   Serve the `dist` directory using a static file server (e.g., Nginx, Serve).
    *   Or run the server output if using SSR (refer to `server.js`).

3.  **SMTP Worker** (`workers/smtp`):
    *   Build it (`pnpm build` from the root covers it — it is a workspace package
        with its own `build` script).
    *   Create `workers/smtp/.env` on the server from `.env.example`. It is
        gitignored, so it does not arrive with a deploy and must exist before the
        process starts — the worker refuses to start without it rather than running
        and silently sending nothing.
    *   Run it with PM2: it is listed in `ecosystem.config.js` as `smtp-worker`.

    No port and no HTTP: it consumes the mail queue and calls SendGrid. It does not
    have to run on the core server — it needs TCP to the broker and outbound HTTPS
    to SendGrid, nothing else.

    **Nothing in core sends member mail.** If this process is not running, mail
    accumulates on the queue and nobody receives anything, with no error anywhere in
    core. Check the queue's consumer count to tell the difference between "not sent"
    and "not delivered".

### Marketing CMS (@karma/marketing-cms)

The Marketing CMS is a Next.js application.

**Build Command:**

```bash
# From root
pnpm build:marketing-cms

# OR from apps/marketing-cms
cd apps/marketing-cms
pnpm build
```

**Docker Build:**

```bash
# From project root
docker build -f apps/marketing-cms/Dockerfile -t karma-marketing-cms .
```

### Marketing Landing Page (@karma/marketing-landing-page)

The Marketing Landing Page is a Next.js application.

**Build Command:**

```bash
# From root
pnpm build:marketing-landing-page

# OR from apps/marketing-landing-page
cd apps/marketing-landing-page
pnpm build
```

**Docker Build:**

```bash
# From project root
docker build -f apps/marketing-landing-page/Dockerfile -t karma-marketing-landing-page .
```