Soalan Lazim (FAQ) Kerjasama ServBay & Docker

Apabila menjalankan pembangunan web tempatan menggunakan ServBay, anda mungkin ingin menggabungkannya dengan Docker untuk persekitaran berasaskan kontena. FAQ ini memberikan penjelasan tentang isu lazim yang mungkin timbul bila ServBay berinteraksi dengan Docker pada macOS dan Windows, termasuk cara mengakses servis ServBay dari Docker serta mengkonfigurasi proxy terbalik untuk aplikasi dalam Docker menggunakan ServBay.

Q1: Kenapa ServBay mengubah fail hosts sistem saya? Bolehkah saya elakkan?

ServBay menambah entri pada fail hosts sistem anda (seperti mysite.servbay.demo 127.0.0.1) supaya anda boleh menggunakan nama domain khusus tempatan (seperti mysite.servbay.demo) untuk mengakses laman web pembangunan tempatan anda. Laman-laman ini sebenarnya beroperasi pada alamat 127.0.0.1 mesin anda.

Namun kerana mekanisme Docker, fail hosts dari sistem induk (macOS atau Windows) akan dibaca ke dalam kontena, menyebabkan mysite.servbay.demo diselesaikan ke 127.0.0.1, mengakibatkan Docker mengakses servis yang salah (iaitu servis dalam kontena itu sendiri).

Mekanisme utama:

• Semasa anda cipta laman web baru dalam ServBay dan beri domain (contohnya example.servbay.demo), ServBay akan automatik tetapkan domain itu ke 127.0.0.1.
• Ini adalah amalan lazim untuk akses domain mesra tempatan. Jika tidak ubah fail hosts, anda cuma boleh akses melalui http://127.0.0.1:PORT tanpa menggunakan domain tersuai.

Bolehkah dielakkan?

Secara teori, anda boleh padam sendiri entri yang ditambah oleh ServBay, tetapi ini akan menghalang anda daripada mengakses laman web tempatan dengan domain yang ditetapkan oleh ServBay, yang bertentangan tujuan utama ServBay untuk memudahkan pembangunan tempatan. Salah satu ciri utama ServBay adalah menyederhanakan proses penciptaan dan akses laman web tempatan. Jika anda tidak mahu ServBay urus entri hosts untuk domain tertentu, adalah lebih baik untuk tidak cipta laman web dalam ServBay bagi domain itu.

Untuk kebanyakan senario pembangunan tempatan, pengurusan automatik fail hosts oleh ServBay adalah perilaku yang diinginkan dan memudahkan workflow anda.

Q2: Bagaimana kontena Docker saya boleh akses website yang diurus oleh ServBay pada mesin hos dengan domain (seperti mysite.servbay.demo)?

Ini adalah keperluan biasa, tetapi mesti dikonfigurasikan dengan betul. Apabila ServBay menghoskan laman web pada sistem anda (macOS atau Windows) seperti mysite.servbay.demo yang diselesaikan ke 127.0.0.1, dalam kontena Docker, alamat 127.0.0.1 merujuk kepada kontena itu sendiri, bukan sistem hos.

Kaedah salah: Gunakan host.docker.internal secara langsung sebagai nama hos URL

Docker Desktop untuk Mac (dan Windows) menyediakan nama DNS istimewa host.docker.internal untuk menyelesaikan IP hos dari dalam kontena, namun tidak digalakkan menggunakan ini dalam URL untuk akses laman web ServBay (contohnya, akses http://host.docker.internal/ dan anggap ia akan ke mysite.servbay.demo).

Kerana jika berbuat demikian, permintaan HTTP ke pelayan web ServBay (seperti Caddy atau Nginx) akan menghantar header Host: host.docker.internal. Pelayan web ServBay bergantung kepada header ini untuk tentukan laman web sasaran. Jika Host bukan mysite.servbay.demo, pelayan tidak akan menghantar respons yang tepat, atau dalam senario HTTPS, ia menyebabkan kesilapan SNI (Server Name Indication) kerana sijil SSL dihasilkan untuk mysite.servbay.demo, bukannya host.docker.internal.

Kaedah betul: Tambahkan entri ke extra_hosts semasa memulakan kontena Docker

Untuk memastikan aplikasi dalam kontena Docker menghantar header Host yang betul dan dapat akses domain sebenar ServBay, tambahkan entri pada /etc/hosts kontena bagi domain itu yang menunjuk ke IP hos, sama ada melalui extra_hosts (dalam docker-compose.yml) atau --add-host (docker run), ditetapkan ke host.docker.internal atau lebih digalakkan, host-gateway.

• Guna docker run:

  docker run --add-host=mysite.servbay.demo:host-gateway ... your_image

  (host-gateway adalah khas dan akan diganti Docker dengan IP dalaman hos; untuk Docker 20.10+, ia adalah alias kepada host.docker.internal.)

• Guna docker-compose.yml:

  version: '3.8' # atau versi lebih baru
  services:
    myapp:
      image: your_image
      extra_hosts:
        - "mysite.servbay.demo:host-gateway" # atau "mysite.servbay.demo:host.docker.internal"
      # ... konfigurasi lain

Selepas konfigurasi:

1. Aplikasi dalam kontena boleh akses http://mysite.servbay.demo atau https://mysite.servbay.demo dan /etc/hosts akan selesaikan domain itu ke IP hos di macOS.
2. Permintaan dihantar ke pelayan web ServBay yang berjalan pada hos.
3. Header HTTP Host adalah benar (mysite.servbay.demo), membolehkan ServBay hantar respons dan sijil SSL yang tepat.

Q3: Bagaimana kontena Docker saya boleh sambung ke pangkalan data (seperti MySQL, PostgreSQL) atau servis lain yang diurus oleh ServBay?

Untuk akses pangkalan data atau servis TCP lain yang tidak bergantung kepada SNI, penggunaan host.docker.internal sebagai hostname adalah digalakkan dan berkesan.

Langkah:

1. Pastikan pakej pangkalan data di ServBay (atau servis lain) sudah berjalan dan membenarkan sambungan dari hos (konfigurasi lalai ServBay biasanya membenarkan ini untuk tujuan pembangunan).
2. Dalam Docker, konfigur sambungan pangkalan data:
   • Hostname: host.docker.internal
   • Port: Guna port yang ditetapkan dalam ServBay (contoh, MySQL: 3306; PostgreSQL: 5432)
   • Username/password: Guna kredensial yang anda tetapkan dalam ServBay.

Contoh (sambung ke MySQL dalam ServBay): Jika MySQL dalam ServBay berjalan pada port lalai 3306, konfigurasi aplikasi dalam container adalah:

• Host: host.docker.internal
• Port: 3306
• User: your_db_user
• Password: your_db_password

Q4: Jika kontena Docker akses laman HTTPS dalam ServBay (dengan CA ServBay), bagaimana nak buat kontena percayakan CA itu?

Jika anda sudah tetapkan domain (contoh secure.servbay.demo) dalam kontena Docker keluar ke host-gateway, dan domain menggunakan sijil SSL daripada ServBay User CA, kontena anda tidak percayakan CA ini secara lalai, menyebabkan sambungan SSL gagal.

Lokasi fail CA ServBay:

• Sijil Akar ServBay User CA:
  • macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
  • Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
• Fail PEM lengkap (CA ServBay, Public CA, Mozilla):
  • macOS (ARM): /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • macOS (Intel): /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
  • Windows: C:\ServBay\package\common\openssl\3.3\cacert.pem

Ringkasan solusi:

Ada beberapa cara untuk membuat kontena Docker percayakan ServBay User CA:

1. Kaedah 1: Percaya CA secara sistem semasa membina image (Dockerfile) - Sesuai untuk sistem yang fleksibel dan custom.
2. Kaedah 2: Percaya CA pada peringkat aplikasi semasa run (mount fail & set env) - Untuk aplikasi tertentu atau tanpa ubah image.
3. Kaedah 3: Percaya CA secara sistem semasa run (mount fail & custom startup command) - Untuk keperluan kepercayaan sistem tanpa membina image baru.

Kaedah 1: Percaya CA secara sistem semasa pembinaan image (Dockerfile)

Kaedah ini mengintegrasi CA kepada stor sistem semasa membina image Docker.

• Sedia fail CA: Salin ServBay User CA ke direktori build Docker (dengan Dockerfile):
  • macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
  • Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
• Contoh Dockerfile (Debian/Ubuntu):

  # Dockerfile
  FROM ubuntu:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
      update-ca-certificates && \
      rm -rf /var/lib/apt/lists/*

• Contoh Dockerfile (Alpine):

  # Dockerfile
  FROM alpine:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apk add --no-cache ca-certificates && update-ca-certificates

• Contoh Docker Compose:

  # docker-compose.yml
  version: '3.8'
  services:
    myapp:
      build:
        context: ./app_service # direktori dengan Dockerfile & ServBay-Private-CA-ECC-Root.crt
        dockerfile: Dockerfile
      extra_hosts: ["secure.servbay.demo:host-gateway"]

Kaedah 2: Percaya CA pada peringkat aplikasi semasa run (mount fail & set env)

Kaedah ini mount fail CA ke dalam container dan mengkonfigurasi environment variable pada aplikasi.

• Contoh docker-compose.yml:

  version: '3.8'
  services:
    myapp:
      image: some-base-image
      volumes:
        # contoh macOS
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
        # contoh Windows (ubah ikut OS)
        # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      environment:
        # Untuk Node.js:
        - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
        # Untuk Python (requests):
        # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
        # SSL_CERT_FILE am:
        # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
      extra_hosts: ["secure.servbay.demo:host-gateway"]

  Pastikan environment variable mengikut keperluan aplikasi anda.

Kaedah 3: Percaya CA secara sistem semasa run (mount fail & custom startup command)

Kaedah ini gabungkan mounting fail CA dan jalankan perintah update semasa container mula. Tidak perlu custom image tapi command jadi sedikit kompleks.

• Contoh docker-compose.yml (Debian/Ubuntu):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest # atau image yang support update-ca-certificates
      volumes:
        # mount SIJIL CA direct ke destinasi
        # contoh macOS
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
        # contoh Windows (ubah ikut OS)
        # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Override command untuk update CA dan jalankan aplikasi
      command: >
        sh -c "
          echo 'Sedang kemaskini sijil CA...' &&
          if command -v update-ca-certificates > /dev/null; then
            if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
            update-ca-certificates &&
            echo 'Sijil CA dikemaskini.'
          else
            echo 'Command update-ca-certificates tidak dijumpai, langkau update CA.'
          fi &&
          echo 'Mulakan aplikasi...' &&
          exec your_original_application_command_here # gantikan dengan aplikasi asal anda atau command
        "
      extra_hosts: ["secure.servbay.demo:host-gateway"]
      # Jika perlu root untuk update CA dan bukan untuk aplikasi, mungkin perlu entrypoint lebih kompleks
      # user: root # boleh tukar ke root, atau entrypoint custom

  Nota:
  • Kompleksiti: Ubah command/entrypoint mungkin rumit untuk image rasmi yang mempunyai process startup khusus.
  • Privilege: Perintah update CA biasanya perlukan root. Kalau container bukan root, kaedah ini mungkin gagal atau perlu privilege.
  • Kebergantungan: Perlu pastikan ca-certificates dan update-ca-certificates wujud dalam container (contoh di atas cuba install jika belum ada).
  • Masa startup: Setiap kali container bermula, semua check dan command akan dijalankan - boleh lambatkan masa mula.
  • Alpine Linux: Guna perintah apk add --no-cache ca-certificates && update-ca-certificates.

Kaedah pilihan?

• Jika membina image custom dan perlu CA dipercayai semua proses: Kaedah 1 adalah paling bagus.
• Jika hanya aplikasi tertentu perlu percayai CA dan tidak mahu ubah image: Kaedah 2 adalah mudah.
• Jika tidak mahu bina image dan perlu kepercayaan sistem-level pada peringkat mulakan container: Kaedah 3 adalah sesuai.

Jika guna sijil dari Public CA (contoh Let's Encrypt): ServBay yang menggunakan sijil dari CA awam (eg: Let's Encrypt melalui ACME), kebanyakan image Docker sudah percayakan CA sedemikian secara lalai, jadi tidak perlu apa-apa konfigurasi tambahan.

Q5: Bagaimana gunakan ServBay untuk tetapkan domain dan proxy terbalik ke aplikasi dalam Docker?

Mungkin anda menjalankan aplikasi dalam Docker (contoh, servis Node.js pada port 3000 dalam container) dan mahu akses melalui domain mesra pengguna (eg: myapp.servbay.demo) daripada pelayar pada hos, serta mengurus SSL melalui ServBay.

Langkah:

1. Jalankan Docker dengan pemetaan port ke 127.0.0.1 hos: Pastikan Docker anda expose port aplikasi ke sistem hos, diikat ke 127.0.0.1 (supaya hanya hos boleh akses, tidak terdedah terus ke rangkaian).

   # Contoh: App Docker listen port 3000, mapping ke hos 127.0.0.1:3001
   docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image

   Sekarang aplikasi boleh diakses pada hos melalui http://127.0.0.1:3001.

2. Tambah laman web baru dalam ServBay dan konfigurasi proxy:

   • Buka panel ServBay.
   • Klik "Tambah Website".
   • Domain: Masukkan domain pilihan, eg: myapp.servbay.demo.
   • Jenis Website: Pilih "Proxy Terbalik" pada dropdown.
   • Alamat IP: Isi 127.0.0.1.
   • Port: Masukkan port hos yang di-mapping tadi, eg: 3001.
   • Klik "Simpan" atau "Tambah".

3. (Pilihan) Aktifkan SSL: Selepas website ditambah, anda boleh buat tetapan SSL dari panel website. ServBay menyokong permohonan automatik sijil awam melalui ACME (eg: Let's Encrypt), atau guna ServBay User CA atau ServBay Public CA. SSL akan diurus oleh ServBay, manakala sambungan dari ServBay ke aplikasi Docker boleh kekal HTTP biasa (iaitu, http://127.0.0.1:3001).

4. Uji akses: Selepas semua tetapan, anda boleh lawati http://myapp.servbay.demo atau https://myapp.servbay.demo (jika SSL aktif) dari browser anda. ServBay akan redirect ke aplikasi dalam Docker.

Aliran kerja: Browser pengguna -> https://myapp.servbay.demo -> ServBay (urus SSL, rules proxy) -> http://127.0.0.1:3001 (port hos) -> aplikasi dalam kontena Docker.

Kesimpulan

ServBay sangat memudahkan pembangunan web tempatan di macOS dan Windows. Apabila digunakan bersama Docker:

• Untuk akses website ServBay dari Docker, gunakan extra_hosts atau --add-host supaya domain website menunjuk ke host-gateway, memastikan header Host betul dan mengelak masalah SNI.
• Untuk akses pangkalan data atau servis TCP lain dari Docker ke ServBay, gunakan host.docker.internal sebagai hostname server – ia mudah dan efektif.
• Untuk percaya CA SSL ServBay dari farm Docker, salin sijil CA ke dalam image dan kemaskini stor kepercayaan.
• Untuk gunakan proxy terbalik ServBay ke aplikasi dalam Docker, pilih "Proxy Terbalik" pada website ServBay, dan configure ke port host 127.0.0.1 yang dimapping dari Docker.

Sentiasa pastikan package relevan dalam ServBay (web server, pangkalan data) dan container Docker anda sudah dikonfigurasikan dengan betul dan sedang berjalan.