Wheels Starter Application - Detailed Overview

What This Is

This directory contains a user management and authentication web application built with the Wheels framework (Wheels 4.x), an MVC framework inspired by Ruby on Rails. The app demonstrates Wheels conventions, security practices, and a Bootstrap UI.

Important: This is not a complete, full-featured app, but rather a starter/example app built with Wheels 4.x. It is designed to help you get started and to showcase best practices in authentication, authorization, auditing, and modern web UI using Wheels.

Installation

See the Quick Start section below for setup instructions.

Key Features

User Registration & Verification

• Users can register through a secure registration form
• Email verification system sends verification emails to new users
• Account activation only after email verification is complete

Authentication

• Secure login and logout functionality
• Password reset system via email
• Note: Brute-force protection is marked as TODO in the codebase

Account Management

• Authenticated users can view their account details
• Users can update their profile information (name, email)
• Password change functionality with current password verification

Admin Panel

Admin users have access to comprehensive management features:

User Management:

• Create new users
• Edit existing user details
• Disable/soft delete users
• Permanently delete users
• Recover disabled users
• Reset user passwords (generates new temp password via email)
• Assume User Identity: Login as another user for troubleshooting (high-privilege feature)

Role & Permission Management:

• Manage roles (create, edit, delete)
• Manage permissions
• Assign/remove permissions for users and roles
• Role-Based Access Control (RBAC) implementation

System Administration:

• View and filter audit logs for security tracking
• Manage application settings
• Monitor user activities

Security Features

• CSRF Protection on all forms using Wheels built-in protection
• Input validation and sanitization on all user inputs
• Role and permission checks for all admin actions
• Audit logging for sensitive actions and changes
• Secure password handling with bcrypt hashing

Email Notifications

• Account verification emails for new registrations
• Password reset emails for forgotten passwords
• Admin password reset notifications when admins reset user passwords

Modern UI

• Bootstrap 5 for clean, responsive design
• All forms and navigation use Wheels helpers for consistency and security
• Mobile-responsive interface
• Consistent styling across all pages

Intended Audience

• Developers looking for a reference or starter app for Wheels 4.x
• Teams wanting to learn or demonstrate best practices in Wheels MVC development
• Students learning modern CFML web development
• Organizations evaluating Wheels framework for their projects

Architecture Overview

MVC Structure

app/
├── controllers/          # Application controllers
│   ├── Controller.cfc   # Base controller with security
│   ├── Main.cfc        # Home page controller
│   ├── Sessions.cfc    # Authentication controller
│   ├── Register.cfc    # User registration
│   ├── PasswordResets.cfc # Password management
│   ├── Accounts.cfc    # User account management
│   └── admin/          # Admin controllers
│   └── functions/          # helper functions
├── models/             # Data models
│   ├── User.cfc        # User model with authentication
│   ├── Role.cfc        # Role model
│   ├── Permission.cfc  # Permission model
│   └── Auditlog.cfc    # Audit logging
|── global/             # application-wide globally accessible functions
├── views/              # Presentation layer
├── mailers/            # Email templates
plugins/            # Legacy plugins the app still uses (authenticateThis, FlashMessagesBootstrap, jsconfirm)

Key Design Principles

• Convention over Configuration following Rails-inspired patterns
• Security by Default with built-in protections
• RESTful Design for clean URLs and API structure
• Separation of Concerns with clear MVC boundaries

Technology Stack

Backend

• Wheels 4.x - MVC framework, included in vendor/wheels/
• Lucee 7 - CFML engine under wheels start (lucee.json); CommandBox's Lucee also works (see below)
• Database - embedded SQLite by default (H2 under CommandBox); MySQL, PostgreSQL, Microsoft SQL Server and Oracle by swapping the datasource
• WheelsTest - Testing framework (vendored with Wheels)

Frontend

• Bootstrap 5 - UI Framework
• jQuery - JavaScript utilities
• Font Awesome - Icons

Development Tools

• Wheels CLI - Server, migrations, generators and tests (wheels start, wheels migrate)
• CommandBox - Optional alternative server (see Using CommandBox instead)

Quick Start

Prerequisites

• The Wheels CLI (wheels), 4.2 or later. See the installation guide for Homebrew, Scoop, apt and yum.

The release zip includes the framework in vendor/wheels/ and uses an embedded SQLite database, so there's nothing else to install and no database server to run.

Install and Run

# 1. Unzip the release and change into it
unzip wheels-starter-app-<version>.zip -d my-starter-app
cd my-starter-app

# 2. Create .env, then set WHEELS_RELOAD_PASSWORD and
#    WHEELS_LUCEE_ADMIN_PASSWORD in it to values of your own
cp .env.example .env

# 3. Start the server (http://localhost:8080)
wheels start

# 4. Create the schema and seed the default data
wheels migrate latest

# 5. Reload so the app picks up the seeded settings
wheels reload

Until step 4 has run, the site returns an error such as key [general_sitename] doesn't exist: the app reads its settings table when it starts. wheels migrate latest and wheels reload need the reload password from step 2.

The database files are db/development.sqlite and, for the tests, db/test.sqlite.

Default sign-in credentials are seeded by the migrations — see app/migrator/migrations/20180519105944_Adds_Default_UserAccounts.cfc.

Using CommandBox instead

The app also runs on CommandBox. CommandBox's Lucee has no SQLite driver, so under CommandBox the app uses an H2 embedded database instead: server.json installs the H2 Lucee extension and sets WHEELS_STARTER_DB=h2, which config/app.cfm checks. The data files go in db/h2/.

# 1. Create .env and set WHEELS_RELOAD_PASSWORD in it, as in step 2 above
#    (WHEELS_LUCEE_ADMIN_PASSWORD is only read by `wheels start`)
cp .env.example .env

# 2. Start the server (http://localhost:8081)
box server start

# 3. Create the schema and seed the default data: open the migrator page
#    http://localhost:8081/wheels/migrator
#    and click "Migrate To Latest", then "Confirm & Execute".

# 4. Restart the server so the app loads the seeded settings
box server restart

The wheels CLI commands, such as wheels migrate latest, talk to a server started with wheels start, so use the migrator page here.

Using a server-based database instead

To point the app at MySQL, PostgreSQL, SQL Server, or Oracle:

1. Copy .env.example to .env
2. Configure database settings based on your chosen database (see below)
3. Replace the datasource definitions in config/app.cfm with one that reads the this.env.DB_* values (the original env-driven MySQL example is preserved in the comments of .env.example)

MySQL Configuration

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=starterapp
DB_USER=youruser
DB_PASSWORD=yourpassword

PostgreSQL Configuration

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=starterapp
DB_USER=youruser
DB_PASSWORD=yourpassword

Microsoft SQL Server Configuration

DB_TYPE=mssql
DB_HOST=localhost
DB_PORT=1433
DB_NAME=starterapp
DB_USER=youruser
DB_PASSWORD=yourpassword

Oracle Configuration

DB_TYPE=oracle
DB_HOST=localhost
DB_PORT=1521
DB_NAME=starterapp
DB_USER=youruser
DB_PASSWORD=yourpassword

H2 Configuration (Development)

DB_TYPE=h2
DB_HOST=localhost
DB_PORT=9092
DB_NAME=starterapp
DB_USER=sa
DB_PASSWORD=

Database Structure

Core Tables

• users - User accounts with authentication fields
• roles - User roles for RBAC
• permissions - Individual permissions
• rolepermissions - Many-to-many between roles and permissions
• userpermissions - User-specific permission overrides
• auditlogs - Security audit trail
• settings - Application configuration

Authentication Flow

Registration Process

1. User fills registration form
2. System creates unverified user account
3. Verification email sent with unique token
4. User clicks verification link
5. Account activated and user can login

Login Process

1. User submits credentials
2. System validates against database
3. Session created with user data
4. Permissions loaded based on role
5. User redirected to appropriate dashboard

Admin Panel Features

User Management Interface

• User List: Paginated table with search and filtering
• User Actions: Edit, delete, reset password, assume identity
• Bulk Operations: Role assignment, status changes
• Audit Trail: View all user-related activities

Role Management

• Role CRUD: Create, read, update, delete roles
• Permission Assignment: Grant/revoke permissions per role
• User Assignment: Assign roles to users

Security Implementation

Built-in Security Features

• CSRF Tokens on all forms
• SQL Injection Prevention via parameterized queries
• XSS Prevention through output encoding
• Password Security with bcrypt hashing
• Session Management with secure cookies

Access Control

• Authentication Required for protected routes
• Role-based Authorization for admin functions
• Permission Checks for sensitive operations
• Audit Logging for compliance

Testing

Test Structure

tests/
├── runner.cfm      # Entry point for /wheels/app/tests (the app template's runner)
├── populate.cfm    # Migrates the test database before each run
├── specs/          # WheelsTest (BDD) specs: what the runner runs
└── RocketUnit/     # Legacy RocketUnit tests from the 3.x app (not run)

Running Tests

With the server running, open:

http://localhost:8080/wheels/app/tests

(port 8081 under CommandBox). Add ?format=json for a JSON result. The specs run on the starterApp_test datasource (SQLite, or H2 under CommandBox; defined in config/app.cfm), which tests/populate.cfm migrates before every run, so they never touch the development database.

Support & Resources

Documentation

• Wheels Guides
• Wheels API Reference

Community

• Wheels Web Community
• Wheels GitHub

License

This starter application is released under the Apache License 2.0.

---

Remember: This is a skeleton/starter application designed to showcase Wheels best practices. Use it as a starting point for your own projects and extend it according to your specific requirements.