CFConfig: automasi konfigurasi Lucee untuk Docker dan CI

CFConfig: automasi konfigurasi Lucee untuk Docker dan CI

Konfigurasi Lucee seperti datasource, mapping, cache dan tetapan admin biasanya hidup dalam UI Lucee Administrator, bukan dalam fail yang boleh dikawal versi. CFConfig ialah alat baris perintah yang mengeksport semua tetapan itu ke satu fail JSON, mengimportnya semula ke pelayan lain, dan memindahkannya antara persekitaran. Dengan CFConfig, konfigurasi boleh disimpan dalam repo, dijalankan semasa bekas Docker mula, dan disahkan dalam CI. Artikel ini menunjukkan arahan asas, contoh fail JSON yang sah, cara mengendalikan rahsia, dan cara menyambungkannya ke Docker dan CI.

Masalahnya: konfigurasi yang hidup dalam UI admin

Apabila anda mencipta datasource, mapping atau mail server melalui Lucee Administrator, tetapan itu disimpan dalam fail XML dalaman Lucee, bukan dalam repo kod anda. Apabila pelayan ujian baharu dinaikkan, atau bekas Docker dibuang dan diganti, seseorang perlu membuka UI admin dan menekan butang yang sama sekali lagi dengan tangan. Proses itu perlahan, mudah silap, dan sukar untuk diulang secara konsisten antara persekitaran.

Masalah sebenar bukan kerana UI admin itu buruk, tetapi kerana konfigurasi yang hanya wujud dalam UI tidak boleh diuji, dijejak atau diaudit. Dua pelayan yang sepatutnya sama boleh berbeza tanpa sesiapa sedar, dan perbezaan itu hanya muncul sebagai ralat aneh di produksi.

Apa itu CFConfig dan cara memasangnya

CFConfig ialah modul CommandBox daripada Ortus Solutions, dikeluarkan di ForgeBox dengan nama commandbox-cfconfig. Ia menyokong Lucee 4.x, 5.x dan 6.x, Adobe ColdFusion daripada CF9 hingga CF2025, BoxLang dan Railo. Ia tidak memerlukan pelayan itu dimulakan oleh CommandBox: anda boleh mengurus konfigurasi mana-mana pelayan dengan menunjuk ke direktori rumah pelayan itu.

Pemasangan ialah satu arahan dalam CommandBox:

box install commandbox-cfconfig

Selepas itu arahan cfconfig tersedia. Jalankan cfconfig help untuk senarai penuh.

Arahan asas commandbox-cfconfig

Empat kata kerja utama ialah export, import, transfer dan diff. Jika anda menjalankannya dari akar pelayan CommandBox, CFConfig mencari pelayan itu sendiri.

# Eksport semua tetapan pelayan semasa ke fail JSON
box cfconfig export .cfconfig.json

# Import tetapan daripada fail JSON ke pelayan semasa
box cfconfig import .cfconfig.json

# Pindahkan tetapan terus dari satu pelayan ke pelayan lain
box cfconfig transfer from=pengeluaran to=ujian

# Bandingkan tetapan dua pelayan dan lihat perbezaannya
box cfconfig diff from=pengeluaran to=ujian

Anda juga boleh menyentuh satu tetapan atau satu datasource tanpa fail penuh:

# Lihat dan tetapkan satu nilai
box cfconfig show requestTimeout
box cfconfig set requestTimeout=0,0,10,0

# Urus satu datasource
box cfconfig datasource save name=kedai dbdriver=mysql host=localhost port=3306 database=kedai username=app_kedai password=rahsia
box cfconfig datasource list

transfer dan diff ialah dua arahan yang paling berguna untuk CI, kerana ia membolehkan anda menyegerakkan atau membandingkan pelayan ujian dengan produksi tanpa menyentuh UI.

Struktur fail cfconfig.json

Eksport menghasilkan fail JSON generik yang boleh dibaca pada mana-mana enjin. Tetapan yang tidak terpakai pada enjin tertentu diabaikan sahaja. Contoh fail yang sah dan ringkas:

{
  "adminPassword": "${LUCEE_ADMIN_PASSWORD}",
  "requestTimeout": "0,0,1,0",
  "datasources": {
    "kedai": {
      "dbdriver": "mysql",
      "host": "mysql",
      "port": "3306",
      "database": "kedai",
      "username": "app_kedai",
      "password": "${DB_PASSWORD}"
    }
  }
}

Perhatikan dua perkara. Pertama, datasources ialah objek yang kuncinya ialah nama datasource. Butiran penuh tentang medan datasource Lucee ada dalam panduan konfigurasi datasource. Kedua, nilai password dan adminPassword bukan kata laluan sebenar, tetapi rujukan ${...} kepada pemboleh ubah persekitaran. Itu kunci kepada pengendalian rahsia yang dibincangkan kemudian.

Jika fail itu dinamakan .cfconfig.json dan diletakkan dalam webroot, CommandBox memuatkannya secara automatik setiap kali pelayan mula. Anda juga boleh menyimpannya di luar webroot dan menunjuk kepadanya melalui kunci cfconfigFile dalam server.json, supaya fail yang mungkin mengandungi rahsia tidak terdedah kepada pelayan web.

Menyimpan cfconfig.json dalam repo

Sebaik sahaja konfigurasi wujud sebagai JSON, ia boleh dimasukkan ke dalam git bersama kod. Setiap perubahan konfigurasi menjadi sebahagian daripada sejarah versi, boleh disemak dalam pull request, dan dijejak kembali bila ia berubah.

Satu peringatan: fail eksport penuh mungkin mengandungi nilai sensitif, jadi sebelum commit anda perlu membuangnya. CFConfig menyediakan excludeList untuk mengeluarkan kunci tertentu:

# Eksport tanpa sebarang kunci bernama password
box cfconfig export to=.cfconfig.json excludeList=**.password

Simpan fail yang sudah bersih ini dalam repo. Nilai sebenar disuntik semula semasa import melalui pemboleh ubah persekitaran.

Mengendalikan rahsia tanpa mendedahkannya

Peraturan asasnya: jangan sekali-kali menyimpan kata laluan datasource atau admin dalam repo, walaupun repo itu peribadi. Sebaik sahaja rahsia masuk ke dalam sejarah git, membuangnya kemudian adalah menyakitkan, dan sebarang kebocoran kunci akses bermakna semua yang membaca repo itu turut membaca rahsia anda. Ini topik yang dibincangkan lebih lanjut dalam panduan rahsia dan pemboleh ubah persekitaran.

CFConfig menawarkan tiga mekanisme untuk memisahkan rahsia daripada fail:

1. Rujukan ${...} dalam JSON. Nilai seperti ${DB_PASSWORD} diperluaskan semasa pelayan mula, dan boleh membawa nilai lalai dengan ${DB_PASSWORD:rahsia_lalai}.

2. Penggantian automatik semasa eksport. Parameter replace: menulis rujukan env ke dalam JSON dan mencipta fail .env di direktori semasa:

box cfconfig export to=.cfconfig.json replace:datasources\.kedai\.password=DB_PASSWORD

3. Penggantian melalui pemboleh ubah persekitaran cfconfig_. Sebarang tetapan boleh ditindih dengan env var yang bermula dengan cfconfig_, dan titik dalam kunci bersarang ditulis sebagai garis bawah:

export cfconfig_datasources_kedai_password=rahsia_sebenar

Pemboleh ubah ini dimuatkan selepas fail JSON dan mengambil keutamaan, jadi ia sesuai untuk Docker dan CI yang menyuntik rahsia pada masa jalan.

Dockerfile dan docker-compose yang menjalankan import semasa mula

Dalam Docker, matlamatnya ialah bekas baharu mendapat konfigurasi penuh tanpa sesiapa membuka UI. Dua pendekatan yang berfungsi: biarkan .cfconfig.json dimuat secara automatik oleh CommandBox, atau jalankan import secara eksplisit dalam skrip permulaan.

Dockerfile di bawah membina imej daripada imej rasmi Lucee, memasang CommandBox dan CFConfig, dan menyalin fail konfigurasi ke dalam imej:

FROM lucee/lucee:6.2

RUN apt-get update \
    && apt-get install -y --no-install-recommends curl gnupg ca-certificates apt-transport-https \
    && curl -fsSl https://downloads.ortussolutions.com/debs/gpg | gpg --dearmor | tee /usr/share/keyrings/ortussolutions.gpg > /dev/null \
    && echo "deb [signed-by=/usr/share/keyrings/ortussolutions.gpg] https://downloads.ortussolutions.com/debs/noarch /" | tee /etc/apt/sources.list.d/commandbox.list \
    && apt-get update \
    && apt-get install -y --no-install-recommends commandbox \
    && box install commandbox-cfconfig --production \
    && rm -rf /var/lib/apt/lists/*

COPY cfconfig.json /opt/cfconfig/cfconfig.json
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh

ENTRYPOINT ["/docker-entrypoint.sh"]

Skrip permulaan mengimport konfigurasi ke konteks web Lucee sebelum menyerahkan kepada entrypoint asal imej yang memulakan Tomcat. Laluan /opt/lucee mengikut susun atur imej rasmi, dan toFormat=luceeWeb memilih konteks web, iaitu tempat datasource hidup secara lalai:

#!/bin/bash
set -e
box cfconfig import from=/opt/cfconfig/cfconfig.json to=/opt/lucee toFormat=luceeWeb
exec /usr/local/tomcat/bin/catalina.sh run

Dalam Compose, rahsia disuntik melalui pemboleh ubah persekitaran dan bukannya ditulis dalam fail. Ini selaras dengan panduan deploy Docker:

services:
  lucee:
    build: .
    ports:
      - "8888:8888"
    environment:
      DB_PASSWORD: ${DB_PASSWORD}
      LUCEE_ADMIN_PASSWORD: ${LUCEE_ADMIN_PASSWORD}
    volumes:
      - ./www:/var/www

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: kedai
      MYSQL_USER: app_kedai
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - dbdata:/var/lib/mysql

volumes:
  dbdata:

Nilai DB_PASSWORD hidup dalam fail .env tempatan atau dalam penyimpanan rahsia platform, bukan dalam repo.

Integrasi CI supaya pelayan ujian sepadan dengan produksi

CI ialah tempat CFConfig paling bernilai. Aliran yang biasa ialah: eksport konfigurasi daripada persekitaran rujukan, import ke pelayan ujian, jalankan ujian, dan sahkan tiada perbezaan yang tidak dijangka.

# Dalam pelayan rujukan, simpan konfigurasi terkini
box cfconfig export to=cfconfig.json

# Dalam CI, import ke pelayan ujian lalu bandingkan
box cfconfig import from=cfconfig.json to=ujian
box cfconfig diff from=pengeluaran to=ujian

Jika diff memulangkan perbezaan yang tidak dirancang, binaan gagal dan pasukan tahu pelayan ujian tidak lagi mencerminkan produksi. Ini menjadikan konfigurasi sebahagian daripada kitaran deploy tanpa henti dan bukannya langkah manual yang terpisah.

Jadual: apa yang boleh diautomasi, apa yang masih manual

CFConfig merangkumi kebanyakan tetapan biasa, tetapi bukan semua. Jadual ini membezakan yang mana satu:

Garisan yang memisahkan kedua-dua lajur ini mudah diingat: CFConfig menguruskan tetapan Lucee, bukan sistem pengendalian, pangkalan data atau pemacu luar.

Soalan Lazim (FAQ)

Adakah CFConfig percuma?

Ya. CFConfig ialah sumber terbuka daripada Ortus Solutions dan boleh dipasang terus daripada ForgeBox melalui box install commandbox-cfconfig.

Bolehkah CFConfig menguruskan pelayan yang tidak dimulakan oleh CommandBox?

Boleh. Anda menunjuk ke direktori rumah pelayan melalui parameter from atau to, dan menyatakan format enjin jika perlu.

Bagaimana saya pastikan kata laluan tidak masuk ke dalam repo?

Gunakan excludeList=**.password semasa eksport, atau replace:...=NAMA_ENV supaya JSON menyimpan rujukan ${...} dan bukannya nilai sebenar. Nilai sebenar disuntik melalui pemboleh ubah persekitaran.

Apa bezanya import dengan transfer?

import membaca daripada fail JSON ke pelayan, manakala transfer membaca terus daripada satu pelayan dan menulis ke pelayan lain tanpa melalui fail perantaraan.

Bagaimana saya sahkan pelayan ujian sepadan dengan produksi?

Jalankan box cfconfig diff from=pengeluaran to=ujian dalam CI dan gagalkan binaan jika ada perbezaan yang tidak dirancang.

Sumber

• CFConfig Documentation, Ortus Books
• Getting Started Guide, CFConfig
• JSON File Storage, CFConfig
• Env Var Overrides, CFConfig
• Export Settings, CFConfig
• commandbox-cfconfig di ForgeBox
• CommandBox Installation

Senarai semak

• Pasang CFConfig dengan box install commandbox-cfconfig.
• Eksport konfigurasi pelayan rujukan ke cfconfig.json.
• Buang kunci password dengan excludeList=**.password sebelum commit.
• Gantikan nilai sensitif dengan rujukan ${...} dan suntik melalui env semasa import.
• Simpan cfconfig.json dalam repo dan semak perubahannya dalam pull request.
• Import konfigurasi dalam skrip permulaan bekas atau dalam langkah CI.
• Jalankan cfconfig diff antara ujian dan produksi, dan gagalkan binaan atas perbezaan tidak dirancang.