nlcc-itinerary/README.md

New Life Christian Church - Sermon Itinerary

A web application for managing and displaying weekly sermons for New Life Christian Church.

Features

• 📝 Sermon Management: Create and manage sermon content with a user-friendly form
• 🔐 Enterprise Security: OWASP-compliant authentication with CSRF protection, session management, and account lockout
• 👥 User Management: Full admin panel for managing users, roles, and account security
• 🔒 Password Security: Bcrypt hashing, strong password requirements, and secure password reset with 8-character alphanumeric codes
• 🛡️ Account Protection: Dual-layer brute force protection (IP-based + per-account lockout)
• 📱 QR Codes: Generate QR codes for easy sermon sharing
• 📅 Date-based URLs: Sermons accessible via sermon-MMDDYYYY format
• 🎨 Modern UI: Clean, responsive design using Tailwind CSS and Inter font
• 📊 Three Sections: Bible References, Personal Appliance, and Pastor's Challenge
• 🗂️ Smart Organization: Recent sermons (last 3 months) displayed by default, older sermons in dropdown
• 📧 Email Notifications: Password reset codes and sermon notes via SMTP
• 🐳 Docker Ready: Fully containerized for easy deployment with auto-generated secrets

Technology Stack

• Frontend: Nuxt 3 (Vue.js)
• Styling: Tailwind CSS with Inter font from Google Fonts
• Database: SQLite
• QR Codes: qrcode library
• Deployment: Docker & Docker Compose

Configuration

This application uses environment variables configured directly in docker-compose.yml. Edit the file to customize your deployment settings.

Environment Variables

Variable	Description	Default	Required
SITE_URL	Public URL where the app is hosted (used for QR codes)	https://nlcc.rydertech.us	Yes
AUTH_SECRET	Secret key for authentication sessions	Auto-generated	No
ADMIN_USERNAME	Initial admin login username	admin	No
ADMIN_PASSWORD	Initial admin login password	Auto-generated	No
EMAIL_HOST	SMTP server hostname	smtp.example.com	Yes
EMAIL_PORT	SMTP server port	587	Yes
EMAIL_USER	SMTP authentication username	noreply@example.com	Yes
EMAIL_PASSWORD	SMTP authentication password	Required	Yes
EMAIL_FROM	Email sender address and name	New Life Christian Church <noreply@example.com>	Yes

Security Note: AUTH_SECRET and ADMIN_PASSWORD are now automatically generated on first launch using cryptographically secure random generation. They are stored in the database and logged once to container logs.

Customizing Configuration

Edit docker-compose.yml and update the required values:

services:
  nlcc-itinerary:
    environment:
      - SITE_URL=https://your-church-domain.com
      # Optional: customize admin username (default: "admin")
      # - ADMIN_USERNAME=your-admin-username
      # Optional: set custom admin password (otherwise auto-generated)
      # - ADMIN_PASSWORD=your-secure-password
      # Email configuration (required for password resets)
      - EMAIL_HOST=smtp.gmail.com
      - EMAIL_PORT=587
      - EMAIL_USER=your-email@gmail.com
      - EMAIL_PASSWORD=your-app-password
      - EMAIL_FROM=Your Church Name <your-email@gmail.com>

Note: AUTH_SECRET is no longer needed in configuration - it's automatically generated and stored in the database on first launch.

Getting Started

Prerequisites

• Docker and Docker Compose installed on your system

Installation & Deployment

1. Clone the repository:

git clone <repository-url>
cd nlcc-itinerary

2. Edit docker-compose.yml and configure your settings:

   • Update SITE_URL to your public domain
   • Configure email settings (required for password resets)
   • Optionally set ADMIN_USERNAME and ADMIN_PASSWORD (otherwise auto-generated)

3. Build and run with Docker Compose:

docker-compose up -d --build

The application will be available at http://localhost:3002 (or your configured port)

Important: The SITE_URL must be set correctly for QR codes to work. This should be the public URL where your application is accessible (e.g., https://church.example.com).

Initial Admin Account

The initial admin account is created automatically on first run with secure auto-generated credentials:

Default behavior:

• Username: admin (can be customized with ADMIN_USERNAME env var)
• Password: Auto-generated (cryptographically secure 16-character password)

Retrieving Auto-Generated Credentials:

# View the auto-generated admin password from container logs
docker logs nlcc-itinerary 2>&1 | grep "ADMIN CREDENTIALS"

The output will show:

╔════════════════════════════════════════════════════════╗
║          🔐 ADMIN CREDENTIALS (SAVE THESE!)           ║
╠════════════════════════════════════════════════════════╣
║ Username: admin                                        ║
║ Password: <randomly-generated-password>                ║
╚════════════════════════════════════════════════════════╝

⚠️ Important:

• Credentials are logged only once on first startup
• Save the credentials immediately - they won't be shown again
• Alternatively, set ADMIN_PASSWORD in docker-compose.yml to use a custom password
• Change admin password after first login via the profile page
• Additional users and admins can be created through the user management interface

Project Structure

nlcc-itinerary/
├── assets/css/          # Global styles
├── components/          # Vue components
│   ├── SermonCard.vue
│   ├── QRCodeButton.vue
│   └── QRCodeModal.vue
├── middleware/          # Route middleware
│   └── auth.ts
├── pages/              # Application pages
│   ├── index.vue       # Main sermon listing
│   ├── login.vue       # Login page
│   ├── register.vue    # User registration
│   ├── admin.vue       # Sermon creation form
│   ├── users.vue       # User management (admin only)
│   ├── profile.vue     # User profile settings
│   └── [slug].vue      # Individual sermon page
├── plugins/            # Nuxt plugins
│   └── csrf.client.ts  # CSRF auto-injection
├── server/
│   ├── api/            # API endpoints
│   │   ├── auth/       # Authentication endpoints
│   │   ├── sermons/    # Sermon CRUD endpoints
│   │   ├── users/      # User management endpoints
│   │   └── profile/    # Profile management
│   ├── middleware/     # Server middleware
│   │   └── csrf.ts     # CSRF validation
│   └── utils/          # Server utilities
│       ├── database.ts # SQLite database functions
│       ├── auth.ts     # Authentication helpers
│       ├── csrf.ts     # CSRF protection utilities
│       └── email.ts    # Email sending functions
├── logos/              # Church logos
├── Dockerfile          # Docker configuration
├── docker-compose.yml  # Docker Compose configuration
└── nuxt.config.ts      # Nuxt configuration

Usage

Creating a Sermon

1. Navigate to /login and sign in with admin credentials
2. You'll be redirected to /admin
3. Fill in the sermon details:
   • Date: Select the sermon date (URL will be auto-generated as sermon-MMDDYYYY)
   • Title: Enter the sermon title
   • Bible References: Add one or more Bible verses (use +/- buttons)
   • Personal Appliance: Enter personal application content
   • Pastor's Challenge: Enter the pastor's challenge content
4. Click "Create Sermon"

Viewing Sermons

• Main Page (/): Shows recent sermons (last 3 months) with option to view older ones
• Individual Sermon (/sermon-MMDDYYYY): Full sermon details with QR code
• QR Code: Click the QR code button on any sermon card or page to generate a scannable code

Database

The application uses SQLite with the following schema:

Sermons Table

• id: Primary key
• slug: Unique sermon identifier (e.g., sermon-09282025)
• title: Sermon title
• date: Sermon date
• bible_references: Newline-separated Bible verses
• personal_appliance: Personal application content
• pastors_challenge: Pastor's challenge content
• created_at: Timestamp

Users Table

• id: Primary key
• username: User's username (unique)
• password: User's password (bcrypt hashed)
• first_name: User's first name
• last_name: User's last name
• email: User's email address
• is_admin: Admin flag (0 or 1)
• failed_login_attempts: Failed login counter
• locked_until: Account lock expiration timestamp
• created_at: Account creation timestamp

Sessions Table

• id: Primary key
• token: Session token (unique)
• username: Associated username
• expires_at: Session expiration timestamp
• csrf_token: CSRF token for request validation
• created_at: Session creation timestamp

Settings Table

• key: Setting key (primary)
• value: Setting value
• created_at: Creation timestamp
• updated_at: Last update timestamp

Security Features

This application implements enterprise-grade security following OWASP best practices:

✅ Implemented Security Features

1. Auto-Generated Secrets

   • AUTH_SECRET automatically generated using cryptographic randomness
   • Admin password auto-generated with 16 characters (uppercase, lowercase, numbers, symbols)
   • All secrets stored securely in database

2. Password Security

   • Bcrypt hashing with 10 salt rounds
   • Strong password requirements (8+ chars, uppercase, lowercase, number/symbol)
   • Secure password reset with 8-character alphanumeric codes (1.8 trillion combinations)
   • Session invalidation on password changes

3. CSRF Protection

   • Double-submit cookie pattern implementation
   • Automatic token injection on all API requests
   • Three-way validation (cookie, header, session database)
   • Zero configuration needed in components

4. Session Management

   • Secure session tokens with HTTP-only cookies
   • Automatic session expiration (24 hours)
   • Session invalidation on security events (password changes, admin resets)
   • Protection against session fixation attacks

5. Account Lockout (Dual-Layer Brute Force Protection)

   • IP-based rate limiting (existing)
   • Per-account lockout: 10 failed attempts = 30 minute lock
   • Automatic unlock after expiration
   • Admin manual unlock capability via UI

6. User Management

   • Role-based access control (admin/user)
   • Admin dashboard for user management
   • Account lock status visibility
   • Password reset functionality

🔒 Production Recommendations

1. ✅ Strong passwords - Enforced by application
2. ✅ Password hashing - Bcrypt with salt rounds
3. ✅ CSRF protection - Implemented
4. ✅ Session security - HTTP-only cookies with expiration
5. ✅ Account lockout - Dual-layer protection
6. ✅ Secrets management - Auto-generated and stored securely
7. Enable HTTPS - Configure reverse proxy (nginx/Caddy)
8. Regular backups - Backup /app/data directory
9. Email security - Use app-specific passwords for SMTP
10. Monitor logs - Review failed login attempts

🛡️ Security Compliance

• OWASP Top 10 2021: Addressed broken authentication, injection, security misconfiguration
• Password Storage: NIST-compliant bcrypt hashing
• CSRF Protection: Industry-standard double-submit pattern
• Session Security: Secure cookie attributes and expiration
• Brute Force Protection: Account lockout + rate limiting

Docker Commands

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Rebuild after changes
docker-compose up -d --build

# Access container shell
docker exec -it nlcc-itinerary sh

Data Persistence

The SQLite database is stored in the ./data directory, which is mounted as a volume in Docker. This ensures sermon data persists across container restarts.

License

This project is created for New Life Christian Church.

Support

For issues or questions, please contact the development team.