Deployment Guide

This guide covers deploying the Yappa Knowledge Hub backend application.

Prerequisites

PHP 8.2 or higher
Composer
MySQL 8.0 or higher
Node.js 18+ (for frontend)
Git

Environment Setup

1. Clone the Repository

bash

git clone <repository-url>
cd yappa-knowledge-hub

2. Install Dependencies

bash

# Backend dependencies
cd backend
composer install --no-dev --optimize-autoloader

# Frontend dependencies
cd ../
npm install

3. Configure Environment

Copy the example environment file and configure it:

bash

cp backend/.env.example backend/.env

Edit backend/.env with your configuration:

env

APP_ENV=prod
APP_SECRET=<generate-a-secure-secret>

DATABASE_URL="mysql://user:password@localhost:3306/yappa_db?serverVersion=8.0"

NOTION_API_KEY=<your-notion-api-key>
NOTION_DATABASE_ID=<your-notion-database-id>

OPENAI_API_KEY=<your-openai-api-key>

4. Database Setup

bash

cd backend

# Create database
php bin/console doctrine:database:create

# Run migrations
php bin/console doctrine:migrations:migrate --no-interaction

# (Optional) Load demo data
php bin/console doctrine:fixtures:load --no-interaction

5. Build Assets

bash

cd ../
npm run build

Deployment Methods

Method 1: Traditional Server Deployment

Apache Configuration

apache

<VirtualHost *:80>
    ServerName yappa.example.com
    DocumentRoot /var/www/yappa/backend/public

    <Directory /var/www/yappa/backend/public>
        AllowOverride All
        Require all granted
        FallbackResource /index.php
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/yappa_error.log
    CustomLog ${APACHE_LOG_DIR}/yappa_access.log combined
</VirtualHost>

Nginx Configuration

nginx

server {
    listen 80;
    server_name yappa.example.com;
    root /var/www/yappa/backend/public;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        internal;
    }

    location ~ \.php$ {
        return 404;
    }

    error_log /var/log/nginx/yappa_error.log;
    access_log /var/log/nginx/yappa_access.log;
}

Method 2: Docker Deployment

Docker Compose

yaml

version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=prod
      - DATABASE_URL=mysql://user:password@db:3306/yappa_db
    depends_on:
      - db
    volumes:
      - ./backend:/app

  db:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=yappa_db
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
    volumes:
      - db_data:/var/lib/mysql

  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

volumes:
  db_data:

Backend Dockerfile

dockerfile

FROM php:8.2-fpm

# Install dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    && docker-php-ext-install pdo_mysql zip

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /app

# Copy application files
COPY . .

# Install PHP dependencies
RUN composer install --no-dev --optimize-autoloader

# Set permissions
RUN chown -R www-data:www-data /app/var

EXPOSE 8000

CMD ["php", "-S", "0.0.0.0:8000", "-t", "public"]

Method 3: Kubernetes Deployment

Deployment YAML

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: yappa-backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: yappa-backend
  template:
    metadata:
      labels:
        app: yappa-backend
    spec:
      containers:
      - name: backend
        image: yappa/backend:latest
        ports:
        - containerPort: 8000
        env:
        - name: APP_ENV
          value: "prod"
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: yappa-secrets
              key: database-url
        livenessProbe:
          httpGet:
            path: /api/health/live
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /api/health/ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: yappa-backend
spec:
  selector:
    app: yappa-backend
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Post-Deployment Tasks

1. Verify Health Checks

bash

curl http://your-domain/api/health

Expected response:

json

{
  "status": "healthy",
  "services": [...]
}

2. Clear Cache

bash

php bin/console cache:clear --env=prod

3. Warm Up Cache

bash

php bin/console cache:warmup --env=prod

4. Set Up Cron Jobs

Add to crontab for scheduled tasks:

cron

# Sync with Notion every hour
0 * * * * cd /var/www/yappa/backend && php bin/console app:sync-notion

# Clear old logs daily
0 0 * * * cd /var/www/yappa/backend && php bin/console app:clear-logs

Monitoring and Maintenance

Health Checks

Monitor application health:

bash

# Overall health
curl http://your-domain/api/health

# Liveness
curl http://your-domain/api/health/live

# Readiness
curl http://your-domain/api/health/ready

# Metrics
curl http://your-domain/api/health/metrics

Logs

View application logs:

bash

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

# Web server logs
tail -f /var/log/nginx/yappa_error.log

Database Backups

Set up automated backups:

bash

#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups"
DB_NAME="yappa_db"

mysqldump -u user -p password $DB_NAME > $BACKUP_DIR/backup_$DATE.sql
gzip $BACKUP_DIR/backup_$DATE.sql

# Keep only last 7 days
find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete

Troubleshooting

Common Issues

Database Connection Errors

bash

# Check database connectivity
php bin/console doctrine:query:sql "SELECT 1"

# Verify DATABASE_URL in .env
grep DATABASE_URL backend/.env

Permission Issues

bash

# Fix permissions
chown -R www-data:www-data backend/var
chmod -R 775 backend/var

Cache Issues

bash

# Clear all caches
php bin/console cache:clear --env=prod
rm -rf backend/var/cache/*

Security Checklist

[ ] Use HTTPS in production
[ ] Set strong APP_SECRET
[ ] Restrict database access
[ ] Keep dependencies updated
[ ] Enable firewall rules
[ ] Set up rate limiting
[ ] Configure CORS properly
[ ] Use environment variables for secrets
[ ] Enable security headers
[ ] Regular security audits

Performance Optimization

PHP-FPM Configuration

ini

; /etc/php/8.2/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 500

OPcache Configuration

ini

; /etc/php/8.2/fpm/conf.d/10-opcache.ini
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
opcache.save_comments=1
opcache.fast_shutdown=1

Database Optimization

sql

-- Add indexes for frequently queried columns
CREATE INDEX idx_knowledge_created_at ON knowledge(created_at);
CREATE INDEX idx_knowledge_status ON knowledge(status);
CREATE INDEX idx_category_name ON category(name);

Rollback Procedure

If deployment fails:

bash

# 1. Revert to previous version
git checkout <previous-tag>

# 2. Restore database backup
mysql -u user -p yappa_db < backup.sql

# 3. Clear cache
php bin/console cache:clear --env=prod

# 4. Restart services
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

Support

For deployment issues:

Check logs: backend/var/log/prod.log
Review health checks: /api/health
Consult documentation: docs/
Contact support: support@example.com

Deployment Guide ​

Prerequisites ​

Environment Setup ​

1. Clone the Repository ​

2. Install Dependencies ​

3. Configure Environment ​

4. Database Setup ​

5. Build Assets ​

Deployment Methods ​

Method 1: Traditional Server Deployment ​

Apache Configuration ​

Nginx Configuration ​

Method 2: Docker Deployment ​

Docker Compose ​

Backend Dockerfile ​

Method 3: Kubernetes Deployment ​

Deployment YAML ​

Post-Deployment Tasks ​

1. Verify Health Checks ​

2. Clear Cache ​

3. Warm Up Cache ​

4. Set Up Cron Jobs ​

Monitoring and Maintenance ​

Health Checks ​

Logs ​

Database Backups ​

Troubleshooting ​

Common Issues ​

Database Connection Errors ​

Permission Issues ​

Cache Issues ​

Security Checklist ​

Performance Optimization ​

PHP-FPM Configuration ​

OPcache Configuration ​

Database Optimization ​

Rollback Procedure ​

Support ​

Deployment Guide

Prerequisites

Environment Setup

1. Clone the Repository

2. Install Dependencies

3. Configure Environment

4. Database Setup

5. Build Assets

Deployment Methods

Method 1: Traditional Server Deployment

Apache Configuration

Nginx Configuration

Method 2: Docker Deployment

Docker Compose

Backend Dockerfile

Method 3: Kubernetes Deployment

Deployment YAML

Post-Deployment Tasks

1. Verify Health Checks

2. Clear Cache

3. Warm Up Cache

4. Set Up Cron Jobs

Monitoring and Maintenance

Health Checks

Logs

Database Backups

Troubleshooting

Common Issues

Database Connection Errors

Permission Issues

Cache Issues

Security Checklist

Performance Optimization

PHP-FPM Configuration

OPcache Configuration

Database Optimization

Rollback Procedure

Support