From aac19f89d378f993c2d6b913a5faada8afcb0c97 Mon Sep 17 00:00:00 2001
From: khantey long <khanteylong@gmail.com>
Date: Wed, 17 Jun 2026 16:26:07 +0700
Subject: [PATCH] Initialize README with project setup and commands

Added detailed setup instructions and project structure for NRML Dashboard.
---
 README.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ced7e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,180 @@
+# NRML Dashboard
+
+Laravel-based dashboard application running with Docker, Nginx, MySQL, and phpMyAdmin.
+
+## Requirements
+
+* Docker Desktop
+* Docker Compose
+* Git
+
+## Project Structure
+
+```text
+nrml_dashboard/
+├── dashboard/          # Laravel application
+├── docker/
+├── docker-compose.yml
+├── Dockerfile
+├── nginx.conf
+```
+
+## First-Time Setup
+
+### Clone Repository
+
+```bash
+git clone https://gitea.niph.org.kh/khantey/nrml_dashboard.git
+cd nrml_dashboard
+```
+
+### Create Environment File
+
+```bash
+cd dashboard
+cp .env.example .env
+```
+
+### Start Docker Containers
+
+```bash
+docker compose up -d --build
+```
+
+### Install PHP Dependencies
+
+```bash
+docker exec -it dashboard_app bash
+
+cd /var/www
+
+composer install
+```
+
+### Generate Application Key
+
+```bash
+php artisan key:generate
+```
+
+### Configure Database
+
+Update `.env`:
+
+```env
+DB_CONNECTION=mysql
+DB_HOST=mysql
+DB_PORT=3306
+DB_DATABASE=dashboard
+DB_USERNAME=laravel
+DB_PASSWORD=secret
+```
+
+### Run Migrations
+
+```bash
+php artisan migrate
+```
+
+### Frontend Assets
+
+Install dependencies:
+
+```bash
+cd dashboard
+npm install
+npm run build
+```
+
+## Application URLs
+
+### Dashboard
+
+http://localhost:8000
+
+### phpMyAdmin
+
+http://localhost:8083
+
+Credentials:
+
+```text
+Server: mysql
+Username: laravel
+Password: secret
+```
+
+## Storage Directories
+
+The following Laravel directories are committed to Git using placeholder `.gitignore` files:
+
+```text
+storage/framework/cache
+storage/framework/sessions
+storage/framework/testing
+storage/framework/views
+storage/logs
+```
+
+Do not remove these directories.
+
+## Common Commands
+
+Enter application container:
+
+```bash
+docker exec -it dashboard_app bash
+```
+
+Clear Laravel caches:
+
+```bash
+php artisan optimize:clear
+```
+
+View logs:
+
+```bash
+php artisan pail
+```
+
+Stop containers:
+
+```bash
+docker compose down
+```
+
+Restart containers:
+
+```bash
+docker compose restart
+```
+
+## Troubleshooting
+
+### "Please provide a valid cache path"
+
+Verify that the following directories exist:
+
+```text
+storage/framework/cache
+storage/framework/sessions
+storage/framework/testing
+storage/framework/views
+storage/logs
+```
+
+Then run:
+
+```bash
+php artisan optimize:clear
+```
+
+### Permission Issues
+
+Inside the container:
+
+```bash
+chown -R www-data:www-data storage bootstrap/cache
+chmod -R 775 storage bootstrap/cache
+```