README: complete installation guide for fresh and OEM deployments
This commit is contained in:
parent
1be7b51812
commit
f54cabd7f8
396
README.md
396
README.md
|
|
@ -1,75 +1,371 @@
|
|||
# CodeIgniter 4 Application Starter
|
||||
# HMS — Hospital Management System (CI4)
|
||||
|
||||
## Project Documents
|
||||
**Framework:** CodeIgniter 4.7 · **PHP:** 8.2+ · **DB:** MySQL 5.7+ / MariaDB 10.4+
|
||||
|
||||
- Complete software help guide: docs/HOSPITAL_STOCK_HELP.md
|
||||
- Software use license: SOFTWARE_USE_LICENSE.md
|
||||
- Open-source notice: OPEN_SOURCE_NOTICE.md
|
||||
A full-featured hospital management system covering OPD, IPD, Billing, Pathology Lab,
|
||||
Radiology, Finance, Pharmacy Stock, and more.
|
||||
|
||||
## What is CodeIgniter?
|
||||
---
|
||||
|
||||
CodeIgniter is a PHP full-stack web framework that is light, fast, flexible and secure.
|
||||
More information can be found at the [official site](https://codeigniter.com).
|
||||
## Table of Contents
|
||||
|
||||
This repository holds a composer-installable app starter.
|
||||
It has been built from the
|
||||
[development repository](https://github.com/codeigniter4/CodeIgniter4).
|
||||
1. [Server Requirements](#1-server-requirements)
|
||||
2. [Fresh Installation](#2-fresh-installation)
|
||||
3. [Web Server Configuration](#3-web-server-configuration)
|
||||
4. [Environment Configuration](#4-environment-configuration)
|
||||
5. [Database Setup](#5-database-setup)
|
||||
6. [Seed Master Data](#6-seed-master-data)
|
||||
7. [File Permissions](#7-file-permissions)
|
||||
8. [First Login](#8-first-login)
|
||||
9. [Updating an Existing Installation](#9-updating-an-existing-installation)
|
||||
10. [OEM / Multi-Site Deployment](#10-oem--multi-site-deployment)
|
||||
11. [Lab Template Workflow](#11-lab-template-workflow)
|
||||
12. [Useful Spark Commands](#12-useful-spark-commands)
|
||||
13. [Project Documents](#13-project-documents)
|
||||
|
||||
More information about the plans for version 4 can be found in [CodeIgniter 4](https://forum.codeigniter.com/forumdisplay.php?fid=28) on the forums.
|
||||
---
|
||||
|
||||
You can read the [user guide](https://codeigniter.com/user_guide/)
|
||||
corresponding to the latest version of the framework.
|
||||
## 1. Server Requirements
|
||||
|
||||
## Installation & updates
|
||||
| Requirement | Minimum | Recommended |
|
||||
|---|---|---|
|
||||
| PHP | 8.2 | 8.3 |
|
||||
| MySQL | 5.7 | 8.0+ |
|
||||
| MariaDB (alternative) | 10.4 | 10.11+ |
|
||||
| Web server | Apache 2.4 / Nginx | Apache with `mod_rewrite` |
|
||||
| Composer | 2.x | latest |
|
||||
|
||||
`composer create-project codeigniter4/appstarter` then `composer update` whenever
|
||||
there is a new release of the framework.
|
||||
**Required PHP extensions:**
|
||||
|
||||
When updating, check the release notes to see if there are any changes you might need to apply
|
||||
to your `app` folder. The affected files can be copied or merged from
|
||||
`vendor/codeigniter4/framework/app`.
|
||||
```
|
||||
intl mbstring mysqlnd json curl gd zip fileinfo xml
|
||||
```
|
||||
|
||||
## Setup
|
||||
**Recommended `php.ini` settings:**
|
||||
|
||||
Copy `env` to `.env` and tailor for your app, specifically the baseURL
|
||||
and any database settings.
|
||||
```ini
|
||||
memory_limit = 256M
|
||||
upload_max_filesize = 20M
|
||||
post_max_size = 25M
|
||||
max_execution_time = 120
|
||||
```
|
||||
|
||||
## Important Change with index.php
|
||||
---
|
||||
|
||||
`index.php` is no longer in the root of the project! It has been moved inside the *public* folder,
|
||||
for better security and separation of components.
|
||||
## 2. Fresh Installation
|
||||
|
||||
This means that you should configure your web server to "point" to your project's *public* folder, and
|
||||
not to the project root. A better practice would be to configure a virtual host to point there. A poor practice would be to point your web server to the project root and expect to enter *public/...*, as the rest of your logic and the
|
||||
framework are exposed.
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/infodevsofttech-admin/devsofttech_hms_ci4.git hms
|
||||
cd hms
|
||||
|
||||
**Please** read the user guide for a better explanation of how CI4 works!
|
||||
# 2. Install PHP dependencies
|
||||
composer install --no-dev --optimize-autoloader
|
||||
|
||||
## Repository Management
|
||||
# 3. Copy environment file
|
||||
cp env .env
|
||||
|
||||
We use GitHub issues, in our main repository, to track **BUGS** and to track approved **DEVELOPMENT** work packages.
|
||||
We use our [forum](http://forum.codeigniter.com) to provide SUPPORT and to discuss
|
||||
FEATURE REQUESTS.
|
||||
# 4. Edit .env (see Section 4)
|
||||
nano .env
|
||||
|
||||
This repository is a "distribution" one, built by our release preparation script.
|
||||
Problems with it can be raised on our forum, or as issues in the main repository.
|
||||
# 5. Run database migrations
|
||||
php spark migrate
|
||||
|
||||
## Server Requirements
|
||||
# 6. Seed all master data (see Section 6)
|
||||
php spark db:seed LabTemplateSeeder
|
||||
php spark db:seed InvestigationMasterSeeder
|
||||
php spark db:seed ClinicalTemplateWorkspaceSeeder
|
||||
php spark db:seed ComplaintsMasterSeeder
|
||||
```
|
||||
|
||||
PHP version 8.2 or higher is required, with the following extensions installed:
|
||||
> **Windows (WAMP/Laragon):** use `php spark` from the project root in Command Prompt or PowerShell.
|
||||
|
||||
- [intl](http://php.net/manual/en/intl.requirements.php)
|
||||
- [mbstring](http://php.net/manual/en/mbstring.installation.php)
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
> - The end of life date for PHP 7.4 was November 28, 2022.
|
||||
> - The end of life date for PHP 8.0 was November 26, 2023.
|
||||
> - The end of life date for PHP 8.1 was December 31, 2025.
|
||||
> - If you are still using below PHP 8.2, you should upgrade immediately.
|
||||
> - The end of life date for PHP 8.2 will be December 31, 2026.
|
||||
## 3. Web Server Configuration
|
||||
|
||||
Additionally, make sure that the following extensions are enabled in your PHP:
|
||||
### Apache
|
||||
|
||||
- json (enabled by default - don't turn it off)
|
||||
- [mysqlnd](http://php.net/manual/en/mysqlnd.install.php) if you plan to use MySQL
|
||||
- [libcurl](http://php.net/manual/en/curl.requirements.php) if you plan to use the HTTP\CURLRequest library
|
||||
Point your virtual host `DocumentRoot` to the **`public/`** folder — **not** the project root.
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName hms.yourhospital.in
|
||||
DocumentRoot /var/www/hms/public
|
||||
|
||||
<Directory /var/www/hms/public>
|
||||
Options -Indexes +FollowSymLinks
|
||||
AllowOverride All
|
||||
Require all granted
|
||||
</Directory>
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
`mod_rewrite` must be enabled:
|
||||
|
||||
```bash
|
||||
sudo a2enmod rewrite
|
||||
sudo systemctl restart apache2
|
||||
```
|
||||
|
||||
### Nginx
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name hms.yourhospital.in;
|
||||
root /var/www/hms/public;
|
||||
index index.php index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.php$is_args$args;
|
||||
}
|
||||
|
||||
location ~ \.php$ {
|
||||
include snippets/fastcgi-php.conf;
|
||||
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Environment Configuration
|
||||
|
||||
Edit `.env` (copied from `env` in step 3):
|
||||
|
||||
```dotenv
|
||||
#--------------------------------------------------------------------
|
||||
# ENVIRONMENT
|
||||
#--------------------------------------------------------------------
|
||||
CI_ENVIRONMENT = production # use "development" while installing
|
||||
|
||||
#--------------------------------------------------------------------
|
||||
# APP
|
||||
#--------------------------------------------------------------------
|
||||
app.baseURL = 'https://hms.yourhospital.in/'
|
||||
app.appTimezone = 'Asia/Kolkata' # adjust to your timezone
|
||||
|
||||
#--------------------------------------------------------------------
|
||||
# DATABASE
|
||||
#--------------------------------------------------------------------
|
||||
database.default.hostname = localhost
|
||||
database.default.database = hms_ci4
|
||||
database.default.username = hms_user
|
||||
database.default.password = StrongPassword123
|
||||
database.default.DBDriver = MySQLi
|
||||
database.default.port = 3306
|
||||
|
||||
#--------------------------------------------------------------------
|
||||
# ENCRYPTION KEY (generate once: php spark key:generate)
|
||||
#--------------------------------------------------------------------
|
||||
# encryption.key = hex2bin:...
|
||||
```
|
||||
|
||||
Generate encryption key:
|
||||
|
||||
```bash
|
||||
php spark key:generate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Database Setup
|
||||
|
||||
### Create database and user (MySQL)
|
||||
|
||||
```sql
|
||||
CREATE DATABASE hms_ci4 CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||||
CREATE USER 'hms_user'@'localhost' IDENTIFIED BY 'StrongPassword123';
|
||||
GRANT ALL PRIVILEGES ON hms_ci4.* TO 'hms_user'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
### Run migrations
|
||||
|
||||
Migrations create all application tables (billing, IPD, finance, stock, etc.):
|
||||
|
||||
```bash
|
||||
php spark migrate
|
||||
```
|
||||
|
||||
> The legacy lab/radiology tables (`lab_repo`, `lab_rgroups`, `lab_tests`, etc.) are
|
||||
> **not** managed by migrations — they are created automatically by the seeders in Step 6.
|
||||
|
||||
---
|
||||
|
||||
## 6. Seed Master Data
|
||||
|
||||
Run in this order:
|
||||
|
||||
```bash
|
||||
# Lab & radiology report templates (creates tables too)
|
||||
php spark db:seed LabTemplateSeeder
|
||||
|
||||
# Investigation/test master list for OPD order panel
|
||||
php spark db:seed InvestigationMasterSeeder
|
||||
|
||||
# OPD clinical workspace templates (complaint, examination, advice templates)
|
||||
php spark db:seed ClinicalTemplateWorkspaceSeeder
|
||||
|
||||
# Complaint master list
|
||||
php spark db:seed ComplaintsMasterSeeder
|
||||
```
|
||||
|
||||
All seeders are **idempotent** — safe to re-run; they use `INSERT IGNORE`.
|
||||
|
||||
### Optional: OPD demo data
|
||||
|
||||
```bash
|
||||
# Loads all OPD master data at once (calls Clinical + Investigation seeders)
|
||||
php spark db:seed OpdDemoMasterSeeder
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. File Permissions
|
||||
|
||||
The web server user (`www-data` on Ubuntu, `apache` on CentOS) must have write access
|
||||
to these directories:
|
||||
|
||||
```bash
|
||||
# Linux / CentOS / Ubuntu
|
||||
chmod -R 775 writable/
|
||||
chmod -R 775 public/assets/uploads/
|
||||
chmod -R 775 public/uploads/
|
||||
|
||||
chown -R www-data:www-data writable/ public/assets/uploads/ public/uploads/
|
||||
```
|
||||
|
||||
> On Windows (WAMP/Laragon) no permission changes are needed.
|
||||
|
||||
---
|
||||
|
||||
## 8. First Login
|
||||
|
||||
1. Open `https://hms.yourhospital.in/` in your browser.
|
||||
2. Register the **first user** — this account automatically becomes `superadmin`.
|
||||
3. Go to **Setup → Hospital Info** and enter your hospital name, address, and logo.
|
||||
4. Go to **Setup → Users** to create additional staff accounts and assign roles.
|
||||
|
||||
**Available roles:**
|
||||
|
||||
| Role | Access |
|
||||
|---|---|
|
||||
| `superadmin` | Full system access |
|
||||
| `admin` | Day-to-day administration |
|
||||
| `stock_manager` | Stock masters, approvals, procurement |
|
||||
| `storekeeper` | Item issuance and stock receiving |
|
||||
| `department_head` | Department stock indents |
|
||||
| `user` | General / reception access |
|
||||
|
||||
---
|
||||
|
||||
## 9. Updating an Existing Installation
|
||||
|
||||
```bash
|
||||
# Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# Install any new Composer packages
|
||||
composer install --no-dev --optimize-autoloader
|
||||
|
||||
# Run any new migrations
|
||||
php spark migrate
|
||||
|
||||
# If lab templates were updated by the developer, re-seed them
|
||||
php spark db:seed LabTemplateSeeder
|
||||
```
|
||||
|
||||
> Always run `php spark migrate` after every `git pull` — it is safe to run on an
|
||||
> already-migrated database (it skips already-applied migrations).
|
||||
|
||||
---
|
||||
|
||||
## 10. OEM / Multi-Site Deployment
|
||||
|
||||
For deploying to multiple hospital sites from one codebase:
|
||||
|
||||
1. Follow Steps 2–8 on each server.
|
||||
2. Each site gets its own `.env` with its own database credentials and `baseURL`.
|
||||
3. When the main developer adds new features/templates, sites update with:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
php spark migrate
|
||||
php spark db:seed LabTemplateSeeder # if lab templates were exported
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Lab Template Workflow
|
||||
|
||||
Lab and radiology report templates are stored in the database. When templates are
|
||||
added or edited via the admin UI, the developer exports them so all OEM sites can
|
||||
receive them via git:
|
||||
|
||||
**On the main/development server (after editing templates in UI):**
|
||||
|
||||
```bash
|
||||
php spark oem:export-lab-templates
|
||||
git add app/Database/Seeds/LabOemData/
|
||||
git commit -m "OEM: update lab template seed data"
|
||||
git push
|
||||
```
|
||||
|
||||
**On each remote/OEM server:**
|
||||
|
||||
```bash
|
||||
git pull
|
||||
php spark db:seed LabTemplateSeeder
|
||||
```
|
||||
|
||||
Tables covered by this workflow:
|
||||
|
||||
| Table | Description |
|
||||
|---|---|
|
||||
| `lab_rgroups` | Report group names (Haematology, BioChemistry …) |
|
||||
| `hc_items` (itype 5,6) | Billing charge items linked to lab reports |
|
||||
| `lab_repo` | Pathology report templates (with HTML layout) |
|
||||
| `lab_tests` | Individual test / parameter definitions |
|
||||
| `lab_tests_option` | Dropdown options for test parameters |
|
||||
| `lab_repotests` | Report ↔ test assignments and sort order |
|
||||
| `radiology_ultrasound_template` | US / MRI / CT / Xray / Echo templates |
|
||||
|
||||
---
|
||||
|
||||
## 12. Useful Spark Commands
|
||||
|
||||
```bash
|
||||
# Show all available commands
|
||||
php spark list
|
||||
|
||||
# Run pending migrations
|
||||
php spark migrate
|
||||
|
||||
# Rollback last migration batch
|
||||
php spark migrate:rollback
|
||||
|
||||
# Seed a specific seeder
|
||||
php spark db:seed LabTemplateSeeder
|
||||
|
||||
# Export current lab templates to git-trackable SQL files
|
||||
php spark oem:export-lab-templates
|
||||
|
||||
# Import Ayushman package master from Excel/CSV
|
||||
php spark ayushman:import
|
||||
|
||||
# Generate a new encryption key (first install only)
|
||||
php spark key:generate
|
||||
|
||||
# Built-in development server (local only)
|
||||
php spark serve
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. Project Documents
|
||||
|
||||
- Full software help guide: [docs/HOSPITAL_STOCK_HELP.md](docs/HOSPITAL_STOCK_HELP.md)
|
||||
- Software use license: [SOFTWARE_USE_LICENSE.md](SOFTWARE_USE_LICENSE.md)
|
||||
- Open-source notice: [OPEN_SOURCE_NOTICE.md](OPEN_SOURCE_NOTICE.md)
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user