Setup & Deployment Guide

System Requirements

Backend Requirements

PHP: >= 8.1 (recommended 8.3)
Web Server: Apache/Nginx
Database: MySQL 8.0+ or MariaDB 10.4+
Redis: 6.0+ (for caching and sessions)
Composer: 2.0+
Node.js: 14+ (for asset compilation)

Frontend Requirements

Node.js: 14, 15, 16, or 18
NPM: >= 6
Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)
Memory: 4GB+ RAM recommended
Storage: 2GB+ free space

Additional Services

Service	Purpose	Required	Notes
Auth0	Authentication provider	Yes	Create free developer account
AWS S3	File storage	Development	Can use local storage for dev
Stripe	Payment processing	Optional	For billing features
Mailtrap	Email testing	Recommended	For development email testing

Development Tools

Code Editors

Visual Studio Code (recommended)
PhpStorm
Sublime Text

Database Tools

phpMyAdmin
MySQL Workbench
Sequel Pro/Sequel Ace
TablePlus

API Testing

Postman
Insomnia
Thunder Client (VS Code)
cURL

1

Clone the Repositories

Clone both the backend and frontend repositories to your local machine:

# Clone backend repository
git clone git@github.com:ComplianceScorecard/polygon-be.git
cd polygon-be

# Clone frontend repository  
git clone git@github.com:ComplianceScorecard/polygon-fe.git
cd polygon-fe

SSH Keys: Ensure you have SSH keys configured for GitHub access. You can also use HTTPS URLs if preferred.

2

Backend Setup (Laravel)

Install Dependencies

cd polygon-be

# Install PHP dependencies
composer install

# Install Node dependencies (for asset compilation)
npm install

Environment Configuration

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

Database Setup

# Create database
mysql -u root -p
CREATE DATABASE compliance_scorecard;
EXIT;

# Run migrations
php artisan migrate

# Seed the database
php artisan db:seed --class=PermissionSeeder
php artisan db:seed --class=RoleSeeder
php artisan db:seed --class=RolePermissionSeeder
php artisan db:seed --class=AuditorRoleSeeder
php artisan db:seed --class=PeerGroupAdminRoleSeeder
php artisan db:seed --class=SuperadminInitialRMFSeeder

Start Development Server

# Start Laravel development server
php artisan serve

# The backend will be available at http://127.0.0.1:8000

3

Frontend Setup (React)

Install Dependencies

cd polygon-fe

# Install dependencies
npm install

# Or for a clean install
npm run install:clean

Environment Configuration

Create a .env file in the frontend root:

# .env file
REACT_APP_BASE_URL=http://localhost:3000
REACT_APP_BACKEND_API_URL=http://127.0.0.1:8000
REACT_APP_AUTH0_DOMAIN=your-auth0-domain.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-auth0-client-id
REACT_APP_AUTH0_AUDIENCE=your-api-audience
REACT_APP_TINYMC_API_KEY=your-tinymce-api-key
REACT_APP_INACTIVE_LIMIT=3600000

Start Development Server

# Start React development server
npm start

# The frontend will be available at http://localhost:3000

Database Configuration

Environment Variables

Configure the following database settings in your .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=compliance_scorecard
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Cache & Session
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Database Features

200+ migrations
Complex relationships
Soft deletes
Activity logging
Index optimization
Foreign key constraints

Performance Optimization

# Optimize autoloader
composer dump-autoload --optimize

# Cache configuration
php artisan config:cache

# Cache routes (production only)
php artisan route:cache

# Cache views
php artisan view:cache

Environment Variables

Complete .env Configuration

# Application
APP_NAME="Compliance Scorecard"
APP_ENV=local
APP_KEY=base64:your-generated-key
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=compliance_scorecard
DB_USERNAME=root
DB_PASSWORD=

# Auth0 Configuration
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_AUDIENCE=your-api-audience

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your-mailtrap-username
MAIL_PASSWORD=your-mailtrap-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@compliancescorecard.com
MAIL_FROM_NAME="Compliance Scorecard"

# AWS S3
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name

# Stripe
STRIPE_KEY=pk_test_your-publishable-key
STRIPE_SECRET=sk_test_your-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

# Redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Cache & Sessions
CACHE_DRIVER=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120
QUEUE_CONNECTION=redis

# Sentry (Error Tracking)
SENTRY_LARAVEL_DSN=your-sentry-dsn

Auth0 Configuration

4

Auth0 Application Setup

1. Create Auth0 Account & Application

Sign up for a free Auth0 account at auth0.com
Create a new Single Page Application
Note your Domain, Client ID, and Client Secret

2. Configure Application Settings

Setting	Value
Allowed Callback URLs	`http://localhost:3000`
Allowed Logout URLs	`http://localhost:3000`
Allowed Web Origins	`http://localhost:3000`
Allowed Origins (CORS)	`http://localhost:3000`

3. Create API

Create an API in Auth0 for backend authentication:

Go to APIs section in Auth0 dashboard
Create new API with identifier (e.g., https://api.compliancescorecard.com)
Use this identifier as REACT_APP_AUTH0_AUDIENCE

External Integrations Setup

Stripe (Optional)

For payment processing and billing:

Create Stripe account
Get API keys from dashboard
Configure webhook endpoints
Add keys to .env file

TinyMCE

For rich text editing:

Sign up at tiny.cloud
Get your API key
Add to frontend .env as REACT_APP_TINYMC_API_KEY
Configure custom plugins if needed

Email Testing

Using Mailtrap for development:

Create account at mailtrap.io
Create inbox for testing
Get SMTP credentials
Configure in backend .env

Error Tracking

Sentry for error monitoring:

Create Sentry account
Create project for Laravel
Get DSN from project settings
Add to backend .env

Docker Deployment

5

Container Setup

Backend Docker Configuration

The backend includes a Dockerfile for containerization:

# Build backend image
cd polygon-be
docker build -t compliance-scorecard-backend .

# Run with environment variables
docker run -d \
  --name cs-backend \
  -p 8000:80 \
  -e DB_HOST=your-db-host \
  -e DB_DATABASE=compliance_scorecard \
  compliance-scorecard-backend

Frontend Docker Configuration

# Build frontend image
cd polygon-fe
docker build -t compliance-scorecard-frontend .

# Run frontend container
docker run -d \
  --name cs-frontend \
  -p 3000:80 \
  -e REACT_APP_BACKEND_API_URL=http://your-backend-url \
  compliance-scorecard-frontend

Docker Compose (Recommended)

Create a docker-compose.yml for the complete stack:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: compliance_scorecard
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    image: redis:6-alpine
    ports:
      - "6379:6379"

  backend:
    build: ./polygon-be
    ports:
      - "8000:80"
    environment:
      - DB_HOST=mysql
      - REDIS_HOST=redis
    depends_on:
      - mysql
      - redis

  frontend:
    build: ./polygon-fe
    ports:
      - "3000:80"
    environment:
      - REACT_APP_BACKEND_API_URL=http://localhost:8000
    depends_on:
      - backend

volumes:
  mysql_data:

Environment Setup

Development Environment

URL: dev-api.compliancerisk.io

Purpose: Active development and testing with frequent deployments

Debug mode enabled
Detailed error reporting
Test data and fixtures
Integration testing

Deployment Process:

Push to dev branch
Automated CI/CD pipeline
Run tests and linting
Deploy to dev environment

Staging Environment

URL: staging-api.compliancerisk.io

Purpose: Pre-production testing and stakeholder review

Production-like configuration
Performance testing
User acceptance testing
Integration verification

Deployment Process:

Merge to staging branch
Full test suite execution
Manual deployment approval
Stakeholder notification

Production Environment

URL: go-api.compliancerisk.io

Purpose: Live production system serving real customers

Optimized performance
Error logging and monitoring
Backup and disaster recovery
High availability setup

Deployment Process:

Tag release version
Comprehensive testing
Maintenance window scheduling
Rollback plan preparation

CI/CD Pipeline

Automated Workflow

The project uses GitHub Actions for continuous integration and deployment:

# Example GitHub Actions workflow
name: CI/CD Pipeline

on:
  push:
    branches: [ dev, staging, main ]
  pull_request:
    branches: [ dev ]

jobs:
  backend-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3
      - name: Install dependencies
        run: composer install
      - name: Run tests
        run: php artisan test

  frontend-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

  deploy:
    needs: [backend-tests, frontend-tests]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/dev'
    steps:
      - name: Deploy to development
        run: |
          # Deployment commands here

Pipeline Steps

Code quality checks
Dependency security scan
Unit and integration tests
Build artifacts
Deploy to target environment
Post-deployment verification
Notification to team

Deployment Best Practices

Branch Strategy

Feature branches → dev → staging → main

Zero Downtime

Blue-green deployments with health checks

Rollback Ready

Automated rollback on deployment failures

Troubleshooting

Verify database credentials in .env file
Ensure MySQL service is running
Check if database exists: SHOW DATABASES;
Test connection: php artisan tinker → DB::connection()->getPdo();

Verify Auth0 domain and client ID in frontend .env
Check allowed callback URLs in Auth0 dashboard
Ensure API audience is correctly configured
Clear browser cache and localStorage

Update config/cors.php to allow frontend origin
Check SANCTUM_STATEFUL_DOMAINS in backend .env
Verify API endpoints are accessible from frontend domain
Clear Laravel config cache: php artisan config:clear

System Requirements

Backend Requirements

Frontend Requirements

Additional Services

Development Tools

Code Editors

Database Tools

API Testing

Install Dependencies

Environment Configuration

Database Setup

Start Development Server

Install Dependencies

Environment Configuration

Start Development Server

Database Configuration

Environment Variables

Database Features

Performance Optimization

Environment Variables

Complete .env Configuration

Auth0 Configuration

1. Create Auth0 Account & Application

2. Configure Application Settings

3. Create API

External Integrations Setup

Stripe (Optional)

TinyMCE

Email Testing

Error Tracking

Docker Deployment

Backend Docker Configuration

Frontend Docker Configuration

Docker Compose (Recommended)

Environment Setup

Development Environment

Deployment Process:

Staging Environment

Deployment Process:

Production Environment

Deployment Process:

CI/CD Pipeline

Automated Workflow

Pipeline Steps

Deployment Best Practices

Branch Strategy

Zero Downtime

Rollback Ready

Troubleshooting

Database Connection Issues

Auth0 Authentication Problems

CORS Issues