---
title: Configuration as code
description: Ekspor konfigurasi panel ke YAML, pratinjau dan terapkan lewat nexcmp config atau halaman Import/Export; rahasia tidak masuk file dan dicek JSON Schema.
url: https://nexcmp.com/id/docs/configure-with-ai/config-as-code/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Configuration as code {#configuration-as-code}

> **Where in the admin:** System › Settings › Import/Export (`/agent/config`). Di server: perintah `nexcmp config export`, `plan`, dan `apply`, serta `nexcmp admin <tool>`.

## Fungsi {#what-it-does}

Konfigurasi panel Anda (branding, pengaturan umum, email, peringatan Telegram, modul, mata uang, gateway pembayaran, batas, zona, paket, penyedia AI, dan halaman hukum) dapat disimpan sebagai satu file YAML. Anda dapat mengedit filenya sendiri, meminta asisten AI untuk mengeditnya, menyimpannya dalam kontrol versi, dan menerapkannya ke panel yang sama atau panel lainnya. Sebelum ada yang berubah, Anda akan selalu melihat daftar perbedaan. Rahasia tidak pernah ditulis ke dalam file.

Gunakan untuk mengkloning peninjauan ke instalasi kedua, untuk meninjau perubahan sebelum ditayangkan, untuk memulihkan pengaturan setelah terjadi kesalahan, atau untuk membiarkan AI mengusulkan seluruh konfigurasi yang Anda baca sebagai satu dokumen.

## Persyaratan {#requirements}

| Item | Persyaratan |
|---|---|
| NexCMP | 1.4.0 atau lebih baru. |
| Baris perintah | Anda adalah `root` di server panel (gunakan `sudo`). Perintah ini meminta kunci sementara dari panel (15 menit, semua cakupan) dengan sendirinya. Untuk menggunakan kunci yang lebih terbatas sebagai gantinya, tetapkan `NEXCMP_KEY` ke [admin API key](https://nexcmp.com/id/docs/configure-with-ai/admin-api-keys/) dan simpan melalui sudo, misalnya `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. |
| Halaman admin | Masuk ke admin. Halaman ini hanya-baca pada panel demo. |
| Rahasia | Nilai yang disediakan pada saat penerapan (lihat [Secrets](#secrets)); tidak pernah di dalam file. |

## Ekspor, edit, pratinjau, terapkan {#export-edit-preview-apply}

1. Ekspor konfigurasi saat ini:

   ```bash
   sudo nexcmp config export -o nexcmp.yaml
   ```

   Tanpa `-o`, YAML dicetak ke layar.
2. Edit `nexcmp.yaml` (lihat [example](#example-file) di bawah). Tetap simpan `version: 1` di atas.
3. Pratinjau apa yang akan berubah. Ini tidak mengubah apa pun:

   ```bash
   sudo nexcmp config plan -f nexcmp.yaml
   ```

   Setiap baris menunjukkan bagian, item, bidang, dan `old → new`. Baris bertanda `$` termasuk dalam bagian penagihan (lihat [Billing sections](#billing-sections)). Jika panel sudah cocok dengan file, Anda akan melihat "No changes".
4. Terapkan. Tanpa `--yes`, perintah ini berupa **dry run** dan hanya mencetak daftar yang sama:

   ```bash
   sudo nexcmp config apply -f nexcmp.yaml --yes
   ```

5. Baca hasilnya: `applied`, `pending` (menunggu konfirmasi Anda), `skipped`, dan `errors`.

| Opsi | Arti |
|---|---|
| `-f <file>` | File YAML (diperlukan untuk `plan` dan `apply`). |
| `--yes` | Terapkan secara nyata. Tanpa itu, `apply` adalah dry run. |
| `--confirm-billing` | Terapkan juga bagian penagihan (`payments`, `currency`, `plans`). Tanpa itu, bagian tersebut akan dilewati. |
| `--section <name>` | Terapkan hanya bagian ini. Ulangi opsi ini untuk beberapa bagian. |
| `-o <file>` | Dengan `export`: tulis YAML ke sebuah file. |

Kode keluar adalah 0 ketika semuanya berhasil diterapkan atau tidak ada yang berubah, 1 ketika kesalahan dikembalikan, 2 untuk kesalahan penggunaan atau kunci.

### Rahasia {#secrets}

File tersebut menyimpan referensi alih-alih rahasia, seperti `password: secret://smtp_password`. Pada saat penerapan, nilai berasal dari variabel lingkungan bernama `NEXCMP_SECRET_` ditambah nama referensi dalam huruf kapital:

```bash
sudo -i
read -rs NEXCMP_SECRET_SMTP_PASSWORD && export NEXCMP_SECRET_SMTP_PASSWORD
read -rs NEXCMP_SECRET_STRIPE_SECRET_KEY && export NEXCMP_SECRET_STRIPE_SECRET_KEY
nexcmp config apply -f nexcmp.yaml --yes --confirm-billing
```

Jika referensi tidak memiliki nilai, rahasia yang sudah disimpan di panel akan **tetap disimpan**. Rahasia yang tidak pernah disimpan dan tidak disediakan akan tetap kosong.

| Nama referensi | Tujuannya |
|---|---|
| `smtp_password` | `email.smtp.password` |
| `telegram_bot_token` | `telegram.bot_token` |
| `stripe_secret_key`, `stripe_webhook_secret` | `payments.stripe` |
| `paypal_client_secret` | `payments.paypal.client_secret` |
| `binance_api_key`, `binance_api_secret` | `payments.crypto` |
| `sepay_api_token`, `sepay_webhook_secret` | `payments.bank` |
| `ai_provider_key` | `ai_provider.api_key` |

## Contoh file {#example-file}

```yaml
# NexCMP configuration. Preview: nexcmp config plan -f nexcmp.yaml
version: 1

branding:
  name: Example Cloud
  primary: "#1677ff"
  currency: usd
  seller_name: Example Cloud LLC

settings:
  brand_name: Example Cloud
  support_email: support@example.com
  default_lang: en
  invoice_prefix: EX
  company_name: Example Cloud LLC
  company_address: "1 Example Street, New York, NY"
  min_topup_cents: 500

email:
  smtp:
    host: smtp.example.com
    port: 587
    security: starttls
    username: mailer@example.com
    password: secret://smtp_password
    from_email: no-reply@example.com
    from_name: Example Cloud
    reply_to: support@example.com

telegram:
  enabled: true
  chat_id: "123456789"
  bot_token: secret://telegram_bot_token

modules:
  s3: true
  k8s: false

currency:
  site_currency: usd
  manual_rate_vnd: 0        # 0 = automatic

payments:
  stripe:
    mode: test
    publishable_key: pk_test_XXXX
    secret_key: secret://stripe_secret_key
    webhook_secret: secret://stripe_webhook_secret
  bank:
    bank_code: BANK
    account_number: "0000000000"
    account_name: EXAMPLE CLOUD LLC
    prefix: EX
    api_token: secret://sepay_api_token
  channels:
    pay_card_enabled: true

quotas:
  quota_enabled: true
  quota_max_vms_24h: 5
  quota_max_vms_30d: 30

zones:
  - slug: new-york
    name: New York
    country: US
    city: New York
    enabled: true
    is_default: true

plans:
  - slug: vps-1c-1g
    name: 1 vCPU, 1 GB RAM, 25 GB
    cpu: 1
    ram_mb: 1024
    disk_gb: 25
    hourly_usd: 0.0112
    cs_offering_id: OFFERING_ID
    enabled: true
    visible: true

ai_provider:
  enabled: true
  name: Example AI
  base_url: https://api.example.com/v1
  model: example-model
  fallback_models: [example-model-mini]
  reasoning_effort: low
  api_key: secret://ai_provider_key

legal:
  terms:
    en: |
      # Terms of service
      Your terms in simple markdown (no HTML).
  privacy:
    en: |
      # Privacy policy
      Your policy in simple markdown (no HTML).
```

Sebuah file dapat berisi bagian mana pun dari subset. Bagian yang Anda lewatkan tidak akan disentuh. File yang lebih besar dari 1 MB, `version: 1` yang hilang, nomor versi yang berbeda, atau bagian yang tidak dikenal akan ditolak sebelum ada yang berjalan.

## Bagian {#sections}

| Bagian | Yang dikendalikan | Catatan |
|---|---|---|
| `branding` | Nama merek (hingga 60 karakter), warna primer, mata uang tampilan (`usd` atau `vnd`), nama penjual. | Logo bukan bagian dari file; gunakan [branding page](https://nexcmp.com/id/docs/customers/branding/). |
| `settings` | Daftar tetap pengaturan umum: `brand_name`, `support_email`, `support_telegram_url`, `default_lang`, `require_email_verified`, `min_topup_cents`, `max_topup_cents`, `invoice_prefix`, `company_name`, `company_address`, `company_tax_id`, `auto_destroy_days`, `low_balance_cents`. | Kunci lainnya diabaikan. |
| `email.smtp` | Host SMTP, port, keamanan (`starttls`, `tls`, `none`), pengguna, kata sandi, nama dan alamat pengirim, balas-ke. | [SMTP and e-mail templates](https://nexcmp.com/id/docs/administration/smtp-and-emails/). Mengubah host, port, atau keamanan memerlukan kata sandi lagi. |
| `telegram` | Saluran pemberitahuan aktif atau nonaktif, chat ID, bot token. | [Telegram notifications](https://nexcmp.com/id/docs/administration/telegram-notifications/). |
| `modules` | Modul opsional aktif atau nonaktif (`key: true/false`). | Hanya tombol yang diizinkan oleh panel. Lihat [Modules](https://nexcmp.com/id/docs/infrastructure/modules/). |
| `currency` | Mata uang tampilan dan kurs manual USD ke VND (`0` otomatis, jika tidak 15000 hingga 50000). | Bagian penagihan. Lihat [Currency and exchange rates](https://nexcmp.com/id/docs/catalog/currency-and-exchange-rates/). |
| `payments` | Kredensial `stripe`, `paypal`, `crypto`, `bank` dan tombol `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Bagian penagihan. Lihat [Payment channels](https://nexcmp.com/id/docs/billing/payment-channels/). |
| `quotas` | Batas `quota_*`. | Lihat [Quotas](https://nexcmp.com/id/docs/billing/quotas/). |
| `zones` | Zona berdasarkan `slug` (wajib: `slug`, `name`, `country`; opsional `city`, `enabled`, `is_default`). | Zona baru dibuat. Zona yang sudah ada **tidak diubah** oleh file tersebut. Lihat [Zones](https://nexcmp.com/id/docs/infrastructure/zones/). |
| `plans` | Paket berdasarkan `slug` (wajib: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; opsional `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Bagian penagihan. Paket baru dibuat, paket yang sudah ada diperbarui berdasarkan slug. Harga dalam USD per jam. Lihat [Plans](https://nexcmp.com/id/docs/catalog/plans/). |
| `ai_provider` | Provider AI panel yang digunakan oleh AI Chat dan AI Agent pelanggan. | [AI provider](https://nexcmp.com/id/docs/ai/ai-providers/). |
| `legal` | Teks syarat dan privasi per bahasa (`en`, `vi`). | [Legal pages](https://nexcmp.com/id/docs/customers/legal/). |

Urutan penerapan adalah urutan di atas: item mirip infrastruktur sebelum paket.

## Aturan yang perlu diingat {#rules-to-remember}

- **Idempoten.** Menerapkan file yang sama dua kali tidak mengubah apa pun pada kali kedua. `plan` menampilkan "No changes".
- **Tanpa penghapusan.** File tidak pernah menghapus zona, paket, atau pengaturan. Menghapus entri dari file membiarkan panel seperti apa adanya.
- **Aturan keamanan normal tetap berlaku.** Dari baris perintah, setiap perubahan dikirim melalui pemeriksaan yang sama seperti perubahan API: cakupan dan aturan IP. Perubahan yang memerlukan konfirmasi (misalnya tombol tingkat situs) dilaporkan di bawah `pending` dengan pratinjau alih-alih langsung diterapkan, kecuali Anda meneruskan `--confirm-billing`, yang mengonfirmasi semuanya.
- **Klien AI tidak dapat membuka kunci penagihan.** Ketika `config_apply` dipanggil oleh klien MCP, `confirm_billing` diabaikan; perubahan uang menunggu persetujuan Anda.
- **Periksa sebelum Anda menerapkannya.** Skema JSON menjelaskan setiap field. Arahkan editor Anda ke sana, atau berikan ke AI agar menulis YAML yang valid: `https://cloud.example.com/v1/admin/agent/config/schema.json` (dapat dibaca publik).

### Bagian penagihan {#billing-sections}

`payments`, `currency`, dan `plans` mengubah harga atau jalur uang. `nexcmp config apply --yes` **mengabaikannya** kecuali Anda menambahkan `--confirm-billing`; perubahan tersebut kemudian dicantumkan di bawah `skipped` ("billing section - pass confirm_billing"). Flag tersebut adalah konfirmasi Anda: dengannya, setiap perubahan penagihan dalam file (dan perubahan lain yang akan meminta konfirmasi) diterapkan tanpa prompt kedua. Jalankan `plan` terlebih dahulu dan baca setiap baris yang ditandai `$`.

Ketika file yang sama diterapkan oleh AI (alat `config_apply` di klien MCP atau AI Chat), flag tersebut diabaikan, dan perubahan uang akan menunggu persetujuan Anda.

## Gunakan halaman Import/Export {#use-the-import-export-page}

1. Buka **System › Settings › Import/Export**.
2. Di bawah **Export** klik **Get current configuration**, lalu **Download .yaml** untuk menyimpan `nexcmp.yaml`. Rahasia muncul sebagai placeholder.
3. Di bawah **Import** pilih file, seret ke dalam kotak, atau tempel YAML.
4. Opsional: buka **Secrets that come with it (not in the file)** dan tambahkan nama serta nilai untuk setiap referensi, misalnya `smtp_password`.
5. Klik **Preview changes**. Tabel mengelompokkan perubahan menurut bagian; bagian yang terkait dengan uang membawa tag "Money-related". Hilangkan centang pada bagian yang tidak Anda inginkan.
6. Jika bagian yang berkaitan dengan keuangan tercantum, centang **Also apply money-related changes (prices, payment gateways, balances)**. Tanpa centang tersebut, bagian itu akan dilewati.
7. Klik **Apply selected**. Hasilnya menunjukkan apa saja yang diterapkan, dilewati, atau gagal. Perubahan yang dikembalikan sebagai menunggu konfirmasi akan muncul sebagai kartu konfirmasi; tekan **Confirm** pada kartu tersebut.

Tombol **JSON Schema** di kanan atas akan membuka skema.

![Halaman Import/Export dengan kartu Export dan kartu Import yang berisi YAML yang diekspor](https://nexcmp.com/id/docs/images/configure-with-ai/config-as-code-01-import-export.webp)

![Tabel pratinjau perubahan yang dikelompokkan menurut bagian dengan tag penagihan dan tombol Apply selected](https://nexcmp.com/id/docs/images/configure-with-ai/config-as-code-02-preview.webp)

## Jalankan alat apa pun dari baris perintah {#run-any-tool-from-the-command-line}

`nexcmp admin` menjalankan alat yang sama seperti asisten AI ([daftar alat](https://nexcmp.com/id/docs/configure-with-ai/mcp-admin/#tools)) dan mencetak JSON:

```bash
sudo nexcmp admin tools                       # name, scope and title of every tool
sudo nexcmp admin system_health
sudo nexcmp admin customers_search q=customer@example.com
sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}'
```

Argumen berupa pasangan `key=value` (nilai dibaca sebagai JSON saat diurai, jika tidak sebagai teks) atau satu objek `--json '{...}'`. Jika tindakan memerlukan konfirmasi, perintah akan mencetak pratinjau dan berhenti dengan kode keluar 3 serta "Nothing changed". Baca pratinjau tersebut, lalu jalankan kembali perintah yang sama dengan `--yes` untuk menerapkannya. Saat dijalankan sebagai root, perintah akan mendapatkan kunci 15 menit dengan semua cakupan, sehingga langkah konfirmasi adalah pengaman Anda; dengan `NEXCMP_KEY`, cakupan kunci Anda sendiri yang akan berlaku.

## Verifikasi {#verify}

1. `sudo nexcmp config plan -f nexcmp.yaml` tepat setelah `apply --yes` mencetak "No changes".
2. Di admin, halaman yang Anda ubah akan menampilkan nilai baru, dan **Logs › Admin actions** mencantumkan perubahan tersebut.
3. Menerapkan file yang sama lagi tidak akan mengubah apa pun.

## Batas & catatan {#limits-notes}

- File ini mencakup pengaturan di atas, bukan pelanggan, server, tagihan, atau sumber infrastruktur (koneksi CloudStack dan Proxmox). Hubungkan komponen tersebut menggunakan [AI Chat](https://nexcmp.com/id/docs/configure-with-ai/ai-chat-in-admin/) atau halaman admin.
- Zona dan paket dicocokkan dengan `slug`. Jangan ganti nama slug di dalam file: slug tersebut akan dibuat sebagai item baru.
- Paket yang sudah digunakan oleh pelanggan tidak dapat diubah ukurannya; buat paket baru sebagai gantinya.
- Jaga kerahasiaan file yang diekspor meskipun tidak berisi data rahasia: file tersebut mencantumkan harga, alamat, dan nama akun Anda.

## Pemecahan Masalah {#troubleshooting}

| Gejala | Penyebab | Solusi |
|---|---|---|
| `missing version: 1` | File tidak dimulai dengan `version: 1` | Tambahkan file tersebut. |
| `unsupported version 2` | File memiliki nomor versi yang berbeda | Panel ini hanya membaca versi 1. |
| `unknown section 'x' (known: ...)` | Kunci tingkat atas salah eja atau tidak didukung | Gunakan bagian di atas. |
| `YAML error: ...` | YAML tidak valid (indentasi, tab) | Perbaiki baris yang disebutkan oleh pesan tersebut. |
| `config is larger than 1 MB` | File terlalu besar | Pecah file tersebut dan gunakan `--section`. |
| `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | Perintah tidak menemukan kunci | Jalankan dengan `sudo`, atau ekspor `NEXCMP_KEY` dan pertahankan melalui sudo. |
| `panel not reachable` | Layanan panel tidak berjalan pada port default | Periksa `sudo nexcmp status`. |
| Baris penagihan di bawah `skipped` | Bagian penagihan memerlukan `--confirm-billing` | Tambahkan tanda (flag) tersebut dan tinjau baris `$` terlebih dahulu. |
| Item di bawah `pending` | Perubahan memerlukan konfirmasi | Buka **API & AI agents**, atau hasil Import/Export, lalu tekan **Confirm** pada kartu tersebut. |
| Rahasia tidak diperbarui | Tidak ada nilai `NEXCMP_SECRET_<NAME>` yang ditetapkan, sehingga rahasia yang disimpan tetap dipertahankan | Ekspor variabel tersebut dan terapkan kembali. |
| Entri di bawah `errors` dengan HTTP 403 `insufficient_scope` | Kunci tidak memiliki cakupan (scope) untuk bagian tersebut | Gunakan kunci yang memiliki cakupan tersebut, atau jalankan sebagai root. |
| Entri di bawah `errors` dengan HTTP 403 `demo_read_only` | Panel demo | Terapkan pada instalasi nyata. |