Installation Guide

This guide provides detailed instructions for setting up EpiDash in various environments, from local development to production deployment.

Prerequisites

Before installing EpiDash, ensure your system meets the following requirements:

System Requirements

• Web server (Apache, Nginx, or similar)
• PHP 7.4 or higher
• MySQL 5.7+ or MariaDB 10.3+ (for database mode)
• Modern web browser (Chrome, Firefox, Safari, Edge)

Required PHP Extensions

• PDO and PDO_MySQL (for database connectivity)
• JSON (for API responses)
• GD or ImageMagick (for potential image processing)
• cURL (for potential external API connections)

Installation Methods

Method 1: Direct Download (Simplest)

1. Download the latest release from the [GitHub repository](https://github.com/dlangkip/epidash)
2. Extract the downloaded ZIP file to your web server's document root or a subdirectory
3. Continue with the [Configuration](#configuration) section below

Method 2: Git Clone (Recommended for Developers)

1. Open a terminal and navigate to your web server's document root or preferred installation directory
2. Clone the repository:

   git clone https://github.com/dlangkip/epidash.git
   

3. Navigate to the project directory:

   cd epidash
   

4. Continue with the [Configuration](#configuration) section below

Configuration

Environment Setup

1. Navigate to the project's api directory
2. Copy the example environment file:

   cp .env.example .env
   

3. Open the .env file in a text editor and configure the following settings:

Basic Settings

APP_NAME=EpiDash
APP_VERSION=1.0.0
APP_AUTHOR=Kiprotich

TIMEZONE=Africa/Nairobi
DISPLAY_ERRORS=1  # Set to 0 in production

Data Source Configuration

# Set your preferred data source: 'mock', 'database', or 'both'
DEFAULT_DATA_SOURCE=mock
ALLOW_SOURCE_SWITCHING=true

# Date range defaults
DEFAULT_START_DATE=2023-01-01
DEFAULT_END_DATE=2023-12-31

Database Configuration (if using database mode)

DB_HOST=localhost
DB_NAME=epidash
DB_USER=your_database_username
DB_PASS=your_database_password

Security Settings

ENABLE_CORS=true
CSRF_PROTECTION=true

Web Server Configuration

Apache

If using Apache, the included .htaccess file should work out of the box. Ensure that mod_rewrite is enabled on your server.

To verify Apache has the required modules:

apache2ctl -M | grep rewrite
apache2ctl -M | grep headers

Nginx

If using Nginx, add the following configuration to your server block:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/epidash;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # Adjust based on your PHP version
    }

    # Set cache headers for static assets
    location ~* \.(css|js|jpg|jpeg|png|gif|svg|ico)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }
}

Database Setup (Optional)

If you're using the database mode instead of mock data:

1. Create a new MySQL database:

   CREATE DATABASE epidash CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   

2. Create a database user:

   CREATE USER 'epidash_user'@'localhost' IDENTIFIED BY 'your_secure_password';
   GRANT ALL PRIVILEGES ON epidash.* TO 'epidash_user'@'localhost';
   FLUSH PRIVILEGES;
   

3. Import the database schema:

   mysql -u epidash_user -p epidash < database/epidash.sql
   

4. Update your .env file with the database credentials

Verification

To verify your installation is working correctly:

1. Open your web browser and navigate to the EpiDash URL (e.g., http://localhost/epidash or your domain)
2. You should see the dashboard interface load with sample data visualizations
3. Check that the filters, charts, and maps are working correctly
4. If using database mode, verify that data is being retrieved from the database

Troubleshooting

If you encounter any issues:

1. Check your web server's error logs:

   • Apache: /var/log/apache2/error.log (Linux) or check your Apache configuration
   • Nginx: /var/log/nginx/error.log

2. Enable PHP error display in development:

   • Set DISPLAY_ERRORS=1 in your .env file
   • Check for errors in the browser console

3. Test the API directly:

   • Navigate to http://your-server/epidash/api/get_data.php in your browser
   • You should see a JSON response with data

4. Database connection issues:

   • Verify database credentials in the .env file
   • Ensure the database user has proper permissions
   • Check that required PHP extensions are enabled

Security Considerations

For production deployments, consider the following security measures:

1. Set DISPLAY_ERRORS=0 in your .env file
2. Use HTTPS for all traffic (configure SSL on your web server)
3. Use a dedicated database user with appropriate permissions
4. Restrict access to the .env file (the .htaccess file includes this restriction for Apache)
5. Consider implementing user authentication for sensitive data

Next Steps

Now that you have EpiDash installed and configured, you can:

• Explore the User Guide to learn about dashboard features
• Check the Technical Documentation for more details on the codebase
• Review the API Reference if you plan to integrate with external systems

For any questions or issues with installation, please create an issue on the GitHub repository or contact the developer directly.