Meeting_Assistant/DEPLOYMENT.md

# Meeting Assistant Deployment Guide

## Prerequisites

- Python 3.10+
- Node.js 18+
- MySQL 8.0+
- Access to Dify LLM service

## Quick Start

Use the startup script to run all services locally:

```bash
# Check environment
./start.sh check

# Start all services
./start.sh start

# Stop all services
./start.sh stop

# View status
./start.sh status
```

## Backend Deployment

### 1. Setup Environment

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure Environment Variables

```bash
# Copy example and edit
cp .env.example .env
```

**Required Environment Variables:**

| Variable | Description |
|----------|-------------|
| `BACKEND_HOST` | Server bind address (default: 0.0.0.0) |
| `BACKEND_PORT` | Server port (default: 8000) |
| `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, `DB_NAME` | MySQL connection |
| `AUTH_API_URL` | Company authentication API |
| `DIFY_API_URL`, `DIFY_API_KEY`, `DIFY_STT_API_KEY` | Dify API settings |
| `ADMIN_EMAIL` | Admin user email |
| `JWT_SECRET` | JWT signing secret (generate secure random string) |

**Optional Environment Variables:**

| Variable | Description | Default |
|----------|-------------|---------|
| `DB_POOL_SIZE` | Database connection pool size | 5 |
| `JWT_EXPIRE_HOURS` | JWT token expiration | 24 |
| `UPLOAD_TIMEOUT` | File upload timeout (ms) | 600000 |
| `DIFY_STT_TIMEOUT` | STT processing timeout (ms) | 300000 |
| `LLM_TIMEOUT` | LLM request timeout (ms) | 120000 |
| `MAX_FILE_SIZE` | Max upload size (bytes) | 524288000 |

See `backend/.env.example` for complete documentation.

### 3. Run Server

```bash
# Development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 4. Verify Deployment

```bash
curl http://localhost:8000/api/health
# Should return: {"status":"healthy","service":"meeting-assistant"}
```

### 5. Production Deployment (1Panel)

For detailed server deployment instructions including Nginx, systemd, and SSL configuration, see:

📖 **[docs/1panel-deployment.md](docs/1panel-deployment.md)**

Or use the deployment script:

```bash
sudo ./scripts/deploy-backend.sh install --port 8000
```

## Electron Client Deployment

### 1. Setup

```bash
cd client

# Install dependencies
npm install
```

### 2. Configure Environment

```bash
# Copy example and edit
cp .env.example .env
```

**Environment Variables:**

| Variable | Description | Default |
|----------|-------------|---------|
| `VITE_API_BASE_URL` | Backend API URL | http://localhost:8000/api |
| `VITE_UPLOAD_TIMEOUT` | Upload timeout (ms) | 600000 |
| `WHISPER_MODEL` | Whisper model size | medium |
| `WHISPER_DEVICE` | Execution device | cpu |
| `WHISPER_COMPUTE` | Compute precision | int8 |

### 3. Development

```bash
npm start
```

### 4. Build for Distribution

```bash
# Update VITE_API_BASE_URL to production server first
# Then build portable executable
npm run build
```

The executable will be in `client/dist/`.

## Transcription Sidecar

### 1. Setup

```bash
cd sidecar

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pyinstaller
```

### 2. Download Whisper Model

The model will be downloaded automatically on first run. For faster startup, pre-download:

```python
from faster_whisper import WhisperModel
model = WhisperModel("medium", device="cpu", compute_type="int8")
```

### 3. Build Executable

```bash
python build.py
```

The executable will be in `sidecar/dist/transcriber`.

### 4. Package with Electron

Copy `sidecar/dist/` to `client/sidecar/` before building Electron app.

## Database Setup

The backend will automatically create tables on first startup. To manually verify:

```sql
USE your_database;
SHOW TABLES LIKE 'meeting_%';
```

Expected tables:
- `meeting_users`
- `meeting_records`
- `meeting_conclusions`
- `meeting_action_items`

## Testing

### Backend Tests

```bash
cd backend
pytest tests/ -v
```

### Performance Verification

On target hardware (i5/8GB):
1. Start the Electron app
2. Record 1 minute of audio
3. Verify transcription completes within acceptable time
4. Test AI summarization with the transcript

## Troubleshooting

### Database Connection Issues

1. Verify MySQL is accessible from server
2. Check firewall rules for database port
3. Verify credentials in .env

### Dify API Issues

1. Verify API key is valid
2. Check Dify service status
3. Review timeout settings for long transcripts (adjust `DIFY_STT_TIMEOUT`, `LLM_TIMEOUT`)

### Transcription Issues

1. Verify microphone permissions
2. Check sidecar executable runs standalone
3. Review audio format (16kHz, 16-bit, mono)
4. Try different `WHISPER_MODEL` sizes (tiny, base, small, medium)

## Security Notes

- Never commit `.env` files to version control
- Keep JWT_SECRET secure and unique per deployment
- Ensure HTTPS in production (see [1panel-deployment.md](docs/1panel-deployment.md))
- Regular security updates for dependencies