Mengonfigurasi aplikasi Node.js untuk Azure App Service

Artikel
10/16/2024

Node.js aplikasi harus disebarkan dengan semua dependensi npm yang diperlukan. Mesin penyebaran App Service secara otomatis berjalan npm install --production untuk Anda saat Anda menyebarkan repositori Git, atau saat Anda menyebarkan 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, kami tidak menyarankan Agar Anda menargetkan versi/patch minor tertentu karena ini tidak dijamin 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 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 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}`)
})

Mengkustomisasi otomatisasi build

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

Jalankan skrip kustom, jika skrip 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.
Menjalankan skrip kustom jika ditentukan oleh POST_BUILD_SCRIPT_PATH.

Catatan

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

PRE_BUILD_COMMAND dan POST_BUILD_COMMAND merupakan 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 menggunakan dua variabel untuk menentukan serangkaian perintah, 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 informasi tentang variabel lingkungan tambahan untuk menyesuaikan otomatisasi 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 untuk memulai dengan PM2, dengan npm start, atau dengan perintah kustom.

Alat	Tujuan
Menjalankan dengan PM2	Direkomendasikan - Penggunaan produksi atau pentahapan. PM2 menyediakan platform manajemen aplikasi layanan lengkap.
Jalankan dengan npm start	Hanya penggunaan pengembangan.
Jalankan dengan 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 file PM2 berikut: process.json atau 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>"

Jalankan dengan 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"

Jalankan dengan npm start

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

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. Pilih Ya untuk mengaktifkan penelusuran kesalahan jarak jauh 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 memilih Ya untuk menonaktifkan penelusuran kesalahan 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, otomatisasi build App Service berjalan npm install --production saat mengenali bahwa aplikasi Node.js disebarkan melalui Git, atau melalui penyebaran Zip dengan otomatisasi build 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 root 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

Dalam App Service, penghentian TLS/SSL terjadi pada load balancer jaringan, sehingga semua permintaan HTTPS mencapai aplikasi Anda sebagai permintaan HTTP yang tidak terenkripsi. Jika logika aplikasi Anda perlu memeriksa apakah permintaan pengguna dienkripsi, periksa X-Forwarded-Proto header.

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.

Penulisan ulang URL

Saat menyebarkan aplikasi Node.js di Azure App Service untuk Linux, Anda mungkin perlu menangani penulisan ulang URL langsung dalam aplikasi Anda. Ini sangat berguna untuk memastikan pola URL tertentu dialihkan ke titik akhir yang benar tanpa mengandalkan konfigurasi server web. Ada beberapa cara untuk menyelesaikan penulisan ulang URL dalam Node.js. Salah satu contohnya adalah melalui paket express-urlrewrite .

Memantau dengan Application Insights

Application Insights memungkinkan Anda memantau performa, pengecualian, dan penggunaan aplikasi Anda tanpa membuat perubahan kode apa pun. Untuk melampirkan agen Application Insights, buka aplikasi web Anda di portal, pilih Application Insights di bawah Pengaturan, lalu pilih Aktifkan Application Insights. Selanjutnya, pilih sumber daya Application Insights yang sudah ada atau buat sumber daya baru. Terakhir, pilih Terapkan di bagian bawah. Untuk melengkapi aplikasi web Anda menggunakan PowerShell, 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. Misalnya:
- Bergantung pada package.json Anda, paket yang berbeda mungkin diinstal untuk mode produksi (dependencies vs. devDependencies).
- Kerangka kerja web tertentu mungkin 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 mengatur aplikasi ke mode pengembangan saat runtime dengan mengatur NODE_ENV pengaturan aplikasi.

Anda tidak memiliki izin untuk melihat direktori atau halaman ini

Setelah menyebarkan 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. Perlindungan pembersihan 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

Azure App Service di FAQ Linux

Atau, lihat sumber daya tambahan:

Variabel lingkungan dan referensi pengaturan aplikasi

Bagikan melalui

Mengonfigurasi aplikasi Node.js untuk Azure App Service

Menampilkan versi Node.js

Mengatur versi Node.js

Mendapatkan nomor port

Mengkustomisasi otomatisasi build

Mengonfigurasi server Node.js

Menjalankan dengan PM2

Jalankan dengan perintah kustom

Jalankan dengan npm start

Men-debug dari jarak jauh

Mengakses variabel lingkungan

Menjalankan Grunt/Bower/Gulp

Bower

Gulp

Grunt

Mendeteksi sesi HTTPS

Mengakses log diagnostik

Penulisan ulang URL

Memantau dengan Application Insights

Pemecahan Masalah

Anda tidak memiliki izin untuk melihat direktori atau halaman ini

robot933456 dalam log

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: