116 lines
7.1 KiB
Markdown
116 lines
7.1 KiB
Markdown
# Product Operation Guide
|
||
|
||
| Document field | Value |
|
||
|---|---|
|
||
| Document | Product Operation Guide |
|
||
| Project | BRN WMS |
|
||
| Project code | 200-WMS-26-001-00 |
|
||
| Title | Operating Manual Document for System Administrators |
|
||
| Project period | 05/01/26–24/08/26 |
|
||
| Release | 17/08/26 V1.0 |
|
||
| Closure status date | 24/08/26 |
|
||
| Standard | ISO/IEC 29110 Basic Profile |
|
||
| Organizer | Apirach Supattaratpateep (Project Manager), Noppong Chareunsook (System Analyst), Thanakorn Sathitwitayakul (Developer) |
|
||
| Status | Final — reflects the implemented deployment mechanisms at project baseline |
|
||
|
||
## Objective
|
||
|
||
Guide a System Administrator through installing, configuring, operating, monitoring, backing up, and recovering BRN WMS, so operation is consistent, correct, and quickly recoverable.
|
||
|
||
## 1. Deployment options
|
||
|
||
BRN WMS supports two deployment paths, evidenced in the repository:
|
||
|
||
| Path | Mechanism | Reference |
|
||
|---|---|---|
|
||
| Manual installation | One-shot database setup script | `setup.php` |
|
||
| Containerized deployment | Docker Compose stack: php-apache, mariadb, node/pm2 | `docker-compose.yml`, `docker/` |
|
||
|
||
## 2. Containerized installation (recommended)
|
||
|
||
1. Copy `.env.example` to `.env`, or run the interactive generator: `docker/init-env.sh` (prompts for DB password, public host, `EMIT_SECRET`, and SMTP credentials; auto-generates secrets left blank).
|
||
2. Run `docker compose up -d --build`. This brings up:
|
||
- `php-apache` — the PHP 8+ web application (`docker/php/`), with `app/config.php` generated from `.env` at container start by `docker/php/entrypoint.sh` — never baked into the image or committed.
|
||
- `mariadb` — the database service, initialized from `docker/mariadb/init-wms2.sql` and `setup.php`.
|
||
- `node` — the Node.js real-time/scheduler service (`docker/node/`), managed by pm2 (`nodejs/ecosystem.config.js`).
|
||
3. Confirm the application is reachable at the configured public host and that the Node.js service is running (Section 5).
|
||
|
||
## 3. Manual installation
|
||
|
||
1. Provision a PHP 8+ / MariaDB / Node.js environment.
|
||
2. Configure `app/config.php` (database credentials for the `wms` and `wms2` databases, `NODE_PUBLIC_URL`, `NODE_EMIT_URL`, `NODE_EMIT_SECRET`, SMTP).
|
||
3. Run `setup.php` once to create the database schema (see Software Requirements Specification, SR08, for the full table list).
|
||
4. Start the Node.js services (`nodejs/server.js`, `nodejs/scheduler.js`), for example under pm2 using `nodejs/ecosystem.config.js`.
|
||
|
||
## 4. Configuration
|
||
|
||
| Item | Location | Notes |
|
||
|---|---|---|
|
||
| Application configuration | `app/config.php` | Generated at deploy time; never committed |
|
||
| Environment secrets | `.env` (Docker) or shell/deployment environment (manual) | Excluded via `.gitignore` |
|
||
| Company-level settings | In-application (`app/setting/`) | Per-company profile, SMTP, system settings |
|
||
| Time zone | `$time_zone` in `app/config.php` | Fixed to `Asia/Bangkok` |
|
||
|
||
## 5. Monitoring
|
||
|
||
- **Web application**: confirm the PHP application responds and users can authenticate.
|
||
- **Database**: confirm both `wms` and `wms2` databases are reachable.
|
||
- **Node.js service**: confirm `server.js` (Socket.IO) and `scheduler.js` (scheduled jobs) are running under pm2; review `nodejs/logs/` (`socket.log`, `scheduler.log`, `scheduler-error.log`) for errors.
|
||
- **Scheduled jobs**: confirm stock/GL aggregate maintenance and low-stock/overdue-invoice alert jobs are completing on schedule without duplication.
|
||
|
||
The production monitoring control performs an automated health check every five minutes. Two consecutive failures trigger an email to the System Administrator. pm2 automatic restart is the first recovery response. If service is not restored within 30 minutes, the System Administrator escalates to the Project Manager; the Project Sponsor is notified when an outage exceeds two hours or materially affects business operations. The System Administrator reviews the affected process state and logs, restores service, confirms application and scheduled-job health, and records the incident through the applicable operational support channel.
|
||
|
||
## 6. Backup and recovery
|
||
|
||
| Item | Mechanism | Status |
|
||
|---|---|---|
|
||
| Source code and configuration templates | Git, two remotes (`origin`, `backup`) | See Project Repository / Project Repository (Backup), work products 9–10 |
|
||
| Database (`wms`, `wms2`) | Automated database export at 02:00 ICT daily to company-controlled cloud storage | Daily backups retained 30 days; month-end backups retained 12 months; access restricted to the System Administrator and authorized management |
|
||
| SDLC documents | External PDF export package | See Project Repository (Backup), Section 3 |
|
||
|
||
### 6.1 Database restoration procedure
|
||
|
||
1. The System Administrator selects the required backup from company-controlled cloud storage and confirms its date and integrity.
|
||
2. The backup is restored into a non-production MariaDB environment before any production recovery is attempted.
|
||
3. Connectivity to `wms` and `wms2` and representative master-data and transaction records are verified.
|
||
4. For a production recovery, the System Administrator records the recovery point, pauses affected services, restores the verified backup, restarts the application and Node.js services, and performs the health checks in Section 5.
|
||
5. Failed or missing scheduled backups are investigated and rerun by the System Administrator.
|
||
|
||
A sample backup dated 22/08/26 was restored successfully to a non-production environment on 23/08/26. Database accessibility and representative records were verified, and the Project Manager reviewed completion during closure.
|
||
|
||
## 7. Operational-control closure
|
||
|
||
| ID | Control | Owner | Status | Closure evidence |
|
||
|---|---|---|---|---|
|
||
| OP-001 | Automated database backup and restoration control for `wms` and `wms2`. | System Administrator | **Closed 23/08/26** | Section 6 records the 02:00 ICT schedule, controlled cloud destination, retention, operator, recovery steps, and successful non-production restoration test. |
|
||
| OP-002 | Monitoring and failure alerting beyond local log review. | System Administrator | **Closed 23/08/26** | Section 5 records the five-minute health check, two-failure email trigger, recipients, escalation time, and recovery response. |
|
||
|
||
## 8. User and access management
|
||
|
||
An Owner/Admin manages users, roles (Owner/Admin/Staff/Viewer), and application-access flags from Settings (`app/setting/`). Role changes take effect on the user's next authenticated action; concurrent-session policy blocks a second simultaneous login on the same account.
|
||
|
||
## Approval
|
||
|
||
### Prepared by
|
||
|
||
Name: Thanakorn Sathitwitayakul
|
||
Role: Developer
|
||
Signature: ______________________________________________
|
||
Date: ___________________________________________________
|
||
|
||
### Reviewed by
|
||
|
||
Name: Apirach Supattaratpateep
|
||
Role: Project Manager
|
||
Signature: ______________________________________________
|
||
Date: ___________________________________________________
|
||
|
||
### Reviewed and authorized by
|
||
|
||
Name: Seri Viriyasakultorn
|
||
Project roles: Project Sponsor / Customer Representative / Authorized Approver
|
||
Position: Managing Director
|
||
Company: B.R.N. Enterprise Co., Ltd.
|
||
Signature: ______________________________________________
|
||
Date: ___________________________________________________
|