Getting Started

Installation

This guide covers the installation of the Klinik Gunung Health Screening System using Laravel 12, Next.js, TanStack Query, and MySQL.

The following guide explains how to install, configure, and run the Klinik Gunung Health Screening System - a digital health screening platform built with Laravel 12, Next.js, and TanStack Query v5.

Prerequisites

PHP 8.3+ (required by Laravel 12)
Composer (for PHP dependency management)
Node.js 22+
NPM (for managing frontend dependencies)
MySQL 8+ (as the primary database)

Installation Prerequisites

Memasang PHP 8.3+

terminal

# Add the packages.sury.org/php repository.
sudo apt-get update
sudo apt-get install -y lsb-release ca-certificates apt-transport-https curl
sudo curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt-get update

# Install PHP.
sudo apt-get install -y php8.4

terminal

sudo apt install -y php8.4-dom php8.4-curl php8.4-xml php8.4-mbstring php8.4-gd php8.4-zip

Composer

terminal

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'c8b085408188070d5f52bcfe4ecfbee5f727afa458b2573b8eaaf77b3419b0bf2768dc67c86944da1544f06fa544fd47') { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"
php composer-setup.php
php -r "unlink('composer-setup.php');"

sudo mv composer.phar /usr/local/bin/composer

To verify your setup, run:

php -v
composer -V
node -v
pnpm -v
mysql --version

You need Git to clone the repository. Download it from here.

git --version

Use a modern code editor, such as:

Before starting, you should be familiar with:

Laravel basics: routes, controllers, migrations.
Next.js fundamentals: routing, components, and API integration.
TanStack Query v5+: client-side data fetching and caching.
MySQL database management.
RESTful API communication.

Installation

Clone the project to your local machine:

git clone https://github.com/<repo>.git

Change directory to the project folder:

cd <repo>

This repository contains both the Laravel API (backend) and Next.js (frontend) under separate directories.

Backend (Laravel 12 API)

Navigate to the Laravel directory:
```
cd api
```
Install dependencies:
```
composer install
```
Create the environment file:
```
cp .env.example .env
```

Configure your .env file:

DB_CONNECTION=mysql
DB_HOST=
DB_PORT=3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

Generate the application key:
```
php artisan key:generate
```
Run migrations and seeders:
```
php artisan migrate --seed
```
Start the Laravel development server:
```
php artisan serve
```
The API will be available at:
```
http://localhost:8000
```

Frontend (Next.js 15 + TanStack Query)

Navigate to the Next.js frontend directory:
```
cd frontend
```
Install dependencies:
```
npm install
```
Create the environment file:
```
cp .env.example .env.local
```
Configure your .env.local file to point to the Laravel API:
```
NEXT_PUBLIC_API_URL=http://localhost:8000/api
```
Run the development server:
```
pnpm run dev
```
Open your browser and go to:
```
http://localhost:3000
```

Folder Structure Overview

klinik-gunung-system/
├── api/        # Laravel 12 API
│   ├── app/
│   ├── routes/
│   ├── database/
│   └── .env
├── frontend/       # Next.js 15 + TanStack Query
│   ├── app/
│   ├── components/
│   ├── lib/
│   └── .env.local
└── README.md

Backend (Laravel): All controllers, models, and routes can be found in the app/ and routes/api.php directories.
Frontend (Next.js): Modify components in src/components and pages in src/app.
TanStack Query: Query and mutation hooks are implemented in /providers/QueryProvider.tsx or /lib/api/.

To update UI or logic, simply modify the respective files and restart your development server.

For the backend:

php artisan optimize
php artisan config:cache

For the frontend:

pnpm run build

Run Laravel:

php artisan serve --env=production

Run Next.js:

pnpm run start

Both applications should now be live:

API → http://your-server:8000
Frontend → http://your-server:3000

Optional

You can deploy both API and frontend to your VPS or local Proxmox environment.

Recommended setup:

API (Laravel): Serve with Nginx or Apache.
Database: MySQL running locally or on a managed host.
Frontend (Next.js): Build and serve with next start or deploy via Docker.

For offline environments, you can maintain a **local MySQL replica** inside Proxmox, and configure automatic synchronization with the VPS database when internet access is restored. The project uses ESLint and Husky for code quality and Git hook automation.

Edit this pageorReport an issue

Introduction

This section provides an overview of how to get started with the Klinik Gunung Documentation System built using Laravel 12, Next.js, and TanStack Query.

Complete Server Migration Guide

Comprehensive guide for migrating Laravel applications with large databases to new VPS servers, including preparation, execution, verification, and troubleshooting steps.