Installation Guidelines 🚀

Before you start following the guidelines, make sure to go through the prerequisites guide to install the required tools and packages on your machine.

Note: If you are a Windows user, use GitBash or PowerShell instead of the command prompt.

Navigate to the right directory where your project will be locally saved

For WAMP:
```
cd C:\wamp64\www\
```
For XAMPP:
```
cd C:\xampp\htdocs\
```
For LAMPP:
```
cd C:\opt\htdocs\
```
For MAMP(macOS):
```
cd /Application/MAMP/htdocs/
```

Note- phpMyAdmin/PHP, apache, and MySQL comes preinstalled with the  WAMP, XAMPP package, that is going to be used later on in this project, so no need to install these files separately.

Clone this repository and move to portal directory

git clone https://github.com/coloredcow/portal
cd portal

Install dependencies
```
composer install
npm install
```
npm build
```
npm run dev
```
A possible error may arise with cross-env. So try running the following commands.
- To clear a cache in npm, we need to run the npm cache command in our terminal and install cross-env.
```
npm cache clear --force
npm install cross-env

npm install
npm run dev
```
If you are still getting the error --hide-module then revert all changes by git checkout .

If you are still getting the error then delete the package-lock.json file and make sure your node and npm version are as below and repeat step 4 again.
```
npm -v
# output should be something like
# 9.5.1

node -v
#output should be somthing like
#v18.16.0
```
Make a copy of the .env.example file in the same directory and save it as .env:
```
cp .env.example .env
```
Run the following command to add the Laravel application key:
```
php artisan key:generate
```
Note: Make sure that the 'php.ini' file in XAMPP/WAMP has this code uncommented/written extension=gd
Add the following settings in .env file:
1. Laravel app configurations
```
APP_NAME="ColoredCow Portal"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://portal.test
```
1. Database configurations
- Create a database in your local server. If you skipped it on the prerequisites guideline, you can check it out on point 3.4 of the prerequisites. Go to prerequisites
- Configure your Laravel app with the right DB settings as mentioned below.
- Read the story about how the team discussed which video should be in the docs
```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=portal
DB_USERNAME=root
DB_PASSWORD=
```
Note: Use the default values for MySQL database in .env file
```
DB_USERNAME=root
DB_PASSWORD=
```
These credentials will be used when you will connect to MySQL Server whether you use XAMPP, WAMP, MAMP (PhpMyadmin) or TablePlus, the proper steps you can find here in the prerequisites guide.
1. (Optional) Google configurations.
```
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CLIENT_CALLBACK=
GOOGLE_CLIENT_HD=
GOOGLE_API_KEY=
GOOGLE_APPLICATION_CREDENTIALS=
GOOGLE_SERVICE_ACCOUNT_IMPERSONATE=
```
1. (Optional) ColoredCow website Configurations In case you want to use website integration functionality, then you need to enable WORDPRESS_ENABLED as true and add wordpress database configurations.
  - DB_WORDPRESS_DATABASE: The name of the WordPress database you want to connect to. For example Coloredcow.
  - DB_WORDPRESS_USERNAME: The user name which is define in the Wp-config.php. For example root.
  - DB_WORDPRESS_PASSWORD: If password is define set the password otherwise it should be null.
  - DB*WORDPRESS_PREFIX: The table prefix used by the WordPress installation. This is typically set to cc* by default, but it can be different depending on the configuration.
  - WORDPRESS_ENABLED: Set this to true to enable the integration with the ColoredCow website. If it is set to false the integration will not work.
```
DB_WORDPRESS_DATABASE=Coloredcow
DB_WORDPRESS_USERNAME=root
DB_WORDPRESS_PASSWORD=
DB_WORDPRESS_PREFIX=cc_
WORDPRESS_ENABLED=true
```
Run migrations
```
php artisan migrate
```
Run seeders
1. Portal
```
php artisan db:seed
```
  (Optional) In case you want to run a specific seeder class, use the --class option:
```
php artisan db:seed --class=CLASSNAME
```
2. Module:
```
php artisan module:seed
```
  (Optional) In case you want to run seeders inside a specific module, run:
```
php artisan module:seed MODULE_NAME
```
Setup Virtual Host
1. For WAMP:
  - Go to C:\WINDOWS\system32\drivers\etc\ and open the hosts (not the one with ICS extension) file in notepad (run as administrator). Add the following line at the end:
```
127.0.0.1      portal.test
```
  - Go to C:\wamp64\bin\apache\apache2.4.46\conf\extra\httpd-vhosts.conf and add the following code snippet at the end of the file. Copy the absolute file path for the public directory of the project and paste it below where /path/to/your/project is written. For example, your project path may look like C:\wamp64\www\portal\public.
```
<VirtualHost *:80>
    ServerName portal.test
    DocumentRoot "/path/to/your/project"
    <Directory "/path/to/your/project">
        DirectoryIndex index.php
        AllowOverride All
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>
```
    In case you are using Apache version 2.4 or above, the above code will give you a 403 Forbidden error. Make the following changes:
```
<Directory>
    # some code above
    Order allow,deny
    Allow from all
</Directory>
```
    Change to:
```
<Directory>
     # some code above
     Require all granted
</Directory>
```
  - Restart WAMP. Next, open this url in your browser: http://portal.test
2. For XAMPP:
  - Go to C:\WINDOWS\system32\drivers\etc\ and open the hosts (not the one with ICS extension) file in notepad (run as administrator) or right click the hosts file, click properties, go to security tab click on edit and give administrator permissions to the file. Add the following line at the end:
```
127.0.0.1      portal.test
```
  - Go to C:\xampp\apache\conf\extra\httpd-vhosts.conf and add the following code snippet at the end of the file. Copy the absolute file path for the public directory of the project and paste it below where your_project_path is written. For example, your project path may look like C:\xampp\htdocs\portal\public.
```
<VirtualHost *:80>
    ServerName portal.test
    DocumentRoot "/path/to/your/project"
    <Directory "/path/to/your/project">
        DirectoryIndex index.php
        AllowOverride All
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>

In case you are using Apache version 2.4 or above, the above code will give you a 403 Forbidden error. Make the following changes:
```apacheconf
    <Directory>
        # some code above
        Order allow,deny
        Allow from all
    </Directory>
```
Change to:
```
    <Directory>
         # some code above
         Require all granted
    </Directory>
```
- Restart XAMPP. Next, open this url in your browser: http://portal.test
- Restart XAMPP. Next, open this url in your browser: http://portal.test
3. For LAMPP(LINUX):
  - Go to etc/hosts file or edit this in the terminal use the following command.
```
sudo nano /etc/hosts
```
  - Add this line
```
127.0.0.1   portal.test
```
  - Go to httpd.conf file or edit this file in the terminal itself use this command
```
sudo nano /opt/lampp/conf/apache/httpd.conf
```
    And search for vhosts and uncomment line like this
```
# Virtual hosts
# Include opt/lampp/conf/apache/extra/httpd-vhosts.conf
```
    Change above to:
```
# Virtual hosts
Include opt/lampp/conf/apache/extra/httpd-vhosts.conf
```
    - Open the vhost file in the terminal
      sudo nano /etc/apache2/extra/httpd-vhosts.conf
      Add the following line at the end of the file: Copy the absolute file path for the public directory of the project and paste it below where your_project_path is written. For example, your project path may look like /opt/lampp/htdocs/portal/public. Make sure you type '/public' at the end after your project path.
      <VirtualHost *:80> ServerName portal.test DocumentRoot "/path/to/your/project/public" <Directory "/path/to/your/project/public"> DirectoryIndex index.php AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
    - In case you are using Apache version 2.4 or above, the above code will give you a 403 Forbidden error. Make the following changes:
      <Directory> # some code above Order allow,deny Allow from all </Directory>
      Change to:
      <Directory> # some code above Require all granted </Directory>
    - Restart MAMP. Next, open this url in your browser: http://portal.test
4. For MAMP(macOS):
  - Go to etc/hosts file or edit this in the terminal use the following command.
```
sudo nano /etc/hosts
```
  - Add this line
```
127.0.0.1   portal.test
```
  - Go to httpd.conf file or edit this file in the terminal itself use this command
```
sudo nano /Applications/MAMP/conf/apache/httpd.conf
```
    And search for vhosts and uncomment line like this
```
# Virtual hosts
# Include Applications/MAMP/conf/apache/extra/httpd-vhosts.conf
```
    Change above to:
```
# Virtual hosts
Include Applications/MAMP/conf/apache/extra/httpd-vhosts.conf
```
    - Open the vhost file in the terminal
      sudo nano /etc/apache2/extra/httpd-vhosts.conf
      Add the following line at the end of the file: Copy the absolute file path for the public directory of the project and paste it below where your_project_path is written. For example, your project path may look like /Application/MAMP/htdocs/portal/public. Make sure you type '/public' at the end after your project path.
      <VirtualHost *:80> ServerName portal.test DocumentRoot "/path/to/your/project/public" <Directory "/path/to/your/project/public"> DirectoryIndex index.php AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
    - In case you are using Apache version 2.4 or above, the above code will give you a 403 Forbidden error. Make the following changes:
      <Directory> # some code above Order allow,deny Allow from all </Directory>
      Change to:
      <Directory> # some code above Require all granted </Directory>
    - Restart MAMP. Next, open this url in your browser: http://portal.test
Login to the portal using the newly created user in the database. Go to http://localhost/phpmyadmin/index.php click on portal database that we created mostly on the left and search for the users table, click on users table and you can find the first user email in it. The default password to log in is 12345678.

(Optional) Setup Email configuration:

Open Mailtrap and signup/login.
Create an inbox.
Open inbox setting and choose Laravel 7+ from Integrations.

Open .env file and add the following

MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=yourPortNumber
MAIL_USERNAME=yourMailtrapUsername
MAIL_PASSWORD=yourMailtrapPassword
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=senderEmailAddress
MAIL_FROM_NAME="${APP_NAME}"

(Optional) Setup pdf generator tool for automatic invoice creation:
1. Open site https://wkhtmltopdf.org/downloads.html and download wkhtmltopdf for window and install it
2. Open .env file and add the following
```
For Windows:
PDF_BINARY='C://"Program Files"/wkhtmltopdf/bin/wkhtmltopdf.exe'

For Mac:
PDF_BINARY="/usr/local/bin/wkhtmltopdf"
```
3. Run the following command in the terminal
```
php artisan optimize
```
(Optional) Setup API Layer API Key for currency excahange rates:
1. Open site https://apilayer.com/
2. Click on "Browse API Marketplace".
1. Under catogories click on "Currency"
1. Select Currency Data API.
2. Select the Free plan.
3. Copy your API key and paste it in the .env file. CURRENCYLAYER_API_KEY=your api key
4. Run the command php artisan config:cache
(Optional) Setup Google Service Account for syncing effortsheet on local:
1. Open Google Console https://console.cloud.google.com/
2. Create a new project by clicking CREATE PROJECT.
1. Give any name to the Project
1. Enable the following APIs and services by clicking the "Enable APIs and Services" button: (i) Google Drive API (ii) Google Sheets API
2. The next step is to create credentials. Click on Credentials on the left panel and then Create Credentials.
1. Fill in the following details: (i) Service account details
  
  (ii) Grant this service account access to the project by selecting a role (Project -> Editor)
2. Go back to credentials and click on edit option in service account section.
3. Go to keys and click on add key button and select Create New Key option.
4. A JSON file will be downloaded when you create credentials and key, move that JSON file to the /portal/public/ folder inside the project.
5. You have to create a OAuth 2.0 Client ID to get your Client ID and Client Secret
  1. For this Click on Create Credentials and select OAuth Client ID
  2. You may need to first configure your consent screen. Click on Configure Consent Screen. Select your User Type as External, click on create
  3. In the App information give any name and your user email. In the Authorized domains click on add domain and fill it with "auth0.com" and again give your email in Developer Contact Information.
  4. Click save on the next step and in the Test users step provide your email, click on save. Now you have configured. Now go to Credentials to create OAuth Client 2.0 ID
  5. Select your Application Type as Web and name as anything(Ex: Client). CLick on save and now you will get both Google Client ID and Client Secret
6. Open the .env file and add the following
```
GOOGLE_CLIENT_ID= #Copy it from the credentials(OAuth 2 Client ID)
GOOGLE_CLIENT_SECRET= #Copy it from the credentials(Key ID)
GOOGLE_CLIENT_CALLBACK=
GOOGLE_CLIENT_HD=
GOOGLE_API_KEY=
GOOGLE_APPLICATION_CREDENTIALS=
GOOGLE_SERVICE_ACCOUNT_IMPERSONATE=
GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION= #Copy the path of the downloaded JSON file after moving it to the /portal/public/ folder
```
  Note Add double backward slash \\ while adding the file path because single backward slash is considered as escape sequence
7. Copy the Email from the Service Accounts details
8. Add the email by clicking on the share button
9. Run the command php artisan config:cache
10. Open the ColoredCow portal http://portal.test/login/
11. Go to CRM->Projects and select any of the projects.
12. After opening the project click on edit button and enter the Effortsheet URL then, click on Save button.
13. Go to phpmyadmin, open users table and change the nicknames of users as team member names in effortsheet.
(Optional) Steps to Verify the syncing of effortsheet on local:
1. Go to CRM -> Projects -> select a project, click on edit, and add a team member (e.g., Admin). Choose a designation from the drop-down lists and input a random number in the Expected Efforts In Hours field. Click on save.
2. Next, navigate to the Effort Sheet and choose a name (e.g., Mike). Open PhpMyAdmin and go to the users table. Locate the team member you added (e.g., Admin) and assign them the nickname of the person you chose from the Effort Sheet (e.g., Mike).
3. Go to employees table, add/edit rows with the exact ID and name from the users table (do not use nicknames). Save the changes.
4. Return to the portal site, select your project, and click on the Sync button. You should now see the team member added in the Team Members table.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

installation.md

installation.md

Installation Guidelines 🚀

Files

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation Guidelines 🚀