# Installation & Configuration Guide

Follow this complete technical checklist to deploy the Laravel API backend, the React Admin Panel, and configure third-party services like Zoom, Firebase, and Cron jobs.

1. Backend Laravel API Deployment

The backend serves as the core REST API and handles data structures, calculations, and integrations.

Step 1.1: Clone & Install Dependencies

Navigate to your backend directory and install the required composer dependencies:

composer install --no-dev --optimize-autoloader

Step 1.2: Environment File Setup

Duplicate the environment template file and open it for editing:

cp .env.example .env
nano .env

Configure your MySQL database connection credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=icare_db
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

Step 1.3: Generate App Key & Run Migrations

Secure the installation by generating the Laravel app encryption key, running database schema migrations, and seeding default records (admin user, base roles, and lookup tables):

php artisan key:generate
php artisan migrate --seed

Link the public file storage folder so avatars, prescriptions, and attachments can be accessed:

php artisan storage:link

2. React Admin Panel Deployment

The admin panel is built as a single-page application using React.js and Vite. It consumes backend resources via Sanctum and API key tokens.

Step 2.1: Dependencies Installation

Navigate to the admin folder (e.g. /icare-admin-panel) and run the Node installer:

npm install

Step 2.2: Frontend Environment Configuration

Create an environment file in the root of your admin panel directory:

cp .env.example .env
nano .env

Provide the backend URL that the React frontend will query:

VITE_API_URL=http://localhost:8000/api/v1
VITE_STORAGE_URL=http://localhost:8000/storage

Step 2.3: Compile & Start the Panel

To run the developer server locally with hot reloading:

npm run dev

To compile the optimized production-ready HTML, JS, and CSS bundle under the dist/ folder:

npm run build

3. Docker VPS Deployment Guide

For deploying the application on a VPS containerized environment using Docker & Docker Compose, use the following configurations to spin up your services.

Step 3.1: docker-compose.yml Config

Create a docker-compose.yml file in your VPS deployment root directory to orchestrate the backend API, web server, database, and React frontend:

version: '3.8'

services:
  # MySQL Database Service
  icare-db:
    image: mysql:8.0
    container_name: icare-db
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: icare_db
      MYSQL_ROOT_PASSWORD: secure_db_root_password
    volumes:
      - dbdata:/var/lib/mysql
    ports:
      - "3306:3306"

  # Laravel API Service
  icare-api:
    build:
      context: ./icare-backend
      dockerfile: Dockerfile
    container_name: icare-api
    restart: unless-stopped
    working_dir: /var/www
    volumes:
      - ./icare-backend:/var/www
    depends_on:
      - icare-db

  # Nginx Web Server (Proxying API requests and serving PHP)
  icare-webserver:
    image: nginx:alpine
    container_name: icare-webserver
    restart: unless-stopped
    ports:
      - "8000:80"
    volumes:
      - ./icare-backend:/var/www
      - ./nginx/conf.d/:/etc/nginx/conf.d/
    depends_on:
      - icare-api

  # React Admin Panel Service
  icare-admin:
    build:
      context: ./icare-admin-panel
      dockerfile: Dockerfile
    container_name: icare-admin
    restart: unless-stopped
    ports:
      - "80:80"

volumes:
  dbdata:
    driver: local

Step 3.2: Backend Dockerfile

Create a Dockerfile inside your backend directory (./icare-backend/Dockerfile):

FROM php:8.2-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# Clear cache
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd

# Get latest Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www

# Copy existing application directory contents
COPY . /var/www

# Copy existing application directory permissions
COPY --chown=www-data:www-data . /var/www

# Change current user to www
USER www-data

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

Step 3.3: Frontend Dockerfile

Create a Dockerfile inside your admin panel directory (./icare-admin-panel/Dockerfile) to build the React application and serve it via Nginx:

# Build stage
FROM node:18-alpine as build-stage
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM nginx:stable-alpine as production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Step 3.4: Deploy & Seed

Boot up the containers in detached mode, run migrations, and seed default data:

docker-compose up -d --build
docker-compose exec icare-api php artisan migrate --seed
docker-compose exec icare-api php artisan storage:link

4. Third-Party Integrations Setup

Configure external integrations in the .env file of your backend Laravel app to enable key features.

4.1: Zoom Server-to-Server OAuth Integration

Zoom is used to handle video consultation calls. To configure this:

1. Log in to the Zoom App Marketplace using your developer account credentials.
2. Select Develop -> Build App and choose Server-to-Server OAuth as the app type.
3. Add the required scopes:
   • meeting:write:meeting:admin
   • meeting:update:meeting:admin
   • meeting:delete:meeting:admin
4. Copy your Client ID, Client Secret, and Account ID and paste them in your backend .env file:

ZOOM_CLIENT_ID=your_zoom_client_id
ZOOM_CLIENT_SECRET=your_zoom_client_secret
ZOOM_ACCOUNT_ID=your_zoom_account_id

4.2: Firebase Push Notifications Setup

To push real-time alerts to the Mobile applications:

1. Go to the Firebase Console and create a new project.
2. Open Project Settings -> Service Accounts and click Generate New Private Key to download the credentials JSON file.
3. Place the JSON credentials file inside your backend storage directory and map its path in the environment configuration:

FIREBASE_CREDENTIALS_PATH=storage/app/firebase-credentials.json

5. Automated Scheduler Cron Job Setup

ICARE uses Laravel's task scheduler to automatically dispatch recurring reminder notifications for appointments. To enable this, configure a cron job on your host server to trigger the scheduler every minute.

Depending on your deployment model, choose one of the following Cron tab configurations:

Option A: Native Deployment

* * * * * cd /path-to-your-ICARE-backend-root && php artisan schedule:run >> /dev/null 2>&1

Option B: Docker VPS Deployment

* * * * * docker exec icare-api php artisan schedule:run >> /dev/null 2>&1