#Panduan Instalasi dan Migrasi Upgrade: Menggunakan NocoBase CLI

NocoBase CLI versi baru (nb) menyatukan operasi instalasi, koneksi, memulai, menghentikan, melihat log, upgrade, dan pembersihan ke dalam satu set perintah. Dibandingkan dengan dokumentasi lama yang dipelihara secara terpisah berdasarkan Docker, create-nocobase-app, dan kode sumber Git, CLI lebih cocok untuk pengembangan lokal, pemeliharaan lingkungan testing, serta integrasi dan kolaborasi AI Agent.

Artikel ini berlaku untuk skenario berikut:

• Anda sedang memasang atau mengupgrade NocoBase berdasarkan dokumentasi lama, dan ingin beralih ke metode CLI baru.
• Anda sudah memiliki NocoBase yang dideploy dengan cara lama, dan ingin CLI mengelola atau menghubungkannya.
• Anda perlu menyiapkan lingkungan NocoBase yang dapat dihubungkan dan dipelihara untuk AI Agent.

#Perbedaan Antara Cara Lama dan Cara Baru

Cara lama memisahkan dokumentasi berdasarkan sumber instalasi, setiap sumber memerlukan eksekusi perintah download, konfigurasi, instalasi, memulai, dan upgrade secara terpisah.

Dokumentasi Instalasi Lama

• Instalasi Docker
• Instalasi create-nocobase-app
• Instalasi Kode Sumber Git

Dokumentasi Upgrade Lama

• Upgrade Instalasi Docker
• Upgrade Instalasi create-nocobase-app
• Upgrade Instalasi Kode Sumber Git

Cara baru menggunakan nb init sebagai entry point, mencatat sumber aplikasi, direktori run, direktori storage, database, dan informasi koneksi API dengan satu env CLI. Selanjutnya, baik sumber Docker, npm, maupun Git, sebisa mungkin menggunakan satu set perintah nb app, nb source, nb db yang sama untuk pemeliharaan.

#Memasang CLI

npm install -g @nocobase/cli@beta
nb --version

Setelah instalasi, Anda dapat melihat bantuan:

nb --help
nb init --help

#Memasang NocoBase dengan Cara Baru

#Disarankan: Menggunakan Wizard Visual

nb init --ui

Wizard akan memandu Anda untuk memilih:

• Buat aplikasi baru atau hubungkan aplikasi yang sudah ada
• Sumber instalasi: Docker, npm, Git
• Versi NocoBase
• Gunakan database bawaan atau database eksternal
• Akun dan password administrator

#Menggunakan Wizard Interaktif Terminal

nb init

#Menggunakan Perintah Non-interaktif

Metode instalasi default adalah Docker, dan menggunakan database PostgreSQL bawaan:

nb init --yes --env app1

Pasang versi tertentu menggunakan Docker:

nb init --yes --env app1 --source docker --version beta

Pasang menggunakan npm:

nb init --yes --env app1 --source npm --version beta --app-port 13080

Pasang menggunakan kode sumber Git:

nb init --yes --env app1 --source git --version beta

Gunakan kode sumber Git dan tentukan tipe database bawaan:

nb init --yes --env app1 --source git --version beta --db-dialect mysql

Hubungkan aplikasi NocoBase yang sudah ada:

# Default menggunakan autentikasi OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# Menggunakan autentikasi Token
nb init --yes --env app1 \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

#Upgrade dengan Cara Baru

Pada cara lama, perintah upgrade Docker, create-nocobase-app, dan kode sumber Git berbeda; CLI baru menyatukannya menjadi:

nb app upgrade -e app1

Jika hanya ingin menjalankan proses upgrade dengan kode sumber atau image yang sudah diunduh, tanpa menarik kode atau image baru:

nb app upgrade -e app1 --skip-code-update

Atau gunakan singkatan:

nb app upgrade -e app1 -s

#Perintah Pemeliharaan Umum

nb app down secara default akan menghentikan aplikasi, dan menghapus container run yang dikelola CLI dan file aplikasi lokal, namun akan mempertahankan data storage dan konfigurasi env. Saat menghapus seluruh konten harus dikonfirmasi secara eksplisit:

nb app down -e app1 --all --yes

#Perintah Pengembangan Harian

nb source digunakan untuk mengelola proyek kode sumber lokal, terutama berlaku untuk env source npm dan Git.

#NB_CLI_ROOT dan Struktur Direktori

CLI akan menyimpan konfigurasi global dan file aplikasi lokal di direktori yang sesuai dengan NB_CLI_ROOT.

Secara default, NB_CLI_ROOT adalah direktori home pengguna saat ini, yaitu path yang dikembalikan oleh Node.js os.homedir(). Misalnya di macOS biasanya /Users/<user>. Oleh karena itu, jika tidak melakukan konfigurasi tambahan, file yang dihasilkan oleh nb init --yes --env app1 biasanya berada di:

~
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

Anda juga dapat secara eksplisit menentukan NB_CLI_ROOT:

export NB_CLI_ROOT=/your/workspace

Setelah diatur, file konfigurasi dan direktori aplikasi default akan ditempatkan di direktori tersebut:

/your/workspace
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

Di mana:

• .nocobase/config.json menyimpan informasi env, lingkungan saat ini, alamat API, path kode sumber, path storage, konfigurasi database, dan lainnya.
• <envName>/source adalah direktori kode sumber atau aplikasi yang dikelola CLI.
• <envName>/storage adalah direktori storage aplikasi yang dikelola CLI.

CLI saat ini hanya menggunakan scope konfigurasi global. Jika perlu menyesuaikan lokasi penyimpanan konfigurasi dan file aplikasi lokal, harap atur NB_CLI_ROOT.

Saat melihat dan menemukan aplikasi, prioritaskan penggunaan nb env list dan nb env info:

# Lihat env yang dikonfigurasi dan status autentikasi API
nb env list

# Lihat informasi detail dari env tertentu
nb env info app1

nb env list ditujukan untuk gambaran umum cepat, di mana App Status adalah status autentikasi yang diperoleh setelah mengakses API aplikasi melalui Token/kredensial OAuth yang disimpan, dan tidak lagi menampilkan status database. Saat perlu melihat status run database bawaan, harap gunakan:

nb db ps -e app1

Hanya saat perlu mengganti env default, baru gunakan:

nb env use app1

#Migrasi dari Cara Lama ke CLI

Migrasi memiliki dua strategi: menghubungkan aplikasi yang sudah ada, atau memasukkan direktori aplikasi lokal ke dalam manajemen CLI. Jika aplikasi lama Anda sudah berjalan stabil, disarankan menggunakan "menghubungkan aplikasi yang sudah ada" terlebih dahulu, risikonya paling rendah.

#Cara Pertama: Menghubungkan Aplikasi yang Sudah Ada

Berlaku untuk NocoBase yang sudah dideploy melalui Docker, create-nocobase-app, kode sumber Git, atau di server.

# Default menggunakan autentikasi OAuth
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# Menggunakan autentikasi Token
nb init --yes --env "app$RANDOM" \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

Cara ini hanya menyimpan koneksi API, CLI tidak akan mengambil alih memulai, menghentikan, upgrade, direktori kode sumber, atau direktori storage dari aplikasi lama. Cocok untuk membuat AI Agent atau perintah API CLI menghubungkan aplikasi yang sudah ada.

Jika perlu me-refresh autentikasi:

nb env auth app1

#Cara Kedua: Buat Env CLI Baru Lalu Migrasi File

Berlaku untuk skenario yang ingin selanjutnya mengelola aplikasi lokal dengan nb app dan nb source.

Sebelum migrasi, harap selesaikan terlebih dahulu:

1. Hentikan aplikasi lama.
2. Backup database lama.
3. Backup direktori storage lama.
4. Catat variabel lingkungan kunci dari aplikasi lama, seperti APP_KEY, TZ, DB_*, DB_UNDERSCORED.

#Migrasi Instalasi Docker Lama

Cara Docker lama biasanya menempatkan data aplikasi di storage dalam direktori proyek:

/old-docker-project
├── docker-compose.yml
└── storage

Disarankan menentukan NB_CLI_ROOT baru terlebih dahulu, lalu gunakan CLI untuk membuat env Docker baru. Contoh di bawah ini mengasumsikan NB_CLI_ROOT adalah /your/workspace.

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app2 --source docker --version beta
nb app stop -e app2

Env baru secara default akan menggunakan direktori berikut:

/your/workspace
└── app2
    ├── source
    └── storage

Kemudian salin storage lama ke /your/workspace/app2/storage, dan pastikan koneksi database dan konfigurasi seperti APP_KEY konsisten dengan lingkungan lama.

Setelah penyalinan selesai dan konfigurasi database dikonfirmasi, baru jalankan aplikasi:

nb app start -e app2
nb app logs -e app2

#Migrasi Instalasi create-nocobase-app atau Kode Sumber Git Lama

Cara npm/Git lama biasanya menempatkan kode sumber, .env, dan storage di direktori proyek yang sama:

/old-nocobase
├── .env
├── package.json
├── packages
└── storage

Disarankan menentukan NB_CLI_ROOT baru terlebih dahulu, lalu buat env npm atau Git baru. Contoh di bawah ini mengasumsikan NB_CLI_ROOT adalah /your/workspace.

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app3 --source git --version beta
nb app stop -e app3

Kemudian migrasikan sesuai kebutuhan:

• Migrasikan kode sumber Plugin kustom dari proyek lama ke direktori yang sesuai di /your/workspace/app3/source.
• Salin storage dari proyek lama ke /your/workspace/app3/storage.
• Sinkronkan konfigurasi kunci dari .env lama ke konfigurasi env CLI atau parameter inisialisasi.
• Saat menggunakan database asli, harap matikan database bawaan dan isi informasi koneksi database lama saat inisialisasi.

Contoh inisialisasi menggunakan database eksternal:

nb init --yes --env app3 --source git --version beta \
  --no-builtin-db \
  --db-dialect postgres \
  --db-host 127.0.0.1 \
  --db-port 5432 \
  --db-database nocobase \
  --db-user nocobase \
  --db-password nocobase

Setelah migrasi selesai, jalankan dan lihat log:

nb app start -e app3
nb app logs -e app3

#Tabel Cepat Migrasi Perintah Lama

#Tautan Terkait

• Panduan Integrasi AI Agent
• Referensi Perintah NocoBase CLI
• Perbandingan Metode Instalasi dan Versi
• Instalasi dan Upgrade Plugin