# TaxCore Service - Docker Setup

This directory contains the Docker configuration for the TaxCore Node.js service.

## Overview

The TaxCore service runs in a Docker container alongside the other TAF services (PHP, PostgreSQL, Redis). It handles all communication with the Fiji Revenue and Customs Service (FRCS) TaxCore API.

## Container Specifications

- **Base Image**: `node:18-alpine`
- **Port**: 3001
- **Dependencies**: Node.js 18, curl (for certificate handling)
- **Health Check**: Every 30s via `/health` endpoint

## Environment Variables

The following environment variables can be configured:

| Variable | Default | Description |
|----------|---------|-------------|
| `TAXCORE_SERVICE_PORT` | `3001` | Port the service listens on |
| `TAXCORE_TAX_URL` | `https://api.sandbox.vms.frcs.org.fj/api` | TaxCore Tax API URL |
| `TAXCORE_VSDC_URL` | `http://devesdc.sandbox.vms.frcs.org.fj:8888/.../api` | TaxCore V-SDC API URL |
| `TAXCORE_PFX_PATH` | `/usr/src/app/certs/certificate.pfx` | Path to PFX certificate in container |
| `TAXCORE_PFX_PASSWORD` | `2CBP6HMW` | PFX certificate password |
| `TAXCORE_PIN_JSON` | `3840` | TaxCore PIN |
| `TAXCORE_DEBUG` | `true` | Enable debug logging |

## Volumes

The container mounts the following volumes:

1. **Application Code**: `./websocket-server:/usr/src/app`
   - Allows hot-reloading during development
   - Contains the TaxCore service code

2. **Certificates**: `./FRCS_Certs_Install:/usr/src/app/certs:ro`
   - Read-only mount of certificate directory
   - Contains PFX files for mutual TLS authentication

3. **Logs**: `./logs:/usr/src/app/logs`
   - Service logs written here
   - Accessible from host for debugging

## Building the Container

### Build only TaxCore service:
```bash
docker-compose build taxcore-service
```

### Build all services:
```bash
docker-compose build
```

## Running the Container

### Start only TaxCore service:
```bash
docker-compose up taxcore-service
```

### Start all services:
```bash
docker-compose up
```

### Start in detached mode (background):
```bash
docker-compose up -d
```

## Stopping the Container

### Stop TaxCore service:
```bash
docker-compose stop taxcore-service
```

### Stop all services:
```bash
docker-compose down
```

## Viewing Logs

### View TaxCore service logs:
```bash
docker-compose logs -f taxcore-service
```

### View logs of all services:
```bash
docker-compose logs -f
```

## Health Check

The container includes a health check that runs every 30 seconds:

```bash
# Check health status
docker-compose ps

# Manual health check
curl http://localhost:3001/health
```

## Networking

All services are connected via the `taf-network` Docker network:

- **php-apache** → can access TaxCore at `http://taxcore-service:3001`
- **taxcore-service** → isolated but accessible to other containers
- Services communicate using container names as hostnames

## Environment Configuration

### Using .env file (Recommended)

Create a `.env` file in the project root:

```bash
# TaxCore 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_FILE=LK2VRSH4-DeveloperAuthenticationCertificate.pfx
TAXCORE_PFX_PASSWORD=your_password
TAXCORE_PIN_JSON=your_pin
TAXCORE_DEBUG=true
```

Docker Compose will automatically load these variables.

### Using docker-compose override

Create `docker-compose.override.yml`:

```yaml
services:
  taxcore-service:
    environment:
      - TAXCORE_PFX_PASSWORD=your_custom_password
      - TAXCORE_DEBUG=false
```

## Certificate Setup

### 1. Place certificate in project

```bash
mkdir -p FRCS_Certs_Install
cp /path/to/certificate.pfx FRCS_Certs_Install/
```

### 2. Update .env file

```bash
TAXCORE_PFX_FILE=certificate.pfx
TAXCORE_PFX_PASSWORD=your_password
```

### 3. Rebuild and restart

```bash
docker-compose up -d taxcore-service
```

## Troubleshooting

### Container won't start

1. **Check logs**:
   ```bash
   docker-compose logs taxcore-service
   ```

2. **Verify certificate exists**:
   ```bash
   ls -la FRCS_Certs_Install/
   ```

3. **Check port availability**:
   ```bash
   lsof -i :3001
   # or
   netstat -tlnp | grep 3001
   ```

### Certificate not found

1. **Verify volume mount**:
   ```bash
   docker-compose exec taxcore-service ls -la /usr/src/app/certs/
   ```

2. **Check permissions**:
   ```bash
   chmod 644 FRCS_Certs_Install/*.pfx
   ```

3. **Update .env file** with correct filename

### Health check failing

1. **Check if service is running**:
   ```bash
   docker-compose exec taxcore-service curl http://localhost:3001/health
   ```

2. **Check service logs**:
   ```bash
   docker-compose logs -f taxcore-service
   ```

3. **Restart container**:
   ```bash
   docker-compose restart taxcore-service
   ```

### Can't connect from PHP

1. **Verify network**:
   ```bash
   docker network inspect taf_taf-network
   ```

2. **Test from PHP container**:
   ```bash
   docker-compose exec php-apache curl http://taxcore-service:3001/health
   ```

3. **Check environment variable**:
   ```bash
   docker-compose exec php-apache env | grep TAXCORE
   ```

## Development vs Production

### Development Mode

- Hot-reload enabled via volume mounts
- Debug logging enabled
- Running in foreground for logs

```bash
docker-compose up taxcore-service
```

### Production Mode

- Run in detached mode
- Disable debug logging
- Set restart policy

```yaml
# docker-compose.prod.yml
services:
  taxcore-service:
    restart: always
    environment:
      - TAXCORE_DEBUG=false
```

```bash
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

## Scaling

To run multiple TaxCore service instances:

```bash
docker-compose up -d --scale taxcore-service=3
```

Then add a load balancer (nginx) to distribute requests.

## Monitoring

### Container Stats

```bash
docker stats taxcore-service
```

### Health Check Status

```bash
docker inspect taxcore-service | grep -A 10 Health
```

### Service Logs

```bash
# Real-time logs
docker-compose logs -f taxcore-service

# Last 100 lines
docker-compose logs --tail=100 taxcore-service

# Since specific time
docker-compose logs --since="2025-10-01T00:00:00" taxcore-service
```

## Backup & Recovery

### Backup Certificates

```bash
tar -czf taxcore-certs-backup.tar.gz FRCS_Certs_Install/
```

### Export Logs

```bash
docker-compose logs taxcore-service > taxcore-service-logs.txt
```

## Security Best Practices

1. **Never commit certificates** to version control
2. **Use .env file** for sensitive data (add to .gitignore)
3. **Mount certificates as read-only** (`:ro` flag)
4. **Limit container permissions** (run as non-root if possible)
5. **Keep base image updated** (`docker-compose pull`)
6. **Use secrets management** for production (Docker Secrets, Vault)

## Integration with Other Services

### PHP Application

PHP can call the TaxCore service using the environment variable:

```php
$taxcoreUrl = getenv('TAXCORE_SERVICE_URL') ?: 'http://taxcore-service:3001';
```

### Frontend (Browser)

For direct browser connection (if enabled):

```javascript
// Note: Use host port mapping, not container name
const serviceUrl = 'http://localhost:3001';
```

## Complete Example

### 1. Setup Environment

```bash
cd /path/to/TAF
cp .env.example .env
# Edit .env with your values
nano .env
```

### 2. Prepare Certificates

```bash
mkdir -p FRCS_Certs_Install
cp /path/to/certificate.pfx FRCS_Certs_Install/
chmod 644 FRCS_Certs_Install/*.pfx
```

### 3. Build Services

```bash
docker-compose build
```

### 4. Start Services

```bash
docker-compose up -d
```

### 5. Verify

```bash
# Check all services are running
docker-compose ps

# Test TaxCore health
curl http://localhost:3001/health

# View logs
docker-compose logs -f taxcore-service
```

### 6. Test from POS

1. Open browser: `http://localhost:8080`
2. Navigate to POS
3. Complete a test sale
4. Verify receipt generation

## Maintenance

### Update Service

```bash
# Pull latest code
git pull

# Rebuild container
docker-compose build taxcore-service

# Restart with zero downtime
docker-compose up -d --no-deps taxcore-service
```

### Clean Up

```bash
# Remove stopped containers
docker-compose rm -f

# Remove unused images
docker image prune

# Remove unused volumes
docker volume prune
```

## References

- Main Documentation: `../../TAXCORE_IMPLEMENTATION_SUMMARY.md`
- Service Details: `../../websocket-server/TAXCORE_SERVICE.md`
- Architecture: `../../docs/TaxCore_Architecture_Diagrams.md`
- Deployment Checklist: `../../TAXCORE_DEPLOYMENT_CHECKLIST.md`