ferrero-naming-tool/SETUP.md

Environment Configuration Setup Guide

Quick Setup

1. Copy Example Files

# Copy config example
cp config.example.php config.php

# Copy .env example
cp .env.example .env

2. Edit .env File

Open .env and update with your actual values:

# Database Configuration
DB_HOST=localhost
DB_PORT=5433
DB_NAME=ferrero_tracking
DB_USER=ferrero_user
DB_PASSWORD=your_actual_password

# DAM API Configuration (mTLS V2 Authentication)
DAM_BASE_URL=https://your-actual-dam-url.com
DAM_MTLS_OAUTH_URL=https://your-actual-oauth-endpoint.com/token

# Path to EXISTING certificate on server (no duplication needed)
DAM_MTLS_CERT_PATH=/path/to/existing/certificate.pfx
DAM_MTLS_CERT_PASSWORD=your_actual_cert_password

3. Verify Certificate Path

The certificate path should point to the existing certificate on your server. No need to duplicate it!

# Example: If your certificate is at:
# /var/certificates/dam-client.pfx

# Then set in .env:
DAM_MTLS_CERT_PATH=/var/certificates/dam-client.pfx

4. Set Permissions

# Protect .env file
chmod 600 .env

# Ensure web server can read it
chown www-data:www-data .env  # Adjust user/group as needed

5. Verify Configuration

The application will automatically:

1. Load environment variables from .env file
2. Use those values in config.php
3. Reference the existing certificate (no duplication)

How It Works

Environment Variable Loading

The env_loader.php file automatically loads variables from .env:

// In config.php
require_once __DIR__ . '/public-v2/env_loader.php';

// Now all .env variables are available via getenv()
$damUrl = getenv('DAM_BASE_URL');

Configuration Priority

1. Environment variables (from .env file) - highest priority
2. Fallback defaults (in config.php) - only if env var not set

Security

• ✅ .env file is in .gitignore (never committed)
• ✅ config.php is in .gitignore (never committed)
• ✅ .htaccess denies web access to config files
• ✅ Certificate referenced by path (not duplicated)

Troubleshooting

"Failed to load .env file"

• Check that .env exists in project root
• Verify file permissions (should be readable by web server)

"Certificate not found"

• Verify DAM_MTLS_CERT_PATH points to existing certificate
• Check certificate file permissions
• Ensure path is absolute, not relative

"No access token"

• Verify all DAM environment variables are set correctly
• Check certificate password is correct
• Review error logs for detailed OAuth errors

Example .env File

# Database
DB_HOST=localhost
DB_PORT=5433
DB_NAME=ferrero_tracking
DB_USER=ferrero_user
DB_PASSWORD=SecurePassword123!

# DAM API (mTLS V2)
DAM_BASE_URL=https://dam.example.com
DAM_MTLS_OAUTH_URL=https://oauth.example.com/token
DAM_MTLS_CERT_PATH=/etc/ssl/certs/dam-client.pfx
DAM_MTLS_CERT_PASSWORD=CertPassword456!

# SSO (Optional)
SSO_ENABLED=false
SSO_TENANT_ID=
SSO_CLIENT_ID=

Files Overview

File	Purpose	Committed to Git?
.env.example	Template for environment variables	✅ Yes
.env	Actual environment variables	❌ No (gitignored)
config.example.php	Template configuration	✅ Yes
config.php	Actual configuration	❌ No (gitignored)
env_loader.php	Loads .env file	✅ Yes

Next Steps

After configuration:

1. Test database connection
2. Test DAM authentication
3. Load A2-A3 Advancement tab
4. Verify campaign query works