skills/catalyst-by-zoho/references/deployment-sops.md

# Catalyst Deployment SOPs

> **⚠️ PRE-FLIGHT CHECK:** Before any deployment steps, confirm `.catalystrc` and `catalyst.json` exist. If not, tell the user to run `catalyst init` first.

## When to use this file
Load this file when the user is deploying a Catalyst project, asking about deployment steps,
running into deployment failures, promoting from Development to Production, setting up
GitHub-based deployment, or needs a pre-deployment checklist.

---

## Pre-deployment checklist

Before running `catalyst deploy`, verify all of the following:

- [ ] **`.catalystrc` exists** — project is linked to your Zoho account. If missing, run
      `catalyst login` then `catalyst init`.
- [ ] **`catalyst.json` at project root** — auto-generated by `catalyst init`. Never create
      manually. If missing, re-initialize.
- [ ] **`functions/` directory structure** — each function has its own subdirectory with the
      handler file (`index.js`, `index.py`, or the Java main class).
- [ ] **All function env vars are in `catalyst-config.json`, NOT the Console UI** —
      `catalyst deploy` **overwrites the function's environment with values from
      `catalyst-config.json` only**. Any variable set through the Console UI is silently
      deleted on the next deploy. Store all secrets, API keys, and config in
      `catalyst-config.json` (gitignore this file) before deploying. After every deploy,
      spot-check Functions → [function] → Settings → Environment Variables to confirm.
- [ ] **AppSail apps have `catalyst-config.json`** with correct `name`, `stack`, `command`,
      `memory`, and `port` fields. The `port` must match what the app actually listens on.
- [ ] **Web client in `client/` directory** (only if using Web Client Hosting, not Slate).
- [ ] **Dependencies installed**:
      - Node.js: `npm install` inside each function directory
      - Python: `pip install -r requirements.txt` inside each function directory
      - Java: `mvn install` or `gradle build`
- [ ] **Java functions**: `.class` files are auto-generated by the CLI during `catalyst deploy` —
      no manual compilation needed when using CLI.
- [ ] **Slate apps**: `catalyst.json` must be present in the repository root if using GitHub deploy.

---

## Deployment commands

### Deploy everything (all components)
```bash
catalyst deploy
```
Deploys all functions, web client, AppSail apps, and Slate apps in the project to the
Development environment.

### Deploy specific components
```bash
# Functions only
catalyst deploy --only functions

# AppSail app only
catalyst deploy appsail

# AppSail standalone (without full project deploy)
catalyst deploy appsail standalone

# Slate frontend only
catalyst deploy slate

# Slate with a deployment message
catalyst deploy slate -m "deployment message"

# Specific Slate app by name
catalyst deploy --only slate:appname

# Slate to production
catalyst deploy slate --production
```

> **Note:** `catalyst deploy` always targets the **Development** environment. Production
> deployment is handled via the Catalyst console (not the CLI).

---

## Post-deployment verification

After every deployment, verify:

1. **Check deployment status** in the Catalyst console.
2. **Test function endpoints** — invoke the function URL directly or from your app.
3. **Check DevOps → Logs** for any runtime errors on first execution.
4. **For AppSail**: verify the endpoint URL returned by the CLI is reachable and responds
   within the expected latency.
5. **For Slate**: check the Deployment Overview screen to confirm the build succeeded.
6. **For Circuits**: run a test execution and review the Execution History logs.
7. **Configure Application Alerts** for cron jobs and event listeners in production so you
   are notified on failures automatically.

---

## GitHub-based deployment

Requirements for GitHub deployment to work:
- Repository must contain Catalyst project resources in **standard project directory format**.
- `catalyst.json` MUST be present in the repository.
- Default branch must have all files in the correct structure.

What happens on successful GitHub deployment:
- Functions are updated in the Catalyst console.
- Web Client Hosting is updated.
- A notification is sent (success or failure).
- The Deployed Repository status bar shows the repository name and URL.

What happens on failure:
- **No changes are reflected** in Functions or Web Client Hosting.
- Fix the directory structure, ensure `catalyst.json` is present, then redeploy.

---

## Common deployment failure recovery

### Slate deployment failed
1. Use **"Sync Now"** in the Catalyst console to merge the latest Git commit into the current
   deployment. This resolves discrepancies causing the failure.
2. If Sync Now doesn't resolve it, use **Rollback** to revert to the last successful deployment
   from the console.
3. After fixing the root cause, trigger a new deployment.

### Function deployment failed — Java missing `.class` file
- Error: function fails to execute after deploy with missing class reference.
- Fix: re-deploy via CLI (`catalyst deploy`). The CLI auto-compiles Java and creates any missing
  dependency files. This error only occurs when uploading via console without the compiled files.

### AppSail not responding after deployment
1. Verify `catalyst-config.json` `port` matches the port the app listens on.
2. Verify the app starts listening within 10 seconds of instance start.
   - Cold start: first request to an inactive app spawns a new instance; if no process is
     listening on the port within 10 seconds, the instance is killed.
3. Check AppSail instance logs: AppSail → Instances → click the Logs icon → Catalyst Logs.
4. Verify the app uses `process.env.X_ZOHO_CATALYST_LISTEN_PORT || 9000` (Node.js) for the port.

### Function behaves correctly locally but fails or uses wrong config after deploy
- **Root cause**: environment variables set through the Catalyst Console UI are deleted on
  every `catalyst deploy`. The deploy replaces the function environment with values from
  `catalyst-config.json` only.
- Fix: move all env vars into `catalyst-config.json` and redeploy. Do not rely on Console-set
  vars for any value that must survive deployments.

### Functions deployed but not behaving as expected
- Check `catalyst.json` for correct function names and configurations.
- Verify the correct function type is used (Basic I/O vs Advanced I/O vs Event, etc.).
- Run `catalyst serve` locally to test Basic I/O and Advanced I/O functions against the
  remote Development Data Store before deploying.
- Check DevOps → Logs for execution errors.

---

## Environment promotion: Development → Production

> Production deployment is not done via CLI. It is managed through the Catalyst console.

1. **Test thoroughly in Development** — ensure all functions, AppSail, and data operations
   work correctly in the Development environment.
2. **Migrate to Production** via the Catalyst console (Deployment and Billing → Environments →
   Initial Deployment, or via the production environment settings).
3. **After promotion**, DevOps components (Logs, APM, Application Alerts) continue to work
   in the production environment.
4. **Update environment-specific config**:
   - ZAID differs between Development and Production — update your app's config accordingly.
   - DataStore table permissions and security rules apply independently per environment.
5. **Configure Application Alerts** for production — set up email alerts for function failures,
   timeouts, and exceptions from DevOps → Application Alerts.
6. **User limit**: Development supports max 25 users; Production has no user limit.

### Function promotion to Production (separate step)

`catalyst deploy --only functions` deploys to the **Development** environment only.
Promoting functions to Production requires a **separate manual step** in the console:

> Console → Cloud Scale → Serverless → Deploy → Select Functions → Initiate Deployment

If this step is skipped, the Development function has your latest code but Production still
runs old code. The Diff Generation screen will show `Total Changes: 0` for Functions if
there are no new changes to promote — use this as a diagnostic.

### Slate production deployment

Slate can be deployed directly to production from the CLI:
```bash
catalyst deploy slate --production
```

### Recommended: deploy components separately

Deploy functions and Slate separately rather than using `catalyst deploy` (which deploys everything):
```bash
# Deploy function changes
catalyst deploy --only functions

# Deploy frontend changes
catalyst deploy slate
```

This gives clearer error messages, avoids deploying unchanged components, and makes it
easier to diagnose which component caused a failure.

---

## Slate-specific deployment gotchas

### `slate-config.toml` wiped by clean builds

The `.catalyst/slate-config.toml` file lives inside the build output directory (e.g., `dist/`).
Any build command that cleans the output (Vite `--clean`, Expo `--clear`, `rm -rf dist/`) deletes
this file. Without it, `catalyst deploy slate` fails.

**Fix — recreate after every clean build:**
```bash
# Vite/React example
npm run build && mkdir -p dist/.catalyst && \
  echo -e 'framework = "static"\ndeployment_name = "default"' > dist/.catalyst/slate-config.toml

# Expo web example
npx expo export --platform web --clear && \
  mkdir -p dist/.catalyst && \
  echo -e 'framework = "static"\ndeployment_name = "default"' > dist/.catalyst/slate-config.toml

# Then deploy
catalyst deploy slate
```

### `baseUrl` breaks assets on Slate

If your build config has a `baseUrl` or `basePath` set to a sub-path (e.g., `/server/my_function`
for serving from inside a function), all JS/CSS URLs will be prefixed with that path on Slate.
Since Slate serves from root `/`, every asset returns 404.

**Fix:** Remove `baseUrl`/`basePath` from your build config before building for Slate. Only set
it when the frontend is served from inside a function or AppSail sub-path.

---

## `catalyst-config.json` reference (AppSail)

```json
{
  "name": "my-app",
  "stack": "node20",
  "command": "node app.js",
  "memory": 512,
  "port": 9000
}
```

| Field | Required | Notes |
|-------|----------|-------|
| `name` | Yes | App name — must match what's initialized |
| `stack` | Yes | Runtime: `node20`, `java11`, `python39`, or `docker` |
| `command` | Yes | Command to start the app |
| `memory` | No | Default 512 MB; range 256–2048 MB |
| `port` | Yes | Must match the port the app listens on |

---

## CLI deployment flags reference

| Command | What it does |
|---------|-------------|
| `catalyst deploy` | Deploy all resources to Development |
| `catalyst deploy --only functions` | Deploy functions only |
| `catalyst deploy appsail` | Deploy AppSail app (as part of full project) |
| `catalyst deploy appsail standalone` | Deploy AppSail without full project deploy |
| `catalyst deploy slate` | Deploy Slate frontend |
| `catalyst deploy slate -m "msg"` | Deploy Slate with a message |
| `catalyst deploy slate --production` | Deploy Slate to production |
| `catalyst deploy --only slate:appname` | Deploy a specific Slate app |
| `catalyst serve` | Run Basic I/O + Advanced I/O locally against remote Dev DataStore |