A ready-to-run toolkit that lets you containerize a CFML app in minutes, the ColdFusion Dockerfile and CommandBox Starter pack bundles a production-grade Dockerfile, docker-compose example, CFConfig templates, and opinionated defaults. Whether you run Adobe ColdFusion or Lucee, you can build, configure, and deploy a consistent, reproducible environment with CommandBox at its core.
—
## Overview
This Starter pack is a curated set of files that helps CFML developers spin up a modern, containerized runtime quickly. It leverages the official CommandBox Docker image as the server runtime, supports both Adobe ColdFusion and Lucee engines, and includes CFConfig for automated ColdFusion Administrator Configuration.
With these assets, you can:
– Build local development stacks fast and with dev/prod parity.
– Bake in secure defaults and CI/CD-friendly patterns.
– Deploy to Docker, docker-compose, or Kubernetes with minimal changes.
—
## What You’ll Get
Inside the Download, you’ll find:
– Dockerfile templates
– A ready-to-use Dockerfile targeting the CommandBox base image.
– Optional multi-stage build example to reduce final image size.
– docker-compose.yml
– Local development stack with environment variables, volumes, and healthcheck.
– CommandBox Configuration
– box.json for dependencies and commands.
– server.json with sensible defaults: ports, rewrites, webroot, and SSL support.
– CFConfig templates
– cfconfig.json to seed ColdFusion Administrator settings, datasources, mail servers, and passwords.
– Environment-specific overlays (e.g., cfconfig.dev.json, cfconfig.prod.json).
– Application scaffolding
– Basic app directory structure (/app), webroot (/app/www), and sample index.cfm.
– .env.example for environment variables.
– Documentation
– README with quick start, supported engines, and common commands.
Each file is commented so you can understand and customize it quickly.
—
## Supported Environments
– CFML Engines
– Adobe ColdFusion 2018/2021/2023 (via CFENGINE tags).
– Lucee 5.x and 6.x.
– Operating Systems
– Linux containers (Debian/Ubuntu base). Alpine guidance included.
– Container Platforms
– Docker Desktop, Docker Engine, Docker Compose, Kubernetes.
– CI/CD
– GitHub Actions, GitLab CI, Azure Pipelines, Jenkins.
—
## Benefits
– Faster Onboarding: New team members can run the app with a single command.
– Reproducible builds: The Dockerfile locks in the OS, CF engine, JDK, and modules.
– Automated configuration: CFConfig applies ColdFusion Administrator settings on boot.
– Secure-by-default: Environment variables and secrets keep passwords out of source control.
– Flexible engine choice: Switch between Adobe ColdFusion and Lucee with one variable.
– Production-ready patterns: Healthchecks, logs, JVM tuning, and multi-stage builds are included.
—
## How to Use
### Prerequisites
– Docker Desktop or Docker Engine installed and running.
– Git (optional but recommended).
– Basic familiarity with CommandBox and CFML.
—
### Quick Start
1) Download and extract the Starter Pack.
2) Copy your app into ./app or start from the included sample.
3) Choose your engine:
– For Adobe ColdFusion: set CFENGINE=adobe@2023
– For Lucee: set CFENGINE=lucee@5
4) Copy .env.example to .env and set values (admin password, ports, etc.).
5) Start the stack:
– Docker Compose up –build
6) Visit http://localhost:8080 to confirm it’s running.
—
### Dockerfile (essentials)
A simplified Dockerfile included in the pack:
FROM ortussolutions/commandbox:latest
ENV CFENGINE=lucee@5
ENV APP_DIR=/app
WORKDIR ${APP_DIR}
COPY . ${APP_DIR}
RUN box install
EXPOSE 8080 8443
HEALTHCHECK –interval=30s –timeout=2s –retries=5 CMD curl -f http://localhost:8080/health || exit 1
CMD [ “box”, “server”, “start”, “server.json” ]
To target Adobe ColdFusion instead, set CFENGINE=adobe@2023 and add any required EULA variables in compose.
—
### docker-compose.yml (essentials)
A typical compose file provided:
services:
web:
build: .
image: cfml-app:latest
environment:
– CFENGINE=${CFENGINE}
– BOX_SERVER_PROFILE=${ENVIRONMENT:-development}
– BOX_SERVER_WEB_PORT=${PORT:-8080}
– BOX_SERVER_WEB_SSL_PORT=${SSL_PORT:-8443}
– BOX_SERVER_JVM_HEAPSIZE=${HEAP_SIZE:-512m}
– CFCONFIG_ADMINPASSWORD=${CFADMIN_PASSWORD}
– CFCONFIG_IMPORT=${CFCONFIG_FILE:-/app/cfconfig.json}
– ACCEPT_EULA=YES
ports:
– “${PORT:-8080}:8080”
– “${SSL_PORT:-8443}:8443”
volumes:
– ./app:/app
healthcheck:
test: [“CMD”, “curl”, “-f”, “http://localhost:8080/health”]
interval: 30s
timeout: 2s
retries: 5
Notes:
– CFCONFIG_IMPORT applies the cfconfig.json on start.
– CFENGINE can be set to lucee@5, lucee@6, adobe@2021, adobe@2023.
– ACCEPT_EULA may be required for Adobe ColdFusion images.
—
### CFConfig basics
The included cfconfig.json seeds:
– Administrator password (from CFCONFIG_ADMINPASSWORD).
– Datasources (DSN, driver, username/password, connection string).
– Mail Server settings.
– JVM settings.
– CORS, Debugging, and cache settings.
To override safely, supply a second file via CFCONFIG_IMPORT=/app/cfconfig.prod.json or mount a secret path. This keeps credentials out of source control.
—
### CommandBox configuration
– server.json sets:
– Webroot: /app/www
– Rewrites: URL rewriting for frameworks (ColdBox, FW/1, etc.).
– SSL enablement.
– Charset and compression.
– box.json manages packages and scripts. Use box install to fetch modules (e.g., CFConfig, DotEnv).
Helpful commands:
– box server start
– box server stop
– box server log
– box task run path=tasks/seed.cfc
—
### Environment variables (common)
– CFENGINE: lucee@5 | lucee@6 | adobe@2023.
– CFCONFIG_ADMINPASSWORD: Administrator password injection.
– CFCONFIG_IMPORT: Path to cfconfig JSON to import on boot.
– HEAP_SIZE / JVM_ARGS: JVM tuning, e.g., -Xms512m -Xmx1024m -XX:+UseG1GC.
– PORT / SSL_PORT: Exposed ports.
– ENVIRONMENT: development | staging | production.
– ACCEPT_EULA: YES for Adobe ColdFusion Licensing acceptance when required.
—
### Production tips
– Switch to a multi-stage Dockerfile:
– Stage 1: build modules, warm up artifacts.
– Stage 2: copy only the final /app and CommandBox home.
– Pin specific image tags:
– FROM ortussolutions/commandbox:adobe2023-jdk17
– Harden your image:
– Add a non-root user.
– Limit OS packages.
– Use read-only filesystem and tmpfs where possible.
– Externalize secrets:
– Use Docker secrets or environment variables injected by your orchestrator.
– Observability:
– Route logs to stdout/stderr.
– Add health and readiness probes for Kubernetes.
– Zero-downtime deploys:
– Configure graceful shutdown.
– Use rolling updates with liveness probes.
—
– Keep CFConfig minimal in source control; overlay sensitive settings in CI/CD.
– Prefer immutable images over bind-mounting in production for better Performance and Security.
– Cache dependencies with box install and leverage Docker layer caching.
– Use distinct profiles: dev (hot reload, debug on), prod (debug off, cache on, robust JVM).
– Validate ports and SSL certificates; automate Let’s Encrypt in ingress or a sidecar.
– Monitor heap and GC with JVM metrics; right-size HEAP_SIZE and container memory limits.
—
## Benefits and Use Cases
– Rapid Prototyping: Create a CFML microservice with a single compose file.
– Legacy Modernization: Lift-and-shift older ColdFusion apps into containers with minimal code changes.
– CI/CD pipelines: Build once, deploy everywhere; run Integration tests against the same image that goes to production.
– Multi-engine testing: Verify compatibility across Lucee and Adobe ColdFusion by flipping CFENGINE.
– Cloud-native Deployment: Ship to ECS, EKS, AKS, or GKE with healthchecks and autoscaling.
The Starter Pack reduces setup friction, enforces consistency, and improves Performance through tuned JVM and Undertow defaults—all while keeping configuration transparent and repeatable.
—
– Container starts but app 404s
– Confirm webroot in server.json matches your app path (default /app/www).
– Check rewrite rules if using a framework with index.cfm front controller.
– Administrator password not applied
– Ensure CFCONFIG_ADMINPASSWORD is set and CFCONFIG_IMPORT points to a valid file.
– High memory usage or slow startup
– Lower HEAP_SIZE or tweak JVM_ARGS; ensure you’re not over-allocating relative to container limits.
– Changes not reflected in dev
– Verify volume mount ./app:/app is active; check box server log for errors.
– Adobe Licensing prompts
– Set ACCEPT_EULA=YES and provide required license parameters per your license terms (outside this pack).
—
## Key Takeaways
– The pack gives you a complete, opinionated scaffold for Dockerizing CFML with CommandBox and CFConfig.
– Switch between Lucee and Adobe ColdFusion using a single CFENGINE variable.
– Automation-first: server.json and cfconfig.json capture server and admin settings as code.
– Suitable for local dev, CI pipelines, and production with minor tweaks.
– Strong defaults reduce risk and speed up deployments while remaining customizable.
—
#### FAQ: Can I use this with existing apps?
Yes. Copy your application into /app (with your webroot under /app/www by default) and adjust server.json if your structure differs. Most Legacy ColdFusion apps run with minimal changes.
—
#### FAQ: How do I choose between Lucee and Adobe ColdFusion?
Set CFENGINE in your compose or Dockerfile. For example: CFENGINE=lucee@5 for Lucee 5, CFENGINE=adobe@2023 for Adobe ColdFusion 2023. Choose Adobe for commercial Features and support; choose Lucee for a lightweight, open-source engine.
—
#### FAQ: Where should I store secrets?
Avoid committing them to Git. Use Docker secrets, environment variables injected by your orchestrator, or a secret manager like AWS Secrets Manager or HashiCorp Vault. The pack demonstrates how to pass CFCONFIG_ADMINPASSWORD and DSN credentials securely.
—
#### FAQ: Can I run this on Kubernetes?
Yes. Convert docker-compose configs to manifests or use a tool like Kompose. Add readiness and liveness probes, mount secrets as env or files, and use a PersistentVolume if you need writable storage.
—
#### FAQ: How do I enable HTTPS locally?
Enable SSL in server.json and map SSL_PORT (default 8443). For certificates, you can generate self-signed keys for local use or terminate TLS at a Reverse proxy or ingress in production.
