Setup.md

Setup Guide for DevNation CMS

Table of Contents

• Overview
• Prerequisites
  • Detailed Node.js Installation
  • Setting Up XAMPP
• Setup Process
• Common Errors and Troubleshooting
• Conclusion

Overview

This document provides a comprehensive guide to setting up the DevNation-CMS project on your local machine. It includes prerequisites, step-by-step instructions, and troubleshooting tips to help you get started quickly and efficiently.

Prerequisites

Before you begin, ensure you have the following installed on your computer:

• GitHub Account: Create one here if you don't have it.
• Visual Studio Code (or any preferred code editor): Download from here.
• Git: Install from here.
• PHP: Install the latest version from here or use XAMPP/WAMP.
• Composer: PHP dependency manager, download from here.
• Node.js: JavaScript runtime, install as described below.

Detailed Node.js Installation

1. Download Node.js:

   • Visit the Node.js website.
   • Choose the LTS (Long Term Support) version for stability.

2. Install Node.js:

   • Run the downloaded installer.
   • Follow the on-screen instructions, ensuring both Node.js and npm are selected for installation.

3. Verify the Installation:

   • Open your terminal or command prompt.
   • Run the following commands:

     node -v
     npm -v

   • Both should return version numbers, confirming successful installation.

Setting Up XAMPP

XAMPP provides a local PHP development environment. Here's how to set it up:

1. Download XAMPP: Visit the XAMPP website and download the installer.
2. Install XAMPP: Run the installer and follow the on-screen instructions.
3. Start Apache and MySQL: Open the XAMPP Control Panel and start these services.

Roadmap for Setting Up DevNation CMS

1. Check out the contribution.md file: This file contains important instructions for contributing to the project, including how to fork and clone the repository.

2. Set Up Environment Variables:

   • Copy the example environment file:

     cp .env.example .env

   • Open .env and update with your local settings:

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

3. Install Dependencies:

   • Install PHP dependencies:

     composer install

   • This command reads the composer.json file in your project directory and installs all required dependencies into the vendor folder.

4. Run Migrations:

   • If the project uses a database, run the migrations to set up the database schema:

     php artisan migrate

   • This command creates the tables defined in your migration files in the database specified in your .env file.

5. Seed the Database:

   • If you want to populate your database with initial data:
     • Go to the /database directory and create a file named database.sqlite. Then run:

     php artisan migrate:fresh --seed

   • The migrate:fresh command drops all existing tables and then runs all migrations again, followed by seeding the database with initial data defined in your seed classes.

6. Start the Application:

   php artisan serve

   Access the application at http://localhost:8000.

Common Errors and Troubleshooting

Click to expand Common Errors and Troubleshooting

• Error: Failed to connect to database

  • Ensure your database credentials in the .env file are correct. Verify that the database you specified exists and that the username and password are accurate.

• Error: Class 'App\Http\Controllers\Controller' not found

  • This may indicate a missing namespace or an issue with autoloading. Run the following command to refresh the autoloader:

    composer dump-autoload

• Error: composer install fails

  • Ensure you have Composer installed correctly. You can check if Composer is installed by running:

    composer --version

  • If it’s not recognized, revisit the Composer installation guide to resolve any issues.
  • Another potential reason could be missing PHP extensions, like mbstring or openssl. Install the required extensions for your OS:

    sudo apt-get install php-mbstring php-xml php-zip

• Error: npm install failed (if applicable)

  • If your project has a package.json file and you need to install JavaScript dependencies, ensure you have Node.js and npm installed. Check the Node.js version by running:

    node -v

  • If it's outdated, consider updating Node.js.

• Error: PHP version compatibility

  • The project may require a specific PHP version. Check the required version in the composer.json file under the "php": key and make sure your local PHP version matches.
    • To check your PHP version, run:

      php -v

    • If the version is outdated, update your PHP to the latest stable version or the required version for the project. On Ubuntu, you can run:

      sudo add-apt-repository ppa:ondrej/php
      sudo apt-get update
      sudo apt-get install php7.4

• Error: Laravel Framework not detected

  • If the error mentions something like laravel/framework is missing, it might be due to missing or incomplete Composer installation. Run:

    composer install

  • If that fails, try manually requiring the Laravel framework in your project using:

    composer require laravel/framework

• Error: php.ini configuration issues

  • If certain PHP extensions are not enabled, it can lead to issues with Composer and PHP scripts.
    • Open the php.ini file (located in your PHP installation folder) and ensure the following extensions are uncommented:

      ;extension=intl   # Change this line to:
      extension=intl
      
      ;extension=fileinfo  # Change this line to:
      extension=fileinfo
      
      ;extension=zip  # Change this line to:
      extension=zip

• Error: php.ini post_max_size and upload_max_filesize

  • If you're uploading files and encounter errors due to file size limits, adjust these values in your php.ini file:

    post_max_size = 100M
    upload_max_filesize = 100M

• Error: Class 'PDO' not found

  • This error indicates that the pdo_mysql extension is not enabled in your PHP configuration. To enable it:
    1. Open your php.ini file.
    2. Search for ;extension=pdo_mysql and remove the semicolon (;) at the beginning of the line.

• Error: Composer certificate error

  • To resolve this error, reinstall Composer from the official Composer website. Additionally, ensure you download the latest version of PHP from the official PHP website and update your environment variables accordingly.
  • Another potential issue could be missing OpenSSL on your system. Ensure it's installed:
    • On Ubuntu:

      sudo apt-get install openssl

    • On Windows, ensure the openssl extension is enabled in php.ini.

• Error: Mcrypt PHP extension is required

  • Laravel versions older than 5.1 use Mcrypt, which is deprecated in PHP 7.2 and later. If you're using an older Laravel project with a newer PHP version, either downgrade your PHP version or upgrade Laravel. Alternatively, you can replace Mcrypt with newer encryption libraries supported by Laravel.

• Error: Memory Limit Exhausted

  • If you encounter a Fatal error: Allowed memory size of X bytes exhausted error while running Composer or PHP scripts, increase the memory limit in your php.ini file:

    memory_limit = 512M

  • Or run Composer with increased memory:

    COMPOSER_MEMORY_LIMIT=-1 composer install

Conclusion

This setup guide should help you establish a local environment for the DevNation CMS project. If you encounter any issues not covered here, please raise an issue in the repository or seek assistance from the community.

Happy coding!