# Deployment Instructions - Brachnha Insights

This guide provides instructions for deploying **Brachnha Insights** to production environments.

## Prerequisites

- **Node.js**: v18 or higher
- **npm**: v9 or higher
- **Docker** & **Docker Compose** (for Dokploy deployment)

## Environment Variables

Ensure the following environment variables are configured in your production environment:

| Variable                     | Description                    | Default / Example         |
| :--------------------------- | :----------------------------- | :------------------------ |
| `NEXT_PUBLIC_AI_PROVIDER`    | Default AI Provider (optional) | `gemini`                  |
| `NEXT_PUBLIC_GEMINI_API_KEY` | Initial API Key (optional)     | `AIzaSy...`               |
| `NEXT_PUBLIC_API_URL`        | API Base URL (if custom)       | `https://api.example.com` |

> **Note:** The application uses a local-first architecture (IndexedDB), so no external database connection strings (Postgres/MySQL) are required for the core journaling features.

---

## Deployment Options

### Option 1: Dokploy with Docker Compose (Recommended for Self-Hosting)

Dokploy provides an easy way to deploy and manage your applications with Docker.

#### Files Included
- `Dockerfile` - Multi-stage build for optimal image size
- `docker-compose.yml` - Service configuration with Traefik labels
- `.dockerignore` - Excludes unnecessary files from build

#### Deployment Steps

**1. Deploy from Git Repository (Recommended)**

In your Dokploy Dashboard:
- Click "Create Project"
- Select "Compose" as project type
- Choose "From Git Repository"
- Enter your Git URL: `https://gitea.brachnha.com/Brachnha/brachnha-insight.git`
- Add your Git credentials (token)
- Set branch to `master`
- Click "Create"

**2. Configure Domain (Optional)**

Edit `docker-compose.yml` and replace `your-domain.com`:

```yaml
labels:
  - "traefik.http.routers.brachnha-insights.rule=Host(`insights.brachnha.com`)"
```

**3. Deploy**
- Click "Deploy" button in Dokploy
- Dokploy will build and start the container

**Manual Deployment (Alternative)**

```bash
# Clone repository
git clone https://gitea.brachnha.com/Brachnha/brachnha-insight.git
cd brachnha-insight

# Build and start
docker-compose up -d
```

**Updating:**

```bash
git pull origin master
docker-compose down
docker-compose build
docker-compose up -d
```

Or trigger a redeploy from the Dokploy dashboard.

---

### Option 2: Vercel (Recommended for Managed Hosting)

Vercel provides the best support for Next.js applications, including PWA headers and caching.

1. **Push to GitHub**: Ensure your code is pushed to a remote repository.
2. **Import Project**: Go to [Vercel Dashboard](https://vercel.com/new) and import your repository.
3. **Configure**:
   - **Framework Preset**: Next.js
   - **Build Command**: `next build`
   - **Output Directory**: `.next`
   - **Environment Variables**: Add any keys defined above.
4. **Deploy**: Click "Deploy".

Vercel will automatically detect the `manifest.webmanifest` and service worker configurations.

---

### Option 3: Traditional Node.js Server

To deploy as a standalone Node.js application:

1. **Build the application**:
   ```bash
   npm run build
   ```
2. **Start the server**:
   ```bash
   npm start
   ```
   The app will be available at `http://localhost:3000`.

Use a process manager like PM2 for production:
```bash
npm install -g pm2
pm2 start npm --name "brachnha-insights" -- start
pm2 startup
pm2 save
```

---

## Troubleshooting

### Docker/Dokploy Issues

**Container won't start:**
```bash
docker-compose logs brachnha-insights
```

**Build fails:**
- Ensure `next.config.ts` has `output: 'standalone'`
- Check that all dependencies are in `package.json`

**Port conflicts:**
- Change the port mapping in `docker-compose.yml`
- Update the Traefik labels accordingly

### Build Failures

- **Google Fonts / Network Errors**: The build process requires internet access to download fonts from Google. If building in a restricted environment (like a corporate firewall or offline CI), you may see TLS/Network errors.
  - *Workaround*: Set `NEXT_TURBOPACK_EXPERIMENTAL_USE_SYSTEM_TLS_CERTS=1` or temporarily disable `next/font/google` in `src/app/layout.tsx`.

- **Manifest Errors**: If you see `manifest.ts` type errors, ensure you are using a compatible Next.js version (14+ recommended) or check `purpose` fields in icon definitions.

### PWA Verification

After deployment, verify the PWA features:
1. Open the deployed URL on a mobile device or Chrome.
2. Look for the "Install Brachnha Insights" prompt (bottom banner) or the Install icon in the address bar.
3. Install the app and verify it opens in standalone mode.
4. Disconnect internet and verify you can still create/save drafts (Offline support).