Skip to main content

​
System Requirements

Before installing Dashboard Dilemas, ensure your environment meets these requirements:

​
Server Requirements

  • PHP: 7.4 or higher
  • MySQL: 5.7 or higher (or MariaDB equivalent)
  • Web Server: Apache or Nginx
  • Node.js: 14.x or higher (for build tools)

​
PHP Extensions

  • PDO
  • PDO_MySQL
  • mbstring
  • json
  • openssl (for session management)
  • Composer: For PHP dependency management
  • NPM/PNPM/Yarn: For Node.js dependencies
  • Cron: For automated tasks (email reminders, reports)
Dashboard Dilemas uses WordPress-compatible database naming conventions but does not require WordPress to be installed.

​
Installation Steps

​
1. Clone or Download the Project

Download the Dashboard Dilemas source code to your server: 
git clone <repository-url> dashboard-dilemas
cd dashboard-dilemas

​
2. Install Node.js Dependencies

Install the required packages for database setup and build tools: 
npm install mysql2 dotenv
Or using alternative package managers: 
# Using pnpm (faster)
pnpm add mysql2 dotenv

# Using yarn
yarn add mysql2 dotenv
The mysql2 package is used for database initialization scripts, while dotenv manages environment configuration.

​
3. Configure Environment Variables

Create your environment configuration file: 
cp .env.example .env
Edit the .env file with your database credentials:
.env
DB_HOST=localhost
DB_USER=your_database_user
DB_PASSWORD=your_secure_password
DB_NAME=wordpress_db
Security Best Practices:
  • Never commit your .env file to version control
  • Use strong, unique passwords for database access
  • Restrict database user permissions to only necessary operations
  • Consider using 127.0.0.1 instead of localhost for MySQL connections to force TCP/IP

​
4. Create the Database

Create a new MySQL database for the application: 
CREATE DATABASE wordpress_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Grant appropriate permissions to your database user: 
GRANT ALL PRIVILEGES ON wordpress_db.* TO 'your_database_user'@'localhost';
FLUSH PRIVILEGES;

​
5. Initialize Database Schema

Run the database setup script to create all required tables: 
node scripts/setup-db.js
This script creates the following tables:
  • de_app_clients - Client organizations
  • de_app_areas - Organizational areas/departments
  • de_app_users - Platform users and participants
  • de_app_games - Dilemma scenarios/games
  • de_app_game_questions - Questions within each dilemma
  • de_app_answers - User responses and submissions
  • de_app_sessions - User authentication sessions
The setup script creates the table structure only. You may need to import initial data separately or create it through the admin interface.

​
6. Configure Web Server

​
Apache Configuration

Create a virtual host configuration: 
<VirtualHost *:80>
    ServerName dashboard-dilemas.local
    DocumentRoot /var/www/dashboard-dilemas
    
    <Directory /var/www/dashboard-dilemas>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/dashboard-dilemas-error.log
    CustomLog ${APACHE_LOG_DIR}/dashboard-dilemas-access.log combined
</VirtualHost>
Enable required Apache modules: 
sudo a2enmod rewrite
sudo systemctl restart apache2

​
Nginx Configuration

Create a server block: 
server {
    listen 80;
    server_name dashboard-dilemas.local;
    root /var/www/dashboard-dilemas;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

​
7. Set File Permissions

Ensure proper file permissions for security: 
# Set ownership to web server user
sudo chown -R www-data:www-data /var/www/dashboard-dilemas

# Set directory permissions
find /var/www/dashboard-dilemas -type d -exec chmod 755 {} \;

# Set file permissions
find /var/www/dashboard-dilemas -type f -exec chmod 644 {} \;

# Protect sensitive files
chmod 600 .env
Never set permissions to 777. This creates security vulnerabilities. Use the minimum required permissions.

​
8. Configure Automated Tasks (Optional)

Set up cron jobs for automated email reminders and reports: 
crontab -e
Add the following entries: 
# Send daily email reminders at 9 AM
0 9 * * * /usr/bin/php /var/www/dashboard-dilemas/cron_email_reminders.php

# Generate weekly reports every Monday at 8 AM
0 8 * * 1 /usr/bin/php /var/www/dashboard-dilemas/weekly_report.php
Adjust the paths and timing based on your server configuration and business needs.

​
9. Start Development Server (Development Only)

For local development, you can use the built-in development server: 
npm run dev
The application will be available at http://localhost:3000.
The development server is not suitable for production use. Always use a proper web server (Apache/Nginx) in production environments.

​
Verification

Verify your installation by checking:
  1. Database Connection: Ensure all tables were created successfully 
    mysql -u your_user -p wordpress_db -e "SHOW TABLES;"
  2. Web Access: Navigate to your dashboard URL and verify the login page loads
  3. PHP Configuration: Check that all required PHP extensions are loaded 
    php -m | grep -E 'pdo|mysql|mbstring|json'

​
Post-Installation

After successful installation:
1

Create Admin Account

Set up your first administrator account through the database or admin interface
2

Configure Email Settings

Set up SMTP credentials for sending invitations and certificates
3

Review Security

Ensure .env file is not web-accessible and database credentials are secure
4

Test Core Workflows

Create a test client, user, and dilemma to verify functionality

​
Troubleshooting

​
Database Connection Errors

If you encounter connection issues:
  • Verify database credentials in .env
  • Ensure MySQL service is running: sudo systemctl status mysql
  • Check MySQL user permissions
  • Try using 127.0.0.1 instead of localhost for DB_HOST

​
Permission Denied Errors

If you see file permission errors:
  • Verify web server user ownership
  • Check that directories have 755 permissions
  • Ensure files have 644 permissions
  • Check SELinux/AppArmor policies if enabled

​
Missing PHP Extensions

Install missing extensions: 
# Ubuntu/Debian
sudo apt-get install php-pdo php-mysql php-mbstring php-json

# CentOS/RHEL
sudo yum install php-pdo php-mysqlnd php-mbstring php-json

​
Next Steps

Quick Start

Follow the quickstart guide to create your first dilemma workflow

Database Schema

Understand the database structure and relationships

Environment Config

Learn about advanced environment configuration options

Email Setup

Configure SMTP for automated emails and notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us