> For the complete documentation index, see [llms.txt](https://docs.kangaroodev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangaroodev.net/product-docs/getting-started/hosting-and-deployment.md).

# Hosting and deployment

***

### Deploying on Vercel

#### How it works

* The repo includes a **Vercel** configuration: all requests are rewritten to `/api?path=<original path>`. The serverless function in `api/index.ts` reconstructs the request and passes it to the main Hono app (built from `src/index.ts`).
* The **build** runs `npm run build`, which compiles TypeScript, runs Prisma generate, and builds Tailwind. The output used in production is `dist/index.js` plus `api/index.ts` as the Vercel serverless entry.

#### Steps

1. **Connect the repo** to Vercel (GitHub/GitLab/Bitbucket).
2. **Set environment variables** in the Vercel project:
   * **DATABASE\_URL** – Your PostgreSQL URL. For Vercel Postgres, use the connection string from the Vercel dashboard (often with `?connection_limit=1` for serverless).
   * **APP\_BASE\_URL** – Your production URL, e.g. `https://your-app.vercel.app`.
   * Optional: **STRIPE\_SECRET\_KEY**, **BLOB\_READ\_WRITE\_TOKEN**, **SMTP\_**\*, Discord vars (see Environment Variables).
3. **Build command:** `npm run build`\
   **Output directory:** leave default (Vercel uses the repo root; the function is in `api/`).
4. **Deploy.** On first deploy, ensure migrations have been applied to your production database. You can run:

   ```bash
   npx prisma migrate deploy
   ```

   locally with `DATABASE_URL` pointing to the production DB, or run it in a one-off script/CI step.

#### Notes for Vercel

* **Read-only filesystem:** The app cannot write files to disk at runtime. Commission file uploads and user banners should use **Vercel Blob** (or an external store) if you need them in production. The code already supports `BLOB_READ_WRITE_TOKEN` for banner uploads; commission uploads currently write to `uploads/` and will only work on a host with a writable filesystem unless you add Blob (or S3) for those too.
* **Connection pooling:** For serverless, add `?connection_limit=1` to `DATABASE_URL` if recommended by your DB provider to avoid exhausting connections.

***

### Self-hosting (VPS, Railway, Render, etc.)

1. **Server requirements:** Node.js 18+, PostgreSQL.
2. **Clone, install, set env:**

   ```bash
   git clone <repo>
   cd <project>
   npm install
   cp .env.example .env
   # Edit .env with DATABASE_URL and other vars
   ```
3. **Database:**

   ```bash
   npx prisma migrate deploy
   ```
4. **Build and start:**

   ```bash
   npm run build
   npm start
   ```
5. **Process manager (recommended):** Use **PM2**, **systemd**, or the platform’s process manager so the app restarts on crash and on reboot. Example with PM2:

   ```bash
   npx pm2 start dist/index.js --name panel
   ```
6. **Reverse proxy:** Put **Nginx** (or Caddy) in front and proxy to the Node port. Use HTTPS (e.g. Let’s Encrypt). Set **APP\_BASE\_URL** to your public URL (e.g. `https://panel.yourdomain.com`).
7. **Uploads:** On a VPS, `uploads/` is writable; commission uploads and banners will be stored on disk. Ensure the app has write permissions to the `uploads` (and `uploads/banners`) directories. Serve user-uploaded files via the existing `/static/:file` (and any route that serves `/uploads/`) so paths match what the app expects.

***

### Summary

| Aspect       | Vercel                                               | Self-hosted (Node)           |
| ------------ | ---------------------------------------------------- | ---------------------------- |
| Database     | Use Vercel Postgres or external                      | Your own PostgreSQL          |
| File uploads | Use Blob for banners (and commissions if you add it) | Can use local `uploads/`     |
| Env vars     | In Vercel project settings                           | In `.env` or process manager |
| Migrations   | Run `prisma migrate deploy` against prod DB          | Same                         |
| Build        | `npm run build` on deploy                            | Run before `npm start`       |