Installation

Installation

Via commandbox

In CommandBox, ensure you've got the latest version of the cfwheels CLI - this is useful for installing plugins and running unit tests from the commandline.

$ install wheels-cli

Then simply create a directory, and run the install command:

$ mkdir myApp
$ cd myApp
$ install cfwheels-example-app

Manually

Download/Clone the repository. Unzip to a directory of your choice.

Start the server

Navigate to the root of the app and in commandbox, start the server by running start. Lucee 6 will be started by default. Note: lucee version will run on http://127.0.0.1:8080. The following instructions are for the Lucee version.

You will get an error when the site initially loads, that's expected. We need to create a database and setup the datasource.

Creating a database

Setup a local mySQL database called exampleapp and ensure you've got a valid user account for it. Locally that's probably root. The example app is currently only tested with MySQL. To create a new schema using the MySQL command line, run the following command:

• mysql> CREATE DATABASE exampleapp;

You could also use a GUI, e.g. MySQL Workbench

Adding the datasource

There are two main ways to configure datasources in Lucee:

1. Programmatic Configuration (Code-based)
2. Lucee Administrator (Web-based GUI)

Programmatic Configuration (Code-based)

Configure your MySQL datasource using code-based configuration in config/app.cfm. This approach keeps database settings in version control and enables environment-specific configurations.

Step 1: Environment Variables Setup

Update .env file in application root:

# MySQL Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_NAME=exampleApp
DB_USER=root
DB_PASSWORD=your_secure_password

# MySQL Driver Settings
DB_CLASS=com.mysql.cj.jdbc.Driver
DB_BUNDLENAME=com.mysql.cj
DB_BUNDLEVERSION=8.0.33

# Connection Pool Settings
DB_CONNECTIONLIMIT=50
DB_LIVETIMEOUT=30
DB_ALWAYSSETTIMEOUT=false
DB_VALIDATE=true

Step 2: Configure config/app.cfm

Update this in config/app.cfm:

// Configure MySQL datasource
this.datasources["exampleApp"] = {
    class: this.env.DB_CLASS,
    bundleName: this.env.DB_BUNDLENAME, 
    bundleVersion: this.env.DB_BUNDLEVERSION,
    connectionString: "jdbc:mysql://#this.env.DB_HOST#:#this.env.DB_PORT#/#this.env.DB_NAME#?characterEncoding=UTF-8&serverTimezone=UTC&maxReconnects=3&useSSL=false",
    username: this.env.DB_USER,
    password: this.env.DB_PASSWORD,
        
    // Connection pool optimization
    connectionLimit: val(this.env.DB_CONNECTIONLIMIT),
    liveTimeout: val(this.env.DB_LIVETIMEOUT),
    alwaysSetTimeout: this.env.DB_ALWAYSSETTIMEOUT EQ "true",
    validate: this.env.DB_VALIDATE EQ "true"
};

Benefits

• Version controlled configuration
• Environment-specific settings
• Secure credential management
• Connection pooling optimization
• No manual admin panel setup required

Lucee Administrator (Web-based GUI)

Login to the Lucee Administrator at /lucee/admin/server.cfm. As this is your first login, you will need to create a password for the administrator. Note, if you're logging into /CFIDE/administrator, the default password for the admin is commandbox.

Select Services > Datasource from the left hand column

Create a new mySQL datasource called exampleapp

Fill in the database credentials

On saving you should see a green check "OK"

Return to the site root. You'll get another error; again, that's cool. We need to run the database migrations.

Database Migrations

Navigate to http://127.0.0.1:8080/wheels/migrator

Select the Migrations Tab

Click Migrate to Latest

Reload the application by visiting http://127.0.0.1:8080/?reload=true&password=changeme

Other Recommended Steps

• Copy .env from .env.example and update the configurations.
• In config/app.cfm
  • Change this.name to something more unique
  • If using HTTPS change this.sessioncookie.secure to true
  • Either remove or change the SMTP configuration at the bottom; set to port 25 localhost if running locally.
• In config/settings.cfm
  • Change reloadPassword to something unique (and datasource name if required)
• In events/onapplicationstart.cfm
  • Change application.encryptionKey to a new one (generate via generateSecretKey("AES"))