YapHub

Appearance

Setup Guide - Yappa Knowledge Hub (TypeScript) ​

Complete setup instructions from zero to running TypeScript-powered POC in under 10 minutes.

Prerequisites ​

Before starting, ensure you have:

  • Node.js >= 18.0.0 (Download)
  • PHP >= 8.2 (Download)
  • Composer (Download)
  • Slack workspace with admin permissions
  • Terminal/Command line access

Part 1: Local Setup (5 minutes) ​

Step 1: Clone and Install Dependencies ​

bash
# Navigate to project directory
cd /home/ubuntu/yappa-knowledge-hub

# Install Node.js dependencies (includes TypeScript)
npm install

# Install PHP dependencies
cd backend
composer install
cd ..

Step 2: Configure Environment ​

bash
# Copy example environment file
cp .env.example .env

# The .env file will look like this (you'll fill in Slack tokens in Part 2):
bash
# Slack Configuration (fill these in after Part 2)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here
SLACK_APP_TOKEN=xapp-your-app-token-here

# Server Configuration
PORT=3000
API_PORT=3001

# Backend API Configuration
DATABASE_API_URL=http://127.0.0.1:8000

# OpenAI Configuration (mock mode for POC)
OPENAI_API_KEY=mock-key
OPENAI_MODEL=gpt-4
OPENAI_MOCK=true

Step 3: Build TypeScript ​

bash
# Compile TypeScript to JavaScript
npm run build

# This creates the dist/ directory with compiled .js files

Step 4: Initialize Database ​

bash
cd backend

# Create database and run migrations
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate --no-interaction

# Seed demo data (20 realistic Dutch knowledge items)
php bin/console app:seed-poc-data

cd ..

Part 2: Slack App Setup (5 minutes) ​

Step 1: Create Slack App ​

  1. Go to https://api.slack.com/apps
  2. Click "Create New App"
  3. Select "From an app manifest"
  4. Choose your workspace
  5. Select "YAML" tab
  6. Copy the entire contents of slack-app-manifest.yaml from this repository
  7. Paste into the YAML editor
  8. Click "Next"
  9. Review the configuration
  10. Click "Create"

Step 2: Enable Socket Mode ​

Socket Mode allows the bot to receive events without exposing a public URL (perfect for development).

  1. In your app settings, click "Socket Mode" in the left sidebar
  2. Toggle "Enable Socket Mode" to ON
  3. Click "Generate" to create an app-level token
  4. Name it "Socket Mode Token"
  5. Add the connections:write scope
  6. Click "Generate"
  7. Copy the token (starts with xapp-)
  8. Save it in your .env file as SLACK_APP_TOKEN

Step 3: Install App to Workspace ​

  1. In the left sidebar, click "Install App"
  2. Click "Install to Workspace"
  3. Review the permissions
  4. Click "Allow"
  5. Copy the "Bot User OAuth Token" (starts with xoxb-)
  6. Save it in your .env file as SLACK_BOT_TOKEN

Step 4: Get Signing Secret ​

  1. In the left sidebar, click "Basic Information"
  2. Scroll down to "App Credentials"
  3. Copy the "Signing Secret"
  4. Save it in your .env file as SLACK_SIGNING_SECRET

Step 5: Verify Environment Variables ​

Your .env file should now look like this:

bash
SLACK_BOT_TOKEN=xoxb-1234567890-1234567890123-abcdefghijklmnopqrstuvwx
SLACK_SIGNING_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SLACK_APP_TOKEN=xapp-1-A01234567-1234567890123-abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnop
PORT=3000
API_BASE_URL=http://localhost:8000
OPENAI_API_KEY=mock-key
OPENAI_MODEL=gpt-4
OPENAI_MOCK=true

Part 3: Start Services ​

Terminal 1: Start Symfony Backend ​

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

# Or if you don't have Symfony CLI:
php -S localhost:8000 -t public

You should see:

[OK] Web server listening on http://127.0.0.1:8000

Terminal 2: Start TypeScript Bot ​

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

# Build TypeScript (if not already built)
npm run build

# Start the bot
npm start

# Or use development mode with hot reload
npm run dev

You should see:

[View Tracker] Periodic cleanup started
[INFO] socket-mode:SocketModeClient:0 Going to establish a new connection to Slack ...
[Yappa Kennishub] Bot is actief op poort 3000
[Yappa Kennishub] Socket Mode: ingeschakeld
[Yappa Kennishub] Handlers:
  - /knowledge commando
  - Message shortcuts: save_to_knowledge, add_to_hub
  - Global shortcut: quick_add_knowledge
  - Events: message, app_home_opened, file_shared
  - View submissions & action handlers
[Yappa Kennishub] API server actief op poort 3001
  - POST /api/slack/refresh-homes - Refresh all home pages
  - POST /api/slack/refresh-home - Refresh specific user home
  - GET /health - Health check
[INFO] socket-mode:SocketModeClient:0 Now connected to Slack

Part 4: Verify Setup ​

Test 1: API is Running ​

bash
curl http://127.0.0.1:8000/api/categories

Expected: JSON response with categories

Test 2: Bot Health Check ​

bash
curl http://localhost:3001/health

Expected: {"status":"ok","service":"yappa-knowledge-hub"}

Test 3: Bot is Connected ​

In Slack:

/knowledge

Expected: Dashboard modal opens

Test 4: View Demo Data ​

In Slack:

/knowledge

Expected: Dashboard modal opens with knowledge items

Test 5: Generate Digest ​

In Slack:

Click "Digest" button in dashboard

Expected: Modal opens with target group and filter options

Troubleshooting ​

Bot Not Responding ​

Problem: /knowledge command does nothing

Solutions:

  1. Check bot is running: ps aux | grep "node src/app.js"
  2. Check logs: tail -f /tmp/slack-bot.log
  3. Verify SLACK_APP_TOKEN starts with xapp-
  4. Verify Socket Mode is enabled in Slack app settings
  5. Restart bot: ./start-bot.sh

API Errors ​

Problem: Bot says "API error" or "Failed to fetch"

Solutions:

  1. Check Symfony is running: curl http://localhost:8000/api/categories
  2. Check logs: tail -f backend/var/log/dev.log
  3. Verify API_BASE_URL=http://localhost:8000 in .env
  4. Restart Symfony: cd backend && symfony server:start

Database Errors ​

Problem: "Table not found" or "Database does not exist"

Solutions:

bash
cd backend
php bin/console doctrine:database:drop --force
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console app:seed-poc-data

Permission Errors ​

Problem: "Missing scope" or "Not authorized"

Solutions:

  1. Go to https://api.slack.com/apps
  2. Select your app
  3. Go to "OAuth & Permissions"
  4. Verify all required scopes are present (see slack-app-manifest.yaml)
  5. Click "Reinstall App"
  6. Update SLACK_BOT_TOKEN in .env if it changed

Socket Mode Connection Issues ​

Problem: Bot starts but doesn't respond to events

Solutions:

  1. Verify SLACK_APP_TOKEN is correct
  2. Check token has connections:write scope
  3. Ensure no firewall is blocking WebSocket connections
  4. Try regenerating the app-level token

Next Steps ​

Now that setup is complete:

  1. Read the POC Documentation: /poc-guide
  2. Try the Demo Workflow: Test all 7 input methods
  3. Generate a Digest: /knowledge digest
  4. Explore the API: http://localhost:8000/api
  5. Provide Feedback: Document what works and what doesn't

Quick Reference ​

Start Services:

bash
# Terminal 1
cd backend && symfony server:start

# Terminal 2
./start-bot.sh

Stop Services:

bash
# Stop bot: Ctrl+C in Terminal 2
# Stop Symfony: Ctrl+C in Terminal 1

Reset Database:

bash
cd backend
php bin/console doctrine:database:drop --force
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console app:seed-poc-data

View Logs:

bash
# Bot logs
tail -f /tmp/slack-bot.log

# Symfony logs
tail -f backend/var/log/dev.log

Test Commands:

bash
# In Slack
/knowledge help
/knowledge
/knowledge add
/knowledge search <query>
/knowledge digest

Additional Resources ​

Setup complete! You're ready to test the POC.