Mengonfigurasi aplikasi Node.js untuk Azure App Service

Artikel
06/01/2023

Aplikasi Node.js harus digunakan dengan semua dependensi NPM yang diperlukan. Mesin penyebaran App Service secara otomatis menjalankan npm install --production untuk Anda saat menyebarkan repositori Git, atau paket Zip dengan otomatisasi build diaktifkan. Namun, jika Anda menyebarkan file menggunakan FTP/S, Anda perlu mengunggah paket yang diperlukan secara manual.

Panduan ini menyediakan instruksi dan konsep utama untuk pengembang Node.js yang menyebarkan ke App Service. Jika Anda belum pernah menggunakan Azure App Service, ikuti mulai cepat Node.js dan tutorial Node.js dengan MongoDB dahulu.

Menampilkan versi Node.js

Untuk menampilkan versi Node.js saat ini, jalankan perintah berikut ini di Cloud Shell:

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

Untuk menampilkan semua versi Node.js yang didukung, navigasikan ke https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime atau jalankan perintah berikut di Cloud Shell:

az webapp list-runtimes --os windows | grep NODE

Untuk menampilkan versi Node.js saat ini, jalankan perintah berikut ini di Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

Untuk menampilkan semua versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell:

az webapp list-runtimes --os linux | grep NODE

Mengatur versi Node.js

Untuk mengatur aplikasi Anda ke versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell untuk mengatur WEBSITE_NODE_DEFAULT_VERSION ke versi yang didukung:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"

Catatan

Contoh ini menggunakan "sintaks tilde" yang direkomendasikan untuk menargetkan versi terbaru dari runtime Node.js 16 yang tersedia di App Service.

Karena runtime secara teratur di-patch dan diperbarui oleh platform, tidak disarankan untuk menargetkan versi/tambalan minor tertentu karena ini tidak dijamin akan tersedia karena potensi risiko keamanan.

Catatan

Anda harus mengatur versi Node.js di package.json proyek Anda. Mesin penyebaran berjalan dalam proses terpisah yang berisi semua versi Node.js yang didukung.

Untuk mengatur aplikasi Anda ke versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"

Pengaturan ini menentukan Node.js yang akan digunakan, baik pada runtime maupun selama pemulihan paket otomatis di Kudu.

Catatan

Anda harus mengatur versi Node.js di package.json proyek Anda. Mesin penyebaran berjalan dalam kontainer terpisah yang berisi semua versi Node.js yang didukung.

Mendapatkan nomor port

Aplikasi Node.js Anda perlu mendengarkan port yang tepat untuk menerima permintaan masuk.

Pada App Service di Windows, aplikasi Node.js dihosting dengan IISNode, dan aplikasi Node.js Anda harus mendengarkan port yang ditentukan dalam variabel process.env.PORT. Contoh berikut menunjukkan cara Anda melakukannya di aplikasi Express sederhana:

App Service menetapkan PORT variabel lingkungan di Node.js, dan meneruskan permintaan masuk ke kontainer Anda di nomor port tersebut. Untuk menerima permintaan, aplikasi Anda harus mendengarkan port tersebut menggunakan process.env.PORT. Contoh berikut menunjukkan cara Anda melakukannya di aplikasi Express sederhana:

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

Menyesuaikan otomatisasi build

Jika Anda menyebarkan aplikasi menggunakan Git, atau paket zip dengan otomatisasi build diaktifkan, langkah-langkah otomatisasi build App Service melalui urutan berikut:

Jalankan skrip kustom jika ditentukan oleh PRE_BUILD_SCRIPT_PATH.
Jalankan npm install tanpa bendera apa pun, yang mencakup skrip npm preinstall dan postinstall serta menginstal devDependencies.
Jalankan npm run build jika skrip build ditentukan di package.json Anda.
Jalankan npm run build:azure jika skrip build:azure ditentukan di package.json Anda.
Jalankan skrip kustom jika ditentukan oleh POST_BUILD_SCRIPT_PATH.

Catatan

Seperti yang dijelaskan dalam npm docs, skrip bernama prebuild dan postbuild masing-masing dijalankan sebelum dan sesudah build, jika ditentukan. preinstall dan postinstall masing-masing dijalankan sebelum dan sesudah install.

PRE_BUILD_COMMAND dan POST_BUILD_COMMAND adalah variabel lingkungan yang kosong secara default. Untuk menjalankan perintah pra-build, tentukan PRE_BUILD_COMMAND. Untuk menjalankan perintah pasca-build, tentukan POST_BUILD_COMMAND.

Contoh berikut menentukan dua variabel ke serangkaian perintah, yang dipisahkan oleh koma.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Untuk variabel lingkungan tambahan untuk mengkustomisasi automasi build, lihat Konfigurasi Oryx.

Untuk informasi lebih lanjut tentang cara App Service menjalankan dan membangun aplikasi Node.js di Linux, lihat Dokumentasi Oryx: Bagaimana aplikasi Node.js dideteksi dan dibuat.

Mengonfigurasi server Node.js

Kontainer Node.js dilengkapi dengan PM2, manajer proses produksi. Anda dapat mengonfigurasi aplikasi Anda untuk memulai dengan PM2, atau dengan NPM, atau dengan perintah kustom.

Alat	Tujuan
Menjalankan dengan PM2	Direkomendasikan - Penggunaan produksi atau pentahapan. PM2 menyediakan platform manajemen aplikasi layanan lengkap.
Menjalankan npm awal	Hanya penggunaan pengembangan.
Menjalankan perintah kustom	Baik pengembangan atau penahapan.

Menjalankan dengan PM2

Kontainer secara otomatis memulai aplikasi Anda dengan PM2 ketika salah satu file Node.js umum ditemukan di proyek Anda:

bin/www
server.js
app.js
index.js
hostingstart.js
Salah satu dari file PM2 berikut: process.json dan ecosystem.config.js

Anda juga dapat mengonfigurasi file awal kustom dengan ekstensi berikut:

File .js
File PM2 dengan ekstensi .json, .config.js, .yaml, atau .yml

Catatan

Mulai dari Node 14 LTS, kontainer tidak secara otomatis memulai aplikasi Anda dengan PM2. Untuk memulai aplikasi Anda dengan PM2, atur perintah mulai ke pm2 start <.js-file-or-PM2-file> --no-daemon. Pastikan untuk menggunakan argumen --no-daemon karena PM2 harus dijalankan di latar depan agar kontainer berfungsi dengan baik.

Untuk menambahkan file awal kustom, jalankan perintah berikut di Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

Menjalankan perintah kustom

App Service dapat memulai aplikasi Anda menggunakan perintah kustom, seperti perintah yang dapat dijalankan seperti run.sh. Misalnya, untuk menjalankan npm run start:prod, jalankan perintah berikut di Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

Menjalankan npm awal

Untuk memulai aplikasi Anda menggunakan npm start, pastikan skrip start ada di file package.json. Contohnya:

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

Untuk menggunakan package.json kustom dalam proyek Anda, jalankan perintah berikut di Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

Men-debug dari jarak jauh

Catatan

Debug jarak jauh saat ini dalam Pratinjau.

Anda dapat men-debug aplikasi Node.js dari jarak jauh di Visual Studio Code jika Anda mengonfigurasinya untuk dijalankan dengan PM2, kecuali jika Anda menjalankannya menggunakan .config.js,.yml, atau .yaml.

Dalam kebanyakan kasus, tidak diperlukan konfigurasi tambahan untuk aplikasi Anda. Jika aplikasi Anda dijalankan dengan file process.json (default atau khusus), aplikasi harus memiliki properti script di akan JSON. Contohnya:

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

Untuk menyiapkan Visual Studio Code untuk debug jarak jauh, instal ekstensi App Service. Ikuti instruksi pada halaman ekstensi dan masuk ke Azure di Visual Studio Code.

Di penjelajah Azure, temukan aplikasi yang ingin Anda debug, klik kanan dan pilih Mulai Debug Jarak Jauh. Klik Ya untuk mengaktifkannya untuk aplikasi Anda. App Service memulai proxy terowongan untuk Anda dan melampirkan debugger. Anda kemudian dapat membuat permintaan ke aplikasi dan melihat debugger berhenti di titik pemisah.

Setelah selesai men-debug, hentikan debugger dengan memilih Putuskan sambungan. Saat diminta, Anda harus mengeklik Ya untuk menonaktifkan debug jarak jauh. Untuk menonaktifkannya nanti, klik kanan aplikasi Anda lagi di penjelajah Azure dan pilih Nonaktifkan Debug Jarak Jauh.

Mengakses variabel lingkungan

Di App Service, Anda dapat menyetel pengaturan aplikasi di luar kode aplikasi. Kemudian Anda dapat mengaksesnya menggunakan pola Node.js standar. Misalnya, untuk mengakses pengaturan aplikasi yang disebut NODE_ENV, gunakan kode berikut:

process.env.NODE_ENV

Menjalankan Grunt/Bower/Gulp

Secara default, automasi pembuatan App Service menjalankan npm install --production saat mengenali aplikasi Node.js yang disebarkan melalui penyebaran Git atau Zip dengan automasi pembangunan diaktifkan. Jika aplikasi Anda memerlukan salah satu alat automasi populer, seperti Grunt, Bower, atau Gulp, Anda perlu menyediakan skrip penyebaran khusus untuk menjalankannya.

Agar repositori Anda dapat menjalankan alat ini, Anda perlu menambahkannya ke dependensi di package.json. Misalnya:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

Dari jendela terminal lokal, ubah direktori ke akar repositori Anda dan jalankan perintah berikut:

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

Akar repositori Anda sekarang memiliki dua file tambahan: .deployment dan deploy.sh.

Buka deploy.sh dan temukan bagian Deployment, yang terlihat seperti ini:

##################################################################################################################################
# Deployment
# ----------

Bagian ini diakhiri dengan menjalankan npm install --production. Tambahkan bagian kode yang Anda perlukan untuk menjalankan alat yang diperlukan di akhir bagian Deployment:

Bower
Gulp
Grunt

Lihat contoh dalam sampel MEAN.js, tempat skrip penyebaran juga menjalankan perintah npm install kustom.

Bower

Cuplikan ini menjalankan bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

Cuplikan ini menjalankan gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

Cuplikan ini menjalankan grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

Mendeteksi sesi HTTPS

Di App Service, penghentian SSL terjadi pada penyeimbang muatan jaringan, sehingga semua permintaan HTTPS mencapai aplikasi Anda sebagai permintaan HTTP yang tidak terenkripsi. Jika logika aplikasi Anda perlu memeriksa apakah permintaan pengguna dienkripsi atau tidak, periksa header X-Forwarded-Proto.

Kerangka kerja web populer memungkinkan Anda mengakses informasi X-Forwarded-* dalam pola aplikasi standar Anda. Di Express, Anda dapat menggunakan proxy kepercayaan. Contohnya:

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

Mengakses log diagnostik

Untuk mengakses log konsol yang dihasilkan dari dalam kode aplikasi Anda di App Service, aktifkan pembuatan log diagnostik dengan menjalankan perintah berikut di Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Nilai yang mungkin untuk --level adalah: Error, Warning, Info, dan Verbose. Setiap level berikutnya mencakup level sebelumnya. Misalnya: Error hanya menyertakan pesan kesalahan, dan Verbose menyertakan semua pesan.

Setelah pembuatan log diagnostik diaktifkan, jalankan perintah berikut untuk melihat aliran log:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Jika Anda tidak segera melihat log konsol, periksa lagi dalam 30 detik.

Catatan

Anda juga dapat memeriksa file log dari browser di https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Untuk menghentikan streaming log kapan saja, ketikkan Ctrl+C.

Anda dapat mengakses log konsol yang dihasilkan dari dalam kontainer.

Pertama, aktifkan pengelogan kontainer dengan menjalankan perintah berikut:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Ganti <app-name> dan <resource-group-name> dengan nama yang sesuai untuk aplikasi web Anda.

Setelah pengelogan kontainer diaktifkan, jalankan perintah berikut untuk melihat aliran log:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Jika Anda tidak segera melihat log konsol, periksa lagi dalam 30 detik.

Untuk menghentikan streaming log kapan saja, tekan Ctrl+C.

Anda juga dapat memeriksa file log di browser di https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Pantau dengan Application Insights

Application Insights memungkinkan Anda memantau performa, pengecualian, dan penggunaan aplikasi Anda tanpa membuat perubahan kode apa pun. Untuk melampirkan agen App Insights, buka aplikasi web Anda di Portal dan pilih Application Insights di Pengaturan, lalu pilih Aktifkan Application Insights. Selanjutnya, pilih sumber daya App Insights yang ada atau buat yang baru. Terakhir, pilih Terapkan di bagian bawah. Untuk melengkapi aplikasi web Anda menggunakan PowerShell, silakan lihat instruksi ini

Agen ini akan memantau aplikasi Node.js sisi server Anda. Untuk memantau JavaScript sisi klien Anda, tambahkan SDK JavaScript ke proyek Anda.

Untuk informasi lebih lanjut, lihat Catatan rilis ekstensi Application Insights.

Pemecahan Masalah

Saat aplikasi Node.js yang aktif berperilaku berbeda di App Service atau mengalami kesalahan, coba fitur berikut:

Mengalirkan aliran log.
Uji aplikasi secara lokal dalam mode produksi. App Service menjalankan aplikasi Node.js Anda dalam mode produksi, jadi Anda perlu memastikan bahwa proyek Anda berfungsi seperti yang diharapkan dalam mode produksi secara lokal. Contohnya:
- Tergantung pada package.json Anda, paket yang berbeda mungkin diinstal untuk mode produksi (dependencies vs. devDependencies).
- Kerangka kerja web tertentu dapat menyebarkan file statis secara berbeda dalam mode produksi.
- Kerangka kerja web tertentu mungkin menggunakan skrip startup kustom saat berjalan dalam mode produksi.
Jalankan aplikasi Anda di App Service dalam mode pengembangan. Misalnya, di MEAN.js, Anda dapat menyetel aplikasi ke mode pengembangan dalam runtime dengan mengatur pengaturan aplikasi NODE_ENV.

Anda tidak memiliki izin untuk melihat direktori atau halaman ini

Setelah menerapkan kode Node.js ke aplikasi Windows asli di App Service, Anda mungkin melihat pesan You do not have permission to view this directory or page. di browser saat menavigasi ke URL aplikasi Anda. Ini kemungkinan besar karena Anda tidak memiliki file web.config (lihat templat dan contoh).

Jika Anda menyebarkan file Anda dengan menggunakan Git, atau dengan menggunakan penyebaran ZIP dengan otomatisasi build diaktifkan, mesin penyebaran menghasilkan web.config di akar web aplikasi Anda (%HOME%\site\wwwroot) secara otomatis jika salah satu kondisi berikut adalah benar:

Akar proyek Anda memiliki package.json yang mendefinisikan skrip start yang berisi jalur file JavaScript.
Akar proyek Anda memiliki server.js atau app.js.

web.config yang dihasilkan disesuaikan dengan skrip awal yang terdeteksi. Untuk metode penyebaran lainnya, tambahkan web.config ini secara manual. Pastikan file diformat dengan benar.

Jika Anda menggunakan penyebaran ZIP (melalui Visual Studio Code, misalnya), pastikan untuk mengaktifkan otomatisasi build karena tidak diaktifkan secara default. az webapp up menggunakan penyebaran ZIP dengan otomatisasi build diaktifkan.

robot933456 dalam log

Anda mungkin melihat pesan berikut dalam log kontainer:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Anda dapat mengabaikan pesan ini dengan aman. /robots933456.txt adalah jalur URL dummy yang digunakan App Service untuk memeriksa apakah kontainer mampu melayani permintaan. Respons 404 hanya menunjukkan bahwa jalur tersebut tidak ada, tetapi ini memberi tahu App Service bahwa kontainernya sehat dan siap untuk menanggapi permintaan.

Langkah berikutnya

Tutorial: Aplikasi Node.js dengan MongoDB

Tanya Jawab Umum App Service Linux

Atau, lihat sumber daya tambahan:

Variabel lingkungan dan referensi pengaturan aplikasi

Mengonfigurasi aplikasi Node.js untuk Azure App Service

Menampilkan versi Node.js

Mengatur versi Node.js

Mendapatkan nomor port

Menyesuaikan otomatisasi build

Mengonfigurasi server Node.js

Menjalankan dengan PM2

Menjalankan perintah kustom

Menjalankan npm awal

Men-debug dari jarak jauh

Mengakses variabel lingkungan

Menjalankan Grunt/Bower/Gulp

Bower

Gulp

Grunt

Mendeteksi sesi HTTPS

Mengakses log diagnostik

Pantau dengan Application Insights

Pemecahan Masalah

Anda tidak memiliki izin untuk melihat direktori atau halaman ini

robot933456 dalam log

Langkah berikutnya

Sumber Daya Tambahan: