# TaxCore Environment Configuration

## Overview

The TaxCore service has **separate environment configuration** from the main PHP application:

- **PHP Application:** Uses `/var/www/html/TAF/.env` (parsed by PHP `config.php`)
- **TaxCore Service:** Uses environment variables passed via Docker or `websocket-server/.env` for manual runs

## Configuration Files

### 1. Docker Deployment (Recommended)

**File:** `.env` (at project root)

```bash
# Copy from template
cp .env.docker .env

# Edit with your TaxCore settings
nano .env
```

The `docker-compose.yaml` reads these variables and passes them to the `taxcore-service` container:

```yaml
environment:
  - TAXCORE_SERVICE_PORT=3001
  - TAXCORE_TAX_URL=${TAXCORE_TAX_URL}
  - TAXCORE_VSDC_URL=${TAXCORE_VSDC_URL}
  - TAXCORE_PFX_PATH=/usr/src/app/certs/${TAXCORE_PFX_FILE}
  - TAXCORE_PFX_PASSWORD=${TAXCORE_PFX_PASSWORD}
  - TAXCORE_PIN_JSON=${TAXCORE_PIN_JSON}
  - TAXCORE_DEBUG=${TAXCORE_DEBUG}
```

**Start services:**
```bash
docker-compose up --build -d
```

### 2. Manual/Development Deployment

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

For manual runs outside Docker, the TaxCore service can use this local `.env` file:

```bash
# TaxCore Service Environment Configuration
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 service:**
```bash
cd websocket-server

# Export environment variables manually
export $(cat .env | xargs)

# Start service
node taxcore-service.js &
```

## Important Notes

### ✅ DO:
- Edit `.env` at project root for Docker deployments
- Edit `websocket-server/.env` for manual/development runs
- Keep `.env` files out of version control (already in `.gitignore`)
- Use `TAXCORE_PFX_FILE` (filename only) for Docker
- Use `TAXCORE_PFX_PATH` (full path) for manual runs

### ❌ DON'T:
- Don't add TaxCore variables to the main `/var/www/html/TAF/.env` used by PHP
- Don't commit `.env` files with secrets
- Don't mix Docker and manual environment variable formats

## Why Separate Environments?

1. **Different Parsers:**
   - PHP uses `parse_ini_file()` for its `.env`
   - Node.js reads `process.env` (set by Docker or shell)

2. **Different Services:**
   - PHP application has different configuration needs (database, sessions, etc.)
   - TaxCore service needs TaxCore-specific settings (API URLs, certificates)

3. **Isolation:**
   - Changes to TaxCore config don't affect PHP
   - Can restart TaxCore service independently

## Configuration Priority

Environment variables are read in this order (highest priority first):

1. **Docker Compose:** Variables from `docker-compose.yaml` environment section
2. **Root .env:** Variables from `/var/www/html/TAF/.env` (loaded by Docker Compose)
3. **Hardcoded Defaults:** Fallback values in `taxcore-service.js`

## Quick Start

### Docker Setup:
```bash
# 1. Copy environment template
cd /var/www/html/TAF
cp .env.docker .env

# 2. Edit TaxCore settings
nano .env
# Update: TAXCORE_VSDC_URL, TAXCORE_PFX_FILE, TAXCORE_PFX_PASSWORD, TAXCORE_PIN_JSON

# 3. Place certificate
cp /path/to/your-cert.pfx FRCS_Certs_Install/

# 4. Start services
docker-compose up --build -d

# 5. Verify
curl http://localhost:3001/health
docker-compose logs taxcore-service
```

### Manual Setup:
```bash
# 1. Create local environment file
cd /var/www/html/TAF/websocket-server
cp .env.example .env  # Or create from scratch

# 2. Edit settings
nano .env
# Update all TAXCORE_* variables with full paths

# 3. Export and start
export $(cat .env | xargs)
node taxcore-service.js &

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

## Testing Configuration

```bash
# Check health
curl http://localhost:3001/health

# Check tax rates (doesn't need cert)
curl http://localhost:3001/tax-rates

# View logs
docker-compose logs -f taxcore-service  # Docker
tail -f /usr/src/logs/taxcore-service.log  # Manual
```

## Troubleshooting

### "Certificate not found"
- **Docker:** Check `TAXCORE_PFX_FILE` matches filename in `FRCS_Certs_Install/`
- **Manual:** Check `TAXCORE_PFX_PATH` is the full absolute path

### "Connection refused"
- Verify `TAXCORE_VSDC_URL` is correct
- Check network connectivity to FRCS servers
- Ensure UUID in URL is correct

### "Environment variables not loading"
- **Docker:** Ensure `.env` exists at project root
- **Manual:** Run `export $(cat .env | xargs)` before starting service
- Check for syntax errors in `.env` file

### PHP errors with .env
- The main PHP `.env` should NOT contain TaxCore variables
- TaxCore settings are only for the Node.js service
- If PHP `.env` has TAXCORE variables, remove them

## See Also

- `docs/TaxCore_Configuration_Guide.md` - Complete configuration reference
- `docs/TaxCore_Docker_Setup.md` - Docker setup guide
- `.env.docker` - Template for Docker environment
- `websocket-server/.env` - Template for manual deployment