Influence Build Guide¶

Influence is BNKops campaign tool for connecting Alberta residents with their elected representatives across all levels of government.

Complete Configuration

For detailed configuration, usage instructions, and troubleshooting, see the main Influence README.

Email Testing

The application includes MailHog integration for safe email testing during development. All test emails are caught locally and never sent to actual representatives.

Prerequisites¶

Docker and Docker Compose installed
NocoDB instance with API access
SMTP email configuration (or use MailHog for testing)
Domain name (optional but recommended for production)

Quick Build Process¶

1. Get NocoDB API Token¶

Login to your NocoDB instance
Click user icon → Account Settings → API Tokens
Create new token with read/write permissions
Copy the token for the next step

2. Configure Environment¶

Navigate to the influence directory and create your environment file:

cd influence
cp example.env .env

Edit the .env file with your configuration:

# Server Configuration
NODE_ENV=production
PORT=3333

# NocoDB Configuration
NOCODB_API_URL=https://your-nocodb-instance.com
NOCODB_API_TOKEN=your_nocodb_api_token_here
NOCODB_PROJECT_ID=your_project_id_here

# Email Configuration (Production SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM_NAME=BNKops Influence Campaign
SMTP_FROM_EMAIL=your_email@gmail.com

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Development Mode Configuration¶

For development and testing, use MailHog to catch emails:

# Development Mode
NODE_ENV=development
EMAIL_TEST_MODE=true

# MailHog SMTP (for development)
SMTP_HOST=mailhog
SMTP_PORT=1025
SMTP_SECURE=false
SMTP_USER=test
SMTP_PASS=test
SMTP_FROM_EMAIL=dev@albertainfluence.local
SMTP_FROM_NAME="BNKops Influence Campaign (DEV)"

# Email Testing
TEST_EMAIL_RECIPIENT=developer@example.com

3. Auto-Create Database Structure¶

Run the build script to create required NocoDB tables:

chmod +x scripts/build-nocodb.sh
./scripts/build-nocodb.sh

This creates six tables: - Campaigns - Campaign configurations with email templates and settings - Campaign Emails - Tracking of all emails sent through campaigns - Representatives - Cached representative data by postal code - Email Logs - System-wide email delivery logs - Postal Codes - Canadian postal code geolocation data - Users - Admin authentication and access control

4. Build and Deploy¶

Build the Docker image and start the application:

# Build the Docker image
docker compose build

# Start the application (includes MailHog in development)
docker compose up -d

Verify Installation¶

Check container status:
```
docker compose ps
```
View logs:
```
docker compose logs -f app
```
Access the application:
Main App: http://localhost:3333
Admin Panel: http://localhost:3333/admin.html
Email Testing (dev): http://localhost:3333/email-test.html
MailHog UI (dev): http://localhost:8025

Initial Setup¶

1. Create Admin User¶

Access the admin panel at /admin.html and create your first administrator account.

2. Create Your First Campaign¶

Login to the admin panel
Click "Create Campaign"
Configure basic settings:
Campaign title and description
Email subject and body template
Upload cover photo (optional)
Set campaign options:
✅ Allow SMTP Email - Enable server-side sending
✅ Allow Mailto Link - Enable browser-based mailto
✅ Collect User Info - Request name and email
✅ Show Email Count - Display engagement metrics
✅ Allow Email Editing - Let users customize message
Select target government levels (Federal, Provincial, Municipal, School Board)
Set status to Active to make campaign public
Click "Create Campaign"

3. Test Representative Lookup¶

Visit the homepage
Enter an Alberta postal code (e.g., T5N4B8)
View representatives at all government levels
Test email sending functionality

Development Workflow¶

Email Testing Interface¶

Access the email testing interface at /email-test.html (requires admin login):

Features: - 📧 Quick Test - Send test email with one click - 👁️ Email Preview - Preview email formatting before sending - ✏️ Custom Composition - Test with custom subject and message - 📊 Email Logs - View all sent emails with filtering - 🔧 SMTP Diagnostics - Test connection and troubleshoot

MailHog Web Interface¶

Access MailHog at http://localhost:8025 to: - View all caught emails during development - Inspect email content, headers, and formatting - Search and filter test emails - Verify emails never leave your local environment

Switching to Production¶

When ready to deploy to production:

Update .env with production SMTP settings:

EMAIL_TEST_MODE=false
NODE_ENV=production
SMTP_HOST=smtp.your-provider.com
SMTP_USER=your-real-email@domain.com
SMTP_PASS=your-real-password

Restart the application:
```
docker compose restart
```

Key Features¶

Representative Lookup¶

Search by Alberta postal code (T prefix)
Display federal MPs, provincial MLAs, municipal representatives
Smart caching with NocoDB for fast performance
Graceful fallback to Represent API when cache unavailable

Campaign System¶

Create unlimited advocacy campaigns
Upload cover photos for campaign pages
Customizable email templates
Optional user information collection
Toggle email count display for engagement metrics
Multi-level government targeting

Email Integration¶

SMTP email sending with delivery confirmation
Mailto link support for browser-based email
Comprehensive email logging
Rate limiting for API protection
Test mode for safe development

API Endpoints¶

Public Endpoints¶

GET / - Homepage with representative lookup
GET /campaign/:slug - Individual campaign page
GET /api/public/campaigns - List active campaigns
GET /api/representatives/by-postal/:postalCode - Find representatives
POST /api/emails/send - Send campaign email

Admin Endpoints (Authentication Required)¶

GET /admin.html - Campaign management dashboard
GET /email-test.html - Email testing interface
POST /api/emails/preview - Preview email without sending
POST /api/emails/test - Send test email
GET /api/test-smtp - Test SMTP connection

Maintenance Commands¶

Update Application¶

docker compose down
git pull origin main
docker compose build
docker compose up -d

Development Mode¶

cd app
npm install
npm run dev

View Logs¶

# Follow application logs
docker compose logs -f app

# View MailHog logs (development)
docker compose logs -f mailhog

Database Backup¶

# Backup is handled through NocoDB
# Access NocoDB admin panel to export tables

Health Check¶

curl http://localhost:3333/api/health

Troubleshooting¶

NocoDB Connection Issues¶

Verify NOCODB_API_URL and NOCODB_API_TOKEN in .env
Run ./scripts/build-nocodb.sh to ensure tables exist
Application works without NocoDB (API fallback mode)

Email Not Sending¶

In development: Check MailHog UI at http://localhost:8025
Verify SMTP credentials in .env
Use /email-test.html interface for diagnostics
Check email logs via admin panel
Review docker compose logs -f app for errors

No Representatives Found¶

Ensure postal code starts with 'T' (Alberta only)
Try different postal code format (remove spaces)
Check Represent API status: curl http://localhost:3333/api/test-represent
Review application logs for API errors

Campaign Not Appearing¶

Verify campaign status is set to "Active"
Check campaign configuration in admin panel
Clear browser cache and reload homepage
Review console for JavaScript errors

Production Deployment¶

Environment Configuration¶

NODE_ENV=production
EMAIL_TEST_MODE=false
PORT=3333

# Use production SMTP settings
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-production-email@domain.com
SMTP_PASS=your-production-password

Docker Production¶

# Build and start in production mode
docker compose -f docker-compose.yml up -d --build

# View logs
docker compose logs -f app

# Monitor health
watch curl http://localhost:3333/api/health

Monitoring¶

Health check endpoint: /api/health
Email logs via admin panel
NocoDB integration status in logs
Rate limiting metrics in application logs

Security Considerations¶

🔒 Always use strong passwords for admin accounts
🔒 Enable HTTPS in production (use reverse proxy)
🔒 Rotate SMTP credentials regularly
🔒 Monitor email logs for suspicious activity
🔒 Set appropriate rate limits based on expected traffic
🔒 Keep NocoDB API tokens secure and rotate periodically
🔒 Use EMAIL_TEST_MODE=false only in production

Support¶

For detailed configuration, troubleshooting, and usage instructions, see: - Main Influence README - Campaign Settings Guide - Files Explainer