The documentation is in the repository

Twenty-six files live in docs/, versioned with the code they describe and reviewed in the same pull requests that change the behaviour. This page indexes the twenty-four that answer questions people actually ask. The rest are internal engineering notes, and the whole set is one click from the repository.

A running site, then the docs you need

1 · install

curl -LO https://github.com/RustCFML/RustCFML/releases/latest/download/rustcfml-linux-x86_64
chmod +x rustcfml-linux-x86_64
sudo mv rustcfml-linux-x86_64 /usr/local/bin/rustcfml

2 · a page

<cfset name = "world">
<cfoutput>Hello, #name#!</cfoutput>

3 · serve

rustcfml --serve . --port 8500
open http://localhost:8500/index.cfm

Build & run

From a downloaded binary to a running web app.

Getting Started Prebuilt binaries, running files, REPL, shebang scripts, building from source docs/getting-started.md Web Server Serve mode, Application.cfc lifecycle, URL rewriting, distributed sessions docs/web-server.md Configuration .cfconfig.json: datasources, mappings, mail, security, caches, env vars docs/configuration.md Sessions The session scope, the CFID cookie, storage backends and expiry docs/sessions.md

Data

Queries, object storage and documents without a JVM.

Database queryExecute, datasources, cfqueryparam and engine specifics docs/database.md Object Storage S3, R2 and MinIO, via the S3* functions and transparent s3:// paths docs/s3.md Spreadsheets Native .xlsx read, edit and write, including charts and styling docs/spreadsheets.md

Concurrency & realtime

Real threads, and sockets on the same port as HTTP.

Threading cfthread on real OS threads: shared scopes, join, terminate, caveats docs/threads.md WebSockets Realtime channels, rooms, presence, auth, resumability and fan-out docs/websockets.md MCP A CFC as an MCP server: tools, resources, prompts, and calling other servers docs/mcp.md

Debug & observe

FusionReactor-class tooling, zero-cost when switched off.

Debugging & observability Debug footer, sampling profiler, OpenTelemetry traces and Prometheus metrics docs/debugging.md Observability ops Tail sampling, Collector to Tempo to Grafana, in one command docs/observability-ops.md Performance Benchmarks and production-mode caching docs/performance.md Profile-guided optimisation How the shipped binaries are built, and why cargo build --release is not the same thing docs/pgo.md Deployment Web app, Docker, CLI tools and Cloudflare Workers docs/deployment.md

Extend & embed

Grow the engine without waiting for a release.

Extensions .rcx files: precompiled Rust a stock binary loads at start-up docs/extensions.md Native Modules Statically link Rust built-ins into a self-contained binary docs/native-modules.md Java Shims The 100+ shimmed Java classes for createObject, and where they stop docs/java-shims.md Embedding Use the CFML engine from your own Rust code docs/embedding.md WebAssembly Compile to WASM, and Cloudflare Workers notes docs/wasm.md

Reference

How it is put together, and how much of it works.

Architecture Compilation pipeline and crate layout docs/architecture.md Testing Running the suites and writing tests that pass on Lucee too docs/testing.md Status Implementation status and remaining work docs/status.md Known Issues Documented gaps, silent no-ops and Lucee divergences docs/known-issues.md Engine Differences The assertions that differ between engines, and the ones wrapped in isRustCFML() docs/lucee-differences.md

The four things everybody looks up first

Configuration is a file, not a console. Secrets come from the environment, so nothing sensitive is ever committed.

A datasource

Add it to .cfconfig.json beside your web root, or to this.datasources in Application.cfc.

.cfconfig.json

{
  "datasources": {
    "app": {
      "type":     "PostgreSQL",
      "host":     "db.internal",
      "port":     5432,
      "database": "appdb",
      "username": "{env:DB_USER}",
      "password": "{env:DB_PASSWORD}"
    }
  }
}

Clean URLs

Drop a rewrite file in the document root. Regex, backreferences, conditions and last="true" all behave the way Tuckey documented.

urlrewrite.xml

<urlrewrite>
  <rule>
    <from>^/([a-z][a-z0-9-]*)/?$</from>
    <to last="true">/$1.cfm</to>
  </rule>
</urlrewrite>

Sessions

On by default and in process. Move them to Memcached, or let nodes discover each other, without touching a line of application code.

Application.cfc

component {
    this.name              = "MyApp";
    this.sessionManagement = true;
    this.sessionTimeout    = createTimeSpan( 0, 8, 0, 0 );
    this.sessioncookie     = {
          secure  = true
        , httpOnly = true
        , samesite = "Lax"
    };
}

Deploy it

Production mode plus a Unix socket behind nginx is the whole deployment story for most applications. For containers, the official image makes a good base.

Dockerfile

FROM ghcr.io/rustcfml/rustcfml:v0.742.2
COPY --chown=nonroot:nonroot webroot/ /srv/app/
# only if the app ships .rcx extensions:
RUN rustcfml-warm-extensions

Before you plan a migration, read Known Issues. It lists the silent no-ops and the places where behaviour diverges from Lucee by choice. It is the shortest document in the repository that will save you the most time. docs/known-issues.md

Read the README Browse docs/ on GitHub Ask a question