# TaxCore Environment Configuration Summary

## The Problem We Solved

Initially, we tried adding TaxCore configuration to the main PHP `.env` file, which caused this error:

```
Warning: syntax error, unexpected '=' in /var/www/html/api/../.env on line 7
```

**Root Cause:** PHP's `parse_ini_file()` and Node.js environment handling are different systems that shouldn't share the same configuration file.

## The Solution: Separate Environment Files

### File Structure

```
/var/www/html/TAF/
├── .env                          # PHP application config (DB, ports, etc.)
├── .env.docker                   # Template for Docker TaxCore config
└── websocket-server/
    ├── .env                      # TaxCore config for manual runs
    ├── taxcore-service.js        # Node.js service
    └── ENVIRONMENT.md            # Environment documentation
```

### Configuration by Deployment Type

| Deployment | Config File | Used By | Format |
|------------|------------|---------|--------|
| **PHP App** | `/var/www/html/TAF/.env` | PHP via `parse_ini_file()` | PHP INI format |
| **Docker TaxCore** | `/var/www/html/TAF/.env` | Docker Compose → Container | Shell variables |
| **Manual TaxCore** | `websocket-server/.env` | Node.js via `process.env` | Shell variables |

## Current Setup

### 1. PHP Application Environment

**File:** `/var/www/html/TAF/.env`

```bash
PHP_PORT=8080
WS_PORT=9000
DB_HOST=postgres
DB_PORT=5432
REDIS_PORT=6379
```

**❌ Do NOT add TaxCore variables here!**

### 2. TaxCore Service (Docker)

**File:** `/var/www/html/TAF/.env` or `.env.docker`

When using Docker, create a separate `.env` at the project root:

```bash
cp .env.docker .env
# Edit .env with TaxCore settings
```

Docker Compose reads this file and passes variables to the `taxcore-service` container.

**Variables:**
```bash
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID/api
TAXCORE_PFX_FILE=YOUR-CERT.pfx
TAXCORE_PFX_PASSWORD=YOUR-PASSWORD
TAXCORE_PIN_JSON=YOUR-PIN
TAXCORE_DEBUG=true
```

### 3. TaxCore Service (Manual)

**File:** `websocket-server/.env`

For running the service manually outside Docker:

```bash
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID/api
TAXCORE_PFX_PATH=/var/www/html/TAF/FRCS_Certs_Install/YOUR-CERT.pfx
TAXCORE_PFX_PASSWORD=YOUR-PASSWORD
TAXCORE_PIN_JSON=YOUR-PIN
TAXCORE_DEBUG=true
TAXCORE_LOG_DIR=/usr/src/logs
```

**Start manually:**
```bash
cd websocket-server
export $(cat .env | xargs)
node taxcore-service.js &
```

## How It Works

### Docker Deployment

```
.env (root)
    ↓
docker-compose.yaml reads variables
    ↓
Sets environment in taxcore-service container
    ↓
Node.js reads process.env.TAXCORE_*
```

### Manual Deployment

```
websocket-server/.env
    ↓
export $(cat .env | xargs)
    ↓
Shell environment variables
    ↓
Node.js reads process.env.TAXCORE_*
```

### PHP Application

```
.env (root) - PHP only
    ↓
config.php calls parse_ini_file()
    ↓
PHP putenv() for PHP variables only
```

## Key Differences

| Aspect | Docker | Manual |
|--------|--------|--------|
| **Config File** | `.env` at root | `websocket-server/.env` |
| **Certificate** | `TAXCORE_PFX_FILE` (filename only) | `TAXCORE_PFX_PATH` (full path) |
| **Certificate Location** | Mounted to `/usr/src/app/certs/` | Local `FRCS_Certs_Install/` |
| **How to Load** | Docker Compose reads `.env` | `export $(cat .env | xargs)` |
| **Restart Command** | `docker-compose restart taxcore-service` | Kill process and restart |

## Best Practices

### ✅ DO:

1. **Keep environments separate:**
   - PHP config in main `.env`
   - TaxCore Docker config in root `.env` (for Docker Compose)
   - TaxCore manual config in `websocket-server/.env`

2. **Use templates:**
   ```bash
   # Docker
   cp .env.docker .env
   
   # Manual
   cp websocket-server/.env.example websocket-server/.env
   ```

3. **Add to .gitignore:**
   ```
   .env
   websocket-server/.env
   *.pfx
   ```

### ❌ DON'T:

1. **Don't mix PHP and TaxCore config** in the same `.env` that PHP parses
2. **Don't commit secrets** - keep `.env` files out of git
3. **Don't use full paths in Docker** - use filenames for `TAXCORE_PFX_FILE`
4. **Don't manually edit** inside containers - update `.env` and restart

## Quick Commands

### Docker Deployment

```bash
# Setup
cp .env.docker .env
nano .env  # Edit TaxCore settings
cp /path/to/cert.pfx FRCS_Certs_Install/
docker-compose up --build -d

# Test
curl http://localhost:3001/health
docker-compose logs taxcore-service

# Update config
nano .env
docker-compose restart taxcore-service
```

### Manual Deployment

```bash
# Setup
cd websocket-server
nano .env  # Edit TaxCore settings
export $(cat .env | xargs)
node taxcore-service.js &

# Test
curl http://localhost:3001/health
tail -f /usr/src/logs/taxcore-service.log

# Update config
nano .env
pkill -f taxcore-service
export $(cat .env | xargs)
node taxcore-service.js &
```

## Troubleshooting

### Error: "syntax error, unexpected '=' in .env"

**Cause:** TaxCore variables added to PHP's `.env` file

**Solution:**
1. Remove TaxCore variables from main `.env`
2. Put TaxCore config in separate location (see above)
3. Restart PHP server: `sudo systemctl restart apache2`

### Error: "Certificate not found"

**Docker:**
- Check: `docker-compose exec taxcore-service ls /usr/src/app/certs/`
- Verify: `TAXCORE_PFX_FILE` matches filename

**Manual:**
- Check: `ls /var/www/html/TAF/FRCS_Certs_Install/*.pfx`
- Verify: `TAXCORE_PFX_PATH` is full absolute path

### TaxCore service not using new config

**Docker:**
```bash
docker-compose down
docker-compose up --build -d
```

**Manual:**
```bash
pkill -f taxcore-service
cd websocket-server
export $(cat .env | xargs)
node taxcore-service.js &
```

## Summary

| Component | Environment File | Purpose |
|-----------|-----------------|---------|
| **PHP** | `/var/www/html/TAF/.env` | Database, PHP settings, ports |
| **TaxCore (Docker)** | `/var/www/html/TAF/.env` | TaxCore API URLs, cert, PIN |
| **TaxCore (Manual)** | `websocket-server/.env` | TaxCore API URLs, cert, PIN |

**The key insight:** Docker and PHP can both use `.env` at the root, but they use different variables. PHP reads its own variables (DB_HOST, PHP_PORT) while Docker Compose reads TaxCore variables (TAXCORE_*) to pass to the container. They never conflict because they're used by different systems.

---

**Related Documentation:**
- `websocket-server/ENVIRONMENT.md` - Detailed environment setup
- `docs/TaxCore_Configuration_Guide.md` - Complete configuration reference
- `docs/TaxCore_Docker_Setup.md` - Docker deployment guide