# Samity360 Installation Guide

## 1. Server preparation

Use PHP 8+, MySQL 8+, Composer, HTTPS, and a web root pointed to the `public/` directory. Never expose the project root, `.env`, `storage/backups`, or SQL files directly through the web server.

Recommended PHP settings:

```ini
upload_max_filesize = 8M
post_max_size = 10M
memory_limit = 256M
session.cookie_httponly = 1
session.cookie_secure = 1
session.use_strict_mode = 1
date.timezone = Asia/Dhaka
```

## 2. Environment

Copy `.env.example` to `.env` and set the database credentials, deployment URL, session security, and timezone.

```dotenv
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.example
APP_TIMEZONE=Asia/Dhaka
SESSION_SECURE=true
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=samity360
DB_USERNAME=samity360_user
DB_PASSWORD=replace-with-strong-password
```

## 3. Dependencies

```bash
composer install --no-dev --optimize-autoloader
```

Composer adds QR rendering, PDF support, email support, and environment loading. The core application still has a fallback PSR-4 loader, but production installations should use Composer.

## 4. Database

Import the schema before demo data:

```bash
mysql -u root -p < database/schema.sql
mysql -u root -p samity360 < database/demo_data.sql
```

The schema uses InnoDB, utf8mb4, foreign keys, indexes, JSON columns, timestamps, and Bangladesh timezone assumptions.

## 5. Permissions

The web server user needs write access only to `storage/`.

```bash
chown -R www-data:www-data storage
chmod -R 775 storage
```

Create the public upload link if your deployment process did not retain it:

```bash
ln -s ../storage public/storage
```

For Nginx, deny PHP execution inside uploaded files. For Apache, add a matching rule or store uploads outside the public tree and serve them through an authorized controller.



## Company-scoped attachment folders

Samity360 stores each company's uploaded files in an isolated directory tree:

```text
public/storage/uploads/companies/
├── company-1/
│   ├── members/YYYY/MM/
│   ├── users/YYYY/MM/
│   ├── loans/
│   └── documents/
├── company-2/
│   ├── members/YYYY/MM/
│   ├── users/YYYY/MM/
│   ├── loans/
│   └── documents/
└── ...
```

The global Developer profile, which does not belong to a company, is stored under:

```text
public/storage/uploads/global/users/YYYY/MM/
```

New company folders are created automatically during company onboarding. Upload requests also create missing folders safely when needed.

After upgrading an existing installation to v1.1.7, run the one-time attachment migration from the project root:

```bash
php bin/migrate_company_attachments_v117.php
```

On Windows/XAMPP, double-click:

```text
migrate-company-attachments-v1.1.7.bat
```

The utility creates a separate folder for every existing company, moves legacy Member and User attachments, and updates their database paths. Back up the database and upload folders first.

## Local development server

Run from the project root:

```bash
php -S 127.0.0.1:8000 -t public public/index.php
```

The `public/index.php` front controller detects PHP's built-in server and returns existing static files directly. After upgrading from an earlier package, restart the PHP server and perform a hard refresh in the browser so old 404 responses are not reused.

## 6. Apache virtual host

```apache
<VirtualHost *:443>
    ServerName samity.example.com
    DocumentRoot /var/www/samity360/public

    <Directory /var/www/samity360/public>
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    # Configure certificates here.
</VirtualHost>
```

## 7. Nginx server block

```nginx
server {
    listen 443 ssl http2;
    server_name samity.example.com;
    root /var/www/samity360/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~* /storage/.*\.php$ { deny all; }
    location ~ /\.(env|git) { deny all; }
}
```

## 8. Cron jobs

Production deployments should add scheduled jobs for overdue calculation, fine assessment, due reminders, backup retention, and expired export cleanup. The included schema and services are ready for these jobs; provider and policy-specific scheduling must be configured for the deployment.

## 9. Backup and restore

```bash
php bin/backup.php
php bin/restore.php storage/backups/samity360-YYYYMMDD-HHMMSS.sql
```

Keep backups encrypted and outside the web root. Test restores regularly on an isolated database.

## Upgrade to v1.0.5

When upgrading an existing v1.0.4 database, replace the project files and import:

```text
database/migrations/20260626_v1.0.5_reports_language_settings.sql
```

XAMPP/phpMyAdmin method:

1. Select the `samity360` database.
2. Open **Import**.
3. Choose the migration SQL file.
4. Click **Import/Go**.
5. Restart the PHP development server and perform a hard refresh.

This migration adds the expanded language catalog and hides global Developer/platform settings from company Admin panels. It does not delete operational data.