> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loglife.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Local development workflow for the LogLife website and plugin

## Local setup

<Warning>
  LogLife is developed and tested on **Linux**. If you are on Windows, use **WSL**. macOS may work but is not fully tested — proceed at your own risk.
</Warning>

<Info>
  **Prerequisites**:

  * Node.js 19+, pnpm
  * OpenClaw installed (see [Self-hosting](/self-hosting))
  * **Two phone numbers**: one for the OpenClaw bot (its WhatsApp account) and one to message from (your personal phone). You cannot send messages to yourself on WhatsApp.
</Info>

<Steps>
  <Step title="Start the OpenClaw gateway">
    ```bash theme={null}
    cd ~/openclaw
    ./openclaw.mjs gateway --allow-unconfigured
    ```

    The gateway runs on port 18789 by default. The LogLife plugin is loaded automatically if installed (see [Self-hosting](/self-hosting) for plugin installation).
  </Step>

  <Step title="Start the website">
    ```bash theme={null}
    cd loglife/website
    pnpm install
    pnpm dev
    ```

    The dashboard is at `http://localhost:3000/dashboard`.
  </Step>

  <Step title="Edit, restart, test">
    When you change `plugin/index.ts`, restart the local gateway to pick up the changes. The website hot-reloads automatically.

    Use the helper script:

    ```bash theme={null}
    bash plugin/scripts/restart-local-gateway.sh
    ```
  </Step>
</Steps>

## CI/CD

LogLife uses two CI/CD pipelines: GitHub Actions for testing and plugin deployment, and Vercel for the website.

### GitHub Actions secrets

If you fork this repository, you need to add the following secrets in **Settings > Secrets and variables > Actions**:

| Secret                              | Used by      | Description                                                 |
| ----------------------------------- | ------------ | ----------------------------------------------------------- |
| `SERVER_HOST`                       | `deploy.yml` | Public IP or hostname of the production server              |
| `SERVER_USER`                       | `deploy.yml` | SSH username on the production server                       |
| `SSH_PRIVATE_KEY`                   | `deploy.yml` | Private SSH key authorized on the server (see below)        |
| `LOGLIFE_API_KEY`                   | `deploy.yml` | LogLife plugin API key — used for post-deploy health checks |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | `ci.yml`     | Clerk publishable key — needed for the website build step   |

<Tip>
  Generate a dedicated deploy key instead of using your personal SSH key:

  ```bash theme={null}
  ssh-keygen -t ed25519 -f ~/.ssh/loglife_deploy -N "" -C "loglife-deploy"
  cat ~/.ssh/loglife_deploy.pub >> ~/.ssh/authorized_keys
  cat ~/.ssh/loglife_deploy  # paste this as SSH_PRIVATE_KEY
  ```
</Tip>

### Vercel environment variables

Set these in your [Vercel project settings](https://vercel.com/docs/environment-variables):

| Variable                            | Description                                        |
| ----------------------------------- | -------------------------------------------------- |
| `OPENCLAW_API_URL`                  | Production API URL (e.g. `https://api.loglife.co`) |
| `OPENCLAW_API_KEY`                  | Same key as `LOGLIFE_API_KEY` above                |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk publishable key                              |
| `CLERK_SECRET_KEY`                  | Clerk secret key (server-side only)                |

### Plugin deployment

When plugin changes are pushed to `main`, the deploy workflow (`.github/workflows/deploy.yml`):

1. SSHes into the production server
2. Pulls the latest code
3. Restarts the OpenClaw gateway (graceful — waits for in-flight replies to drain)
4. Runs a health check against the plugin endpoints

**Sessions are not lost on restart** — they are persisted to disk in `sessions.json`. In-memory verification codes are cleared, but that's expected (5-minute TTL, users simply re-request).

### Health checks

The deploy workflow verifies two things after each restart:

* `GET /loglife/sessions?phone=healthcheck` returns 404 (plugin loaded, searched, found nothing)
* `POST /loglife/verify/check` with dummy data returns 200 (verify endpoint loaded)

If either check fails, the deploy is marked as failed in GitHub Actions.

### Website deployment

The website deploys to Vercel automatically on push to `main`. No gateway restart needed — the website is a separate deployment that connects to the plugin via `OPENCLAW_API_URL`.

## User lifecycle and onboarding tests

Use these commands to verify the V1 onboarding flow and monitor user state while testing.

### Monitor registered users

One-time check:

```bash theme={null}
bash plugin/scripts/check-registered-users.sh
```

Live monitoring:

```bash theme={null}
bash plugin/scripts/check-registered-users.sh --watch --interval 2
```

### Remove a user quickly

Use the helper script:

```bash theme={null}
bash plugin/scripts/unregister-user.sh --phone 15551234567
```

You can also call the endpoint directly:

```bash theme={null}
curl -s -X POST "http://127.0.0.1:18789/loglife/unregister" \
  -H "Authorization: Bearer test-key-for-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15551234567"}'
```

To clear all registered users (clean slate):

```bash theme={null}
bash plugin/scripts/unregister-user.sh --all
```

### V1 onboarding test checklist

<Steps>
  <Step title="Start from a clean user state">
    Remove your test phone with `unregister-user.sh`.

    <Check>
      Confirm `/loglife/users` shows your phone is no longer registered.
    </Check>
  </Step>

  <Step title="Run dashboard onboarding">
    In the dashboard, enter your phone number and continue the V1 flow:

    1. register first, 2) send/check verification code.

    <Check>
      You should receive a verification code on WhatsApp and complete verification.
    </Check>
  </Step>

  <Step title="Verify backend state">
    Query `/loglife/users` and confirm your user appears.

    <Check>
      The `count` increases and your phone appears in `users`.
    </Check>
  </Step>

  <Step title="Verify idempotency">
    Repeat the same registration for the same phone.

    <Check>
      Registration should not create duplicates.
    </Check>
  </Step>

  <Step title="Verify removal path">
    Remove the same phone using `/loglife/unregister`.

    <Check>
      `/loglife/users` no longer includes that user.
    </Check>
  </Step>
</Steps>

## Docs preview

To preview documentation changes locally:

```bash theme={null}
npm i -g mint
cd docs
mint dev
```

A local preview will be available at `http://localhost:3000`.