fix(docs): document evidence file upload issue and VPS setup
Files not displaying after upload due to missing EVIDENCE_DIR and EVIDENCE_URL_SECRET environment variables. Uploads fail silently when env vars unset, files never inserted into database. Add bug fix documentation with root cause analysis and VPS deployment instructions. Update .env.local.example to emphasize these vars are required for file uploads to work. See docs/BUG_FIX_evidence_display.md for details.
This commit is contained in:
+2
-1
@@ -10,7 +10,8 @@ APP_URL=http://localhost:3000
|
||||
NEXT_PUBLIC_SITE_URL=http://localhost:3000
|
||||
CRON_SECRET=<generate with: openssl rand -hex 32>
|
||||
|
||||
# Evidence storage (local filesystem)
|
||||
# Evidence storage (local filesystem) — REQUIRED for file uploads
|
||||
# Without these, file uploads fail silently and no files appear in incidents
|
||||
EVIDENCE_DIR=/tmp/ims-evidence
|
||||
EVIDENCE_URL_SECRET=<generate with: openssl rand -hex 32>
|
||||
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Bug Fix: Files Not Displaying After Upload
|
||||
|
||||
## Issue
|
||||
After users report incidents and upload images/videos/documents, the files don't display in the incident detail page under the evidence section.
|
||||
|
||||
## Root Cause
|
||||
The `uploadEvidenceFile()` function in `lib/storage/evidence.ts` requires two environment variables:
|
||||
- `EVIDENCE_DIR` — filesystem path to store evidence files
|
||||
- `EVIDENCE_URL_SECRET` — HMAC secret for signing secure file URLs
|
||||
|
||||
When these variables are missing:
|
||||
1. File upload API receives files from client
|
||||
2. Calls `uploadEvidenceFile()` at `/api/incidents/route.ts:154`
|
||||
3. Function throws error (e.g., "EVIDENCE_DIR env var not set")
|
||||
4. Error caught silently at line 164: `catch (err) { console.error(...) }`
|
||||
5. Evidence not inserted into database
|
||||
6. Display shows empty file list
|
||||
|
||||
## Related Changes
|
||||
- Commit e5f74c3 (2026-07-23): Switched from Supabase storage to local filesystem with HMAC-signed URLs
|
||||
- This change requires new env vars that weren't documented in deployment checklist
|
||||
|
||||
## Fix
|
||||
Set environment variables before starting the app:
|
||||
|
||||
```bash
|
||||
# Generate secret
|
||||
EVIDENCE_URL_SECRET=$(openssl rand -hex 32)
|
||||
|
||||
# Export or add to .env file
|
||||
export EVIDENCE_DIR=/var/lib/ims-evidence
|
||||
export EVIDENCE_URL_SECRET=$EVIDENCE_URL_SECRET
|
||||
|
||||
# Create directory with proper permissions
|
||||
mkdir -p $EVIDENCE_DIR
|
||||
chmod 755 $EVIDENCE_DIR
|
||||
```
|
||||
|
||||
For VPS systemd service, add to `/etc/systemd/system/ims.service`:
|
||||
```ini
|
||||
Environment="EVIDENCE_DIR=/var/lib/ims-evidence"
|
||||
Environment="EVIDENCE_URL_SECRET=<generated-secret>"
|
||||
```
|
||||
|
||||
Then reload and restart:
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart ims
|
||||
```
|
||||
|
||||
## Testing
|
||||
1. Report incident with file upload
|
||||
2. Check `/var/lib/ims-evidence` directory—files should appear as `<user-id>/<incident-id>/report/<timestamp>-<random>.<ext>`
|
||||
3. Verify via HSE incident detail page—files should display in gallery
|
||||
4. Check database: `SELECT COUNT(*) FROM evidence_files WHERE deleted = false`
|
||||
Reference in New Issue
Block a user