# TaskFlow — Production Installation & Slack Integration Guide

## Part 1: Server Requirements

Before you begin, ensure your server meets these requirements:

| Requirement | Version |
|---|---|
| PHP | 8.4+ with extensions: `pdo_mysql`, `redis`, `bcmath`, `ctype`, `mbstring`, `openssl`, `tokenizer`, `xml`, `curl`, `gd` |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| Composer | 2.x |
| Web Server | Nginx or Apache |
| Supervisor | Latest |

---

## Part 2: Application Installation

### 1. Clone & Set Up Files

```bash
git clone <your-repo-url> /var/www/taskflow
cd /var/www/taskflow
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

### 2. Install PHP Dependencies

```bash
composer install --no-dev --optimize-autoloader
```

### 3. Configure Environment

```bash
cp .env.example .env
php artisan key:generate
```

Then edit `.env` with your production values:

```ini
APP_NAME=TaskFlow
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=taskflow
DB_USERNAME=taskflow_user
DB_PASSWORD=your_strong_password

# Redis (session, cache, queues all use Redis)
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=your_redis_password
REDIS_PORT=6379

SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=warning

# Mail (choose one provider)
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your@domain.com
MAIL_PASSWORD=your_smtp_password
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME=TaskFlow

# Failed job notifications (optional)
FAILED_JOBS_NOTIFY_EMAIL=ops@yourdomain.com
```

### 4. Database Setup

```bash
# Create MySQL database and user first
mysql -u root -p <<'SQL'
CREATE DATABASE taskflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'taskflow_user'@'localhost' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON taskflow.* TO 'taskflow_user'@'localhost';
FLUSH PRIVILEGES;
SQL

# Run migrations
php artisan migrate --force
```

### 5. Storage & Caches

```bash
php artisan storage:link --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### 6. Nginx Configuration

```nginx
server {
    listen 443 ssl;
    server_name yourdomain.com;
    root /var/www/taskflow/public;
    index index.php;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Webhook endpoints must not be rate-limited at Nginx level
    location ~ ^/webhooks/ {
        try_files $uri /index.php?$query_string;
    }

    client_max_body_size 50M;
}

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}
```

### 7. Queue Workers (Supervisor)

Copy the included example config and adjust paths:

```bash
cp /var/www/taskflow/supervisord.conf.example /etc/supervisor/conf.d/taskflow.conf
```

Edit the file to replace `/var/www/taskflow` with your actual path, then:

```bash
supervisorctl reread
supervisorctl update
supervisorctl start taskflow-worker-default:*
supervisorctl start taskflow-worker-notifications:*
supervisorctl start taskflow-worker-slack:*
supervisorctl start taskflow-worker-email:*
```

The app uses **4 named queues**: `default`, `notifications`, `slack`, `email`. All four workers must be running.

### 8. Scheduler (Cron)

```bash
crontab -e
# Add:
* * * * * cd /var/www/taskflow && php artisan schedule:run >> /dev/null 2>&1
```

### 9. Subsequent Deploys

Use the included script — it handles pull, dependencies, migrations, caches, and worker restart:

```bash
./deploy.sh
```

---

## Part 3: Slack Integration

The app supports Slack OAuth login, slash commands, interactive modals, and bot notifications. This requires creating a Slack App in your workspace.

### Step 1: Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**
2. Name it `TaskFlow` and select your workspace

### Step 2: Configure OAuth & Permissions

Under **OAuth & Permissions**, add these **Bot Token Scopes**:

| Scope | Purpose |
|---|---|
| `chat:write` | Send messages |
| `chat:write.public` | Post to channels without joining |
| `commands` | Register slash commands |
| `users:read` | Sync workspace users |
| `users:read.email` | Match users by email |
| `channels:read` | List public channels |
| `groups:read` | List private channels |
| `im:write` | Open DM channels |
| `im:read` | Read DMs |

Under **Redirect URLs**, add:

```
https://yourdomain.com/auth/slack/callback
```

### Step 3: Configure Slash Commands

Under **Slash Commands** → **Create New Command**:

| Field | Value |
|---|---|
| Command | `/task` (or your preferred command) |
| Request URL | `https://yourdomain.com/webhooks/slack/commands` |
| Short Description | Create and manage tasks |
| Usage Hint | `create \| list \| help` |

### Step 4: Enable Interactivity

Under **Interactivity & Shortcuts** → enable it and set:

- **Request URL**: `https://yourdomain.com/webhooks/slack/interactive`

### Step 5: Configure Event Subscriptions

Under **Event Subscriptions** → enable and set:

- **Request URL**: `https://yourdomain.com/webhooks/slack/events`

Subscribe to these **Bot Events**:

- `app_mention`
- `message.im` (if you want DM handling)

> Slack will send a challenge request to verify the endpoint. Your app must be live and `SLACK_SIGNING_SECRET` must be set before this verification will pass.

### Step 6: Install App & Get Credentials

1. Under **Basic Information** → copy **Signing Secret** → set as `SLACK_SIGNING_SECRET`
2. Under **OAuth & Permissions** → click **Install to Workspace** → authorize
3. Copy the **Bot User OAuth Token** (`xoxb-...`) → set as `SLACK_BOT_TOKEN`
4. Under **Basic Information** → copy **Client ID** and **Client Secret**

### Step 7: Add Slack Variables to `.env`

```ini
SLACK_CLIENT_ID=your_client_id
SLACK_CLIENT_SECRET=your_client_secret
SLACK_SIGNING_SECRET=your_signing_secret
SLACK_REDIRECT_URI=https://yourdomain.com/auth/slack/callback
SLACK_BOT_TOKEN=xoxb-your-bot-token

# For notifications channel (optional)
SLACK_BOT_USER_OAUTH_TOKEN=xoxb-your-bot-token
SLACK_BOT_USER_DEFAULT_CHANNEL=#general
```

Then re-cache config:

```bash
php artisan config:cache
```

### Step 8: Sync Existing Slack Users

If your workspace already has users, run the sync command to link their Slack accounts:

```bash
php artisan slack:sync-users
```

> Note: New Slack users from an already-connected team cannot sign up via OAuth alone — they must be synced via this command or invited directly.

---

## Part 4: Inbound Email (Optional)

The app supports task creation via email through Mailgun or SendGrid.

### Mailgun

```ini
INBOUND_EMAIL_PROVIDER=mailgun
MAILGUN_WEBHOOK_SIGNING_KEY=your_mailgun_webhook_signing_key
```

Configure a Mailgun inbound route to `POST` to:

```
https://yourdomain.com/webhooks/inbound-email
```

### SendGrid

```ini
INBOUND_EMAIL_PROVIDER=sendgrid
SENDGRID_WEBHOOK_PUBLIC_KEY=your_ec_public_key
```

The public key is found in **SendGrid → Settings → Mail Settings → Event Webhook**. Configure the webhook URL to:

```
https://yourdomain.com/webhooks/inbound-email
```

---

## Part 5: Health Check & Verification

```bash
# Verify the app is up
curl https://yourdomain.com/api/health

# Check queue workers are running
supervisorctl status

# Tail application logs
tail -f /var/www/taskflow/storage/logs/laravel.log

# Tail queue worker logs
tail -f /var/www/taskflow/storage/logs/worker-slack.log
```

---

## Part 6: Known Limitations

These items require manual attention post-deploy:

1. **Push notifications** — `PushNotificationSender` logs payloads but does not actually send. Firebase FCM or APNs must be implemented separately.
2. **Slack new-user UX** — New Slack users from a connected workspace must be added via `slack:sync-users`; they cannot self-register via OAuth.
3. **Supervisor queues** — All four workers (`default`, `notifications`, `slack`, `email`) must be running or jobs will queue up silently.