# Canaccom Deployment Guide

## Summary

Production deployment is Git-based.

The supported flow is:

1. Make and test changes locally.
2. Commit to `main`.
3. Push to GitHub.
4. Run `deploy.bat prod` on Windows or `./sync-to-server.sh prod` on Linux/macOS.
5. The deploy command uploads `scripts/prod-remote-deploy.sh` to the server and runs it.
6. The server creates a backup, updates the full repo checkout, runs `composer install --no-dev`, and runs a smoke check.

Do not deploy by copying selected files anymore.

## Repo And Environment Rules

- Repo root: `d:\Canaccom`
- Remote: `https://github.com/Sportzone99/canaccom.git`
- Production branch: `main`
- Production code path: `/var/www/html/canaccom`
- Backup path: `/var/www/backups/canaccom`
- Production `.env` stays on the server only
- Local development uses `.env.dev`, which `start-dev.ps1` copies to `.env`

Tracked example env files:

- `.env.example`
- `.env.dev.example`
- `.env.prod.example`

Never commit:

- `.env`
- `.env.dev`
- `.env.prod`
- PEM keys
- runtime uploads/logs/backups

## Required Files

- `deploy-config.bat`
- `deploy.bat`
- `sync-to-server.sh`
- `server-config.sh`
- `scripts/prod-remote-deploy.sh`
- `.gitignore`
- `.rsync-exclude`

## First-Time Server Setup

If the server has never used the Git-based flow:

1. Ensure the server can reach GitHub.
2. Ensure `git`, `php`, and `composer` are installed on the server.
3. Put the production `.env` in `/var/www/html/canaccom/.env` after the first clone, or preserve the existing `.env` if migrating an old non-Git site directory.
4. Confirm the SSH key referenced by `deploy-config.bat` / `sync-to-server.sh` can connect to the server.

Optional helper commands:

```bash
./server-config.sh setup
./server-config.sh test
./server-config.sh info
```

## Standard Deployment

### Windows

```bat
deploy.bat prod
```

### Linux / macOS

```bash
./sync-to-server.sh prod
```

Both commands do the same thing:

1. Refuse to deploy if the working tree is dirty.
2. Refuse to deploy if you are not on `main`.
3. Push `main` to `origin`.
4. Copy `scripts/prod-remote-deploy.sh` to the server.
5. Run the remote deploy helper with the configured repo URL, branch, backup path, and expected env.

## What The Remote Deploy Does

`scripts/prod-remote-deploy.sh` runs on the server and:

1. Creates a backup in `/var/www/backups/canaccom`
2. If the app directory is already a Git checkout:
   - `git fetch origin`
   - `git checkout main`
   - `git reset --hard origin/main`
3. If the app directory is a legacy non-Git folder:
   - create a migration backup
   - preserve `.env` plus common runtime directories
   - replace the directory with a fresh clone
4. Recreate runtime directories such as `uploads`, `files`, `logs`, and `images/profiles`
5. Run `composer install --no-dev --prefer-dist --optimize-autoloader`
6. Run `php scripts/smoke-check.php --expect-env=production`

## Smoke Checks

Local development:

```bash
php scripts/smoke-check.php
```

Production expectation:

```bash
php scripts/smoke-check.php --expect-env=production
```

The script now exits non-zero on failure so deploy scripts can stop on a bad release.

## Emergency / Manual Full Sync

The primary deployment model is Git-based.

`.rsync-exclude` is still maintained for emergency/manual full-project syncs only. It excludes secrets and runtime-only directories, not source code required by the app.

## Troubleshooting

### Working tree is dirty

Commit or stash local changes first:

```bash
git status --short
```

### Wrong branch

Production deploy expects `main`:

```bash
git checkout main
```

### Server cannot clone or fetch

Check GitHub access from the server:

```bash
ssh ec2-user@52.60.53.55
git ls-remote https://github.com/Sportzone99/canaccom.git HEAD
```

### Composer missing on server

Install Composer or vendor dependencies will not refresh during deploy.

### Smoke check fails

SSH to the server and run:

```bash
cd /var/www/html/canaccom
php scripts/smoke-check.php --expect-env=production
```

Then verify:

- `.env` exists
- DB credentials are correct
- PHP extensions are installed

## Rollback

Each deployment creates a backup tarball in `/var/www/backups/canaccom`.

To inspect backups:

```bash
ssh ec2-user@52.60.53.55 "ls -lah /var/www/backups/canaccom"
```

If you need to roll back code, either:

1. Redeploy an older Git commit by checking it out locally, pushing it, and redeploying.
2. Restore a backup tarball on the server if the checkout itself is damaged.