YapHub

Appearance

Deployment Guide: Notion to Slack Sync ​

Overview ​

This guide covers deploying the Notion to Slack sync system. The system automatically syncs changes from Notion databases to the local SQLite database and triggers Slack home page refreshes.

Architecture ​

Notion Database Changes

Backend Sync Endpoint (/api/notion/sync/from-notion)

SQLite Database Updated

SlackHomeRefreshService Called

Node.js Slack Bot API (/api/slack/refresh-homes)

Slack Home Pages Refreshed for All Users

Prerequisites Check ​

Run the test script to verify everything is configured:

bash
cd /home/ubuntu/yappa-knowledge-hub
./scripts/test-sync.sh

Quick Setup (2 minutes) ​

1. Update Environment Variables ​

Backend (.env in https://github.com/undead2146/KnowledgeHub/blob/main/backend/):

bash
SLACK_BOT_URL=http://localhost:3001
NOTION_WEBHOOK_SECRET=  # Optional, for webhook verification

Frontend (.env in /home/ubuntu/yappa-knowledge-hub/):

bash
API_PORT=3001
SLACK_BOT_URL=http://localhost:3001

2. Start Services ​

Start Slack Bot:

bash
cd /home/ubuntu/yappa-knowledge-hub
npm start

The bot will start on:

  • Port 3000: Slack Socket Mode
  • Port 3001: Internal API for home refresh

Start Backend (in a new terminal):

bash
cd /home/ubuntu/yappa-knowledge-hub/backend
symfony server:start

Or if you don't have Symfony CLI:

bash
cd /home/ubuntu/yappa-knowledge-hub/backend
php -S localhost:8000 -t public/

3. Set Up Auto-Sync ​

Option A: Cron Job (Recommended for Production)

bash
crontab -e

Add this line to sync every 2 minutes:

*/2 * * * * /home/ubuntu/yappa-knowledge-hub/auto-sync.sh

Save and verify:

bash
crontab -l

Option B: Manual Testing

bash
cd /home/ubuntu/yappa-knowledge-hub
./auto-sync.sh

Option C: Watch Mode (Development)

bash
# Run sync every 30 seconds (for testing)
watch -n 30 ./auto-sync.sh

Testing ​

1. Test Backend Sync ​

bash
curl -X POST http://localhost:8000/api/notion/sync/from-notion \
  -H "Content-Type: application/json" \
  -d '{"force": true, "limit": 100}'

Expected response:

json
{
  "message": "Sync completed",
  "created": 0,
  "updated": X,
  "skipped": Y,
  "failed": 0
}

2. Test Slack Home Refresh ​

bash
curl -X POST http://localhost:3001/api/slack/refresh-homes

Expected response:

json
{
  "success": true,
  "refreshed": 0,
  "failed": 0
}

Note: refreshed: 0 is expected until user tracking is implemented.

3. End-to-End Test ​

  1. Open Slack and go to the Yappa Knowledge Hub app home tab
  2. Make a change in Notion (edit a knowledge item)
  3. Wait 2 minutes (or run ./auto-sync.sh manually)
  4. Refresh the Slack app home tab
  5. Your changes should appear

4. Test Health Endpoints ​

bash
# Check Slack bot
curl http://localhost:3001/health

# Check backend
curl http://localhost:8000/api/notion/verify

Production Deployment with PM2 ​

Install PM2 ​

bash
npm install -g pm2

Start Bot with PM2 ​

bash
cd /home/ubuntu/yappa-knowledge-hub
pm2 start src/app.js --name yappa-bot
pm2 save
pm2 startup

Manage PM2 Process ​

bash
# View logs
pm2 logs yappa-bot

# Restart
pm2 restart yappa-bot

# Stop
pm2 stop yappa-bot

# Status
pm2 status

API Endpoints ​

Backend (Port 8000) ​

  • POST /api/notion/sync/from-notion - Sync from Notion to local DB
  • POST /api/notion/sync/categories-from-notion - Sync categories
  • POST /api/notion/sync/bidirectional - Full bidirectional sync
  • GET /api/notion/sync/status - Get sync status
  • GET /api/notion/verify - Verify Notion connection
  • POST /api/webhooks/notion - Webhook endpoint for Notion (optional)
  • POST /api/webhooks/notion/trigger-sync - Manual trigger endpoint

Frontend (Port 3001) ​

  • POST /api/slack/refresh-homes - Refresh all user home pages
  • POST /api/slack/refresh-home - Refresh specific user home page
  • GET /health - Health check

Monitoring ​

Check Sync Logs ​

bash
tail -f /tmp/notion-sync.log

Check Backend Logs ​

bash
tail -f https://github.com/undead2146/KnowledgeHub/blob/main/backend/var/log/dev.log

Check Bot Logs ​

If running with npm start, logs appear in the console.

If using PM2:

bash
pm2 logs yappa-bot

Troubleshooting ​

Services Not Running ​

bash
# Check if bot is running
curl http://localhost:3001/health

# Check if backend is running
curl http://localhost:8000/api/notion/verify

# Check processes
ps aux | grep node
ps aux | grep php

Sync Not Working ​

bash
# Test sync manually
./auto-sync.sh

# Check logs
tail -f /tmp/notion-sync.log

# Test backend directly
curl -X POST http://localhost:8000/api/notion/sync/from-notion \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Home Not Refreshing ​

bash
# Test refresh
curl -X POST http://localhost:3001/api/slack/refresh-homes

# Check bot logs
tail -f logs/slack-bot.log

Cron Job Not Running ​

bash
# Check if cron job is configured
crontab -l

# Check cron logs
grep CRON /var/log/syslog | tail -20

# Test script manually
/home/ubuntu/yappa-knowledge-hub/auto-sync.sh

# Check script permissions
ls -la /home/ubuntu/yappa-knowledge-hub/auto-sync.sh

Known Limitations ​

User Tracking ​

The current implementation has a limitation in the home refresh service. The getActiveUsers() function in https://github.com/undead2146/KnowledgeHub/blob/main/src/services/homeRefresh.js returns an empty array by default.

Impact: When refreshAllHomePages() is called, it won't refresh any homes because there are no tracked users.

Solutions:

  1. Implement user tracking: Track users when they open the app home and store in Redis/database
  2. Use Slack API: Call users.list() to get all workspace members (can be expensive)
  3. Manual refresh: Users can manually refresh by opening the app home tab

Recommended approach: Implement user tracking by modifying https://github.com/undead2146/KnowledgeHub/blob/main/src/handlers/home.js to call trackUserHomeOpen(userId) when users open the home page.

Sync Frequency ​

Adjust crontab to change frequency:

bash
*/1 * * * *   # Every 1 minute (fast, more API calls)
*/2 * * * *   # Every 2 minutes (recommended)
*/5 * * * *   # Every 5 minutes (slower, fewer API calls)
*/10 * * * *  # Every 10 minutes (slow)

Optional: Notion Webhooks ​

For instant updates instead of polling:

  1. Create a webhook in Notion pointing to: https://your-domain.com/api/webhooks/notion
  2. Set NOTION_WEBHOOK_SECRET in backend/.env
  3. Configure your reverse proxy to forward webhook requests to port 8000

Security Notes ​

  1. Webhook Secret: Set NOTION_WEBHOOK_SECRET to verify webhook authenticity
  2. Internal API: The Slack API endpoints (port 3001) should not be exposed publicly
  3. Firewall: Ensure ports 3000, 3001, and 8000 are only accessible internally

Performance Considerations ​

Database Size ​

  • SQLite is suitable for small to medium workloads
  • For large datasets (>10,000 items), consider PostgreSQL or MySQL

Log Rotation ​

Set up log rotation for /tmp/notion-sync.log to prevent disk space issues.

Next Steps ​

  1. Implement user tracking in homeRefresh.js for proper home page refreshes
  2. Set up monitoring for sync failures and API errors
  3. Configure Notion webhooks for instant updates (optional)
  4. Set up log rotation for /tmp/notion-sync.log
  5. Add metrics to track sync performance and success rates