admin/sides
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README for SIDES project

Browse Source 
Replace template boilerplate with project description, quick start,
documentation index linking to docs/, stack summary, and project structure.
This commit is contained in:
root
2026-05-21 03:39:23 +08:00
parent 6863f39a24
commit e22644b32b
1 changed files with 54 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@@ -1,65 +1,64 @@
# Laravel using PostgreSQL in Docker # SIDES
<p align="center"> **Sabo Integrated Debris Flow Monitoring and Early Warning System**
<img src="./docker/image/laravel+docker.png" alt="docker+laravel">
</p>
## Introduction Flood and debris flow early warning system for Sungai Kupang, Malaysia. Operated under Jabatan Pengairan dan Saliran (JPS) — the Malaysian Department of Irrigation and Drainage.
Build a simple laravel application development environment with docker compose. Monitors rainfall, water levels, and siren activations at remote telemetry stations with a real-time web dashboard, interactive map, and push notifications.
## Quick Start
## Requirement
- Docker ^19.*
## Installation
1. Git clone & move to working directory
2. Settings your credentials, copy `.env.example` to `.env`
3. Execute the following command for create application
```bash ```bash
$ make create-project git clone <repo-url> && cd tckdev
cp .env.example .env # Configure credentials
cp src/.env.example src/.env # Configure Laravel
docker compose up -d --build
``` ```
4. Next, set environment DB for app laravel in `src/.env` variable : The app container automatically runs migrations, seeding, and asset building on first start. Access the dashboard at `http://localhost`.
## Documentation
Full documentation is in [`docs/`](docs/):
| Document | Description |
|----------|-------------|
| [01-OVERVIEW](docs/01-OVERVIEW.md) | Project overview, purpose, and high-level architecture |
| [02-ARCHITECTURE](docs/02-ARCHITECTURE.md) | Technology stack, container layout, request flow, middleware |
| [03-DEPLOYMENT](docs/03-DEPLOYMENT.md) | Docker Compose deployment, reverse proxy setup, production checklist |
| [04-DATA-PIPELINE](docs/04-DATA-PIPELINE.md) | Python autoscript, FTP ingestion, CSV parsing, alert triggers |
| [05-FEATURES](docs/05-FEATURES.md) | User-facing features, routes, and access control |
| [06-DATABASE](docs/06-DATABASE.md) | PostgreSQL schema, tables, relationships |
| [07-API](docs/07-API.md) | REST API reference for station data and push notifications |
| [08-CONFIGURATION](docs/08-CONFIGURATION.md) | Environment variables, Docker Compose config, Nginx, Laravel |
## Stack
- **Backend**: Laravel 12 (PHP 8.2-FPM)
- **Database**: PostgreSQL 16
- **Frontend**: Blade + Alpine.js + Tailwind CSS + Leaflet.js
- **Push Notifications**: Firebase Cloud Messaging
- **Data Pipeline**: Python (psycopg2, ftplib)
- **Deployment**: Docker Compose (nginx, php-fpm, postgres, pgadmin)
## Project Structure
``` ```
DB_CONNECTION=pgsql tckdev/
DB_HOST=postgres ├── src/ # Laravel application (bind-mounted into containers)
DB_PORT=5432 │ ├── app/Http/Controllers/
DB_DATABASE=<your_db_name> // same in root .env variable POSTGRES_DB │ ├── database/migrations/
DB_USERNAME=<your_db_user> // same in root .env variable POSTGRES_USER │ ├── routes/
DB_PASSWORD=<your_db_password> // same in root .env variable POSTGRES_PASSWORD │ ├── resources/views/
│ └── .env
├── autoscript/
│ └── sidesdecode.py # Python data ingestion pipeline
├── docker/
│ ├── nginx/default.conf
│ └── entrypoint.sh
├── docs/ # Documentation wiki
├── docker-compose.yml
├── Dockerfile
├── .env # Docker-level credentials
└── .env.example
``` ```
5. show application in [http://localhost:85](http://localhost:85)
<img src="./docker/image/app.png" alt="app+laravel">
1. show adminer in [http://localhost:8080](http://localhost:8080)
<img src="./docker/image/adminer.png" alt="adminer">
7. show pgadmin in [http://localhost:5050](http://localhost:5050)
<img src="./docker/image/pgadmin.png" alt="pgadmin">
8. list execute command in [Makefile](Makefile).
## Container details :
- ``app`` use image:
- [php](https://hub.docker.com/_/php):8.2-fpm
- [composer](https://hub.docker.com/_/composer):2.3
- [npm](https://deb.nodesource.com/setup_lts.x):latest
- ``web`` use image:
- [nginx](https://hub.docker.com/_/nginx):stable-alpine
- ``db`` use image:
- [postgres](https://hub.docker.com/_/postgres):15
- ``adminer`` use image:
- [adminer](https://hub.docker.com/_/adminer):latest
*Optional*
- ``pgadmin`` use image:
- [pgadmin](https://hub.docker.com/_/pgadmin):latest