Skip to content

dev-server.mdx

Latest commit

 

History

History
160 lines (114 loc) · 7.89 KB

dev-server.mdx

File metadata and controls

160 lines (114 loc) · 7.89 KB
Raw
title Dev Server
description wheels start, wheels stop, and wheels reload — run the Wheels dev server, shut it down cleanly, and apply framework or config changes without restarting the JVM.
type reference
sidebar
order
4

import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';

Three commands cover the inner dev loop: wheels start brings a development server up, wheels stop takes it down, and wheels reload reinitializes the running application without restarting the JVM. You'll compose these every day while iterating on a Wheels app.

You'll use this for:

  • Running your Wheels app locally while you work on it.
  • Stopping the dev server cleanly when you're done — or before switching branches.
  • Reinitializing framework state (routes, settings, DI bindings) after edits that require a full app reload without killing the JVM.

Overview

wheels start is the preferred way to run a Wheels app during development. It wraps LuCLI's lower-level wheels server start with Wheels-specific bootstrap — forwarding any extra flags through to the underlying server command so things like --port and --version still work. wheels stop is a thin wrapper around wheels server stop for the project directory. wheels reload is Wheels-specific: it talks to the running app over HTTP rather than restarting anything.

`wheels start` (Wheels module) and `wheels server start` (LuCLI core) are related but distinct surfaces. `wheels start` is the short, Wheels-aware form you'll reach for 99% of the time. `wheels server` is LuCLI's general-purpose server manager and exposes more subcommands (`status`, `list`, `restart`, `log`, and so on). See the LuCLI [`server`](../../core-commands/server/) reference for the full surface.

wheels start

Start a Wheels development server for the current project. Delegates to wheels server start under the hood and forwards extra flags to it.

Synopsis

wheels start [flags]

Any flags you pass are forwarded verbatim to wheels server start. The common ones are listed below — see wheels server start for the full list.

Flags (forwarded to wheels server start)

Flag Description
-p, --port=<port> Port number for the server (e.g., 8080).
-n, --name=<name> Custom name for the server instance.
-v, --version=<version> Lucee version to use (e.g., 6.2.2.91).
--env, --environment=<env> Environment to use (e.g., dev, staging, prod).
-c, --config=<file> Configuration file to use (defaults to lucee.json).
--disable-open-browser Don't open a browser after the server starts.
--dry-run Show the resolved configuration without starting the server.
--sandbox Start a transient background server without writing lucee.json.

Example

wheels start

Prints Starting Wheels server... in cyan and hands control off to wheels server start in the current project directory. The server runs in the foreground and occupies the terminal until it exits.

`wheels start` blocks the terminal. To stop the server, run `wheels stop` from another terminal or press `Ctrl+C` in the terminal that owns the process.

wheels stop

Stop the running Wheels development server for the current project.

Synopsis

wheels stop

Resolves the server instance from the project directory and asks LuCLI to stop it. Under the hood it runs wheels server stop scoped to the project root.

Example

wheels stop

Prints Stopping Wheels server... in cyan and delegates to wheels server stop. Useful from a second terminal when wheels start is blocking the first one.

To stop a server by explicit name or to stop every running Lucee server on the machine, drop down to the core command: `wheels server stop --name=` or `wheels server stop --all`. See the [`server`](../../core-commands/server/) reference.

wheels reload

Reinitialize the running Wheels application without restarting the JVM. Useful after edits to config/settings.cfm, config/routes.cfm, config/services.cfm, or any file that is only read during framework bootstrap.

Synopsis

wheels reload

wheels reload detects the running server's port automatically (from lucee.json, then .env) and hits http://localhost:<port>/?reload=true&password=<password> with the reload password it finds in your project config. If no server is running, it prints No running Wheels server detected. Start one with: wheels start and exits.

The reload password gates the **HTTP** endpoint `?reload=true` — it's an ACL against remote attackers who could otherwise hit that URL and wipe your app's state. The CLI runs locally, has filesystem access to your project, and reads the configured password directly from `.env` or `config/settings.cfm`. Re-prompting you for a password the tool just read from disk wouldn't add security: an attacker with disk read would already have the password.

This matches how Rails (no reload password concept; bin/rails restart/deploy tooling instead), Laravel (php artisan optimize:clear and friends never authenticate), Symfony (bin/console cache:clear), Django (manage.py runserver/migrate), and Phoenix (mix phx.server) treat the CLI/HTTP boundary. The CLI carries owner-of-the-project trust by definition.

If you need to keep wheels reload itself behind a credential check (e.g. a shared dev box where multiple users have shell access), gate it at the OS level with file permissions on .env. See Security Hardening — Reload password for the full threat model.

Example

wheels reload

On success: Application reloaded successfully. in green. On failure — most often a password mismatch — it prints Failed to reload: <message> and hints at setting RELOAD_PASSWORD in .env or config/settings.cfm.

Most CFML source changes are picked up on the next request without a reload. In development, changes to `app/global/*.cfm` are also auto-detected on bare `?reload=true` (the `reloadOnGlobalChange` setting). You need `wheels reload` when you change config that's only read at bootstrap — routes, settings, DI bindings, package manifests — or when you want to force every per-request cache to clear.

Dev loop example

The three commands compose into a typical inner loop:

# Terminal 1 — bring the server up and leave it running
wheels start

# Terminal 2 — iterate on your app
# For most CFML edits: just save the file and hit refresh.
# For config/routes/services changes, force a reload:
wheels reload

# When you're done for the day
wheels stop

Related commands