Manuel kurulum kılavuzu

Otomatik temel hazırlık akışı, etiketleme sunucusunu yalnızca birkaç tıklamayla Cloud Run'a dağıtmak için kullanılabilir. Etiketleme sunucusunu diğer ortamlarda hazırlamak istiyorsanız bunu manuel olarak yapabilirsiniz. Etiketleme sunucusu, bir Docker görüntüsünün içinde bulunan bir Node.js sunucusudur.

Etiketleme sunucusunun manuel olarak hazırlanması için sunucu tarafı etiketleme (SST) kümesinin ve bir önizleme sunucusunun ayrı olarak hazırlanması gerekir. SST kümesi, etiketleme sunucusuna yapılan tüm isteklerin giriş noktasıdır ve istekleri Sunucu tarafı etiketlemeye giriş bölümünde açıklandığı şekilde işler. Önizleme sunucusu, kapsayıcıları önizlemek için gereklidir.

Etiketleme sunucuları ile önizleme sunucusu arasındaki veri etkileşiminin bir resmi için Şekil 1'e bakın.

Etiketleme sunucuları ve önizleme sunucusu veri akışının şeması

Şekil 1: Etiketleme sunucuları ve önizleme sunucusu veri akışının şeması.

Bu kılavuzda aşağıdakiler açıklanmaktadır:

  • Docker resmi için kullanılabilen tüm ayarları görüntüleyin.
  • (İsteğe bağlı) BigQuery kimlik bilgilerini ekleme
  • SST Docker görüntüsünü kullanarak bir önizleme sunucusunu manuel olarak hazırlayın.
  • SST Docker görüntüsünü kullanarak SST kümesini manuel olarak sağlayın.
  • Önizleme sunucusunun ve SST kümesinin doğru şekilde yapılandırıldığından emin olun.
  • Sunucu temel hazırlığından sonra etiketleme sunucusu sürümünüzü güncel tutun.

Bu kılavuzdaki Docker komutlarını çalıştırmak için önce bilgisayarınıza Docker'ı yüklemeniz gerekir.

Docker görüntüsü için mevcut tüm ayarları görüntüleme

Etiketleme sunucusu Docker görüntüsünü şu URL'de bulabilirsiniz:

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Etiketleme sunucusu ve önizleme sunucusu, farklı işaretlerle aynı Docker resmini kullanır. Bu bölümde, Docker görüntüsüyle kullanılabilen tüm mevcut ayarların nasıl aranacağı açıklanmaktadır.

Kullanılabilir tüm ayarları görmek için docker komut satırı aracını kullanarak aşağıdakileri çalıştırın:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable server_bin.js --help

(İsteğe bağlı) Google Cloud kimlik bilgilerini ekleme

BigQuery veya Firestore API'yi Google Cloud dışında kullanmak için bu kaynaklara erişme yetkisi olan bir hizmet hesabı kimlik bilgisi sağlamanız gerekir.

  1. BigQuery erişimi için BigQuery Veri Düzenleyicisi rolüne veya Firestore erişimi için Cloud Datastore Kullanıcısı rolüne sahip bir hizmet hesabı oluşturmak ve JSON kimlik bilgilerini local_service_account_key.json dosya adıyla dışa aktarmak için bu kılavuzu uygulayın.
  2. JSON kimlik bilgisini, görüntünün erişebileceği bir birime bağlayın. docker run kullanarak kimlik bilgilerini resme monte etmek için -v local_service_account_key.json:/app/service_account_key.json değerini belirtebilirsiniz.
  3. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kimlik bilgisine yönlendirin.
  4. İsteğe bağlı olarak, etiketleme sunucusunun projeyi dolaylı olarak seçmesine izin vermek için GOOGLE_CLOUD_PROJECT ortam değişkeninde Google Cloud proje kimliğinizi belirtin.

  5. Sunucuyu çalıştırın. Aşağıdaki komut, etiketleme sunucusunu kimlik bilgileri eklenmiş şekilde çalıştırır:

    docker run -v local_service_account_key.json:/app/service_account_key.json \
-p 8080:8080 \
-e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
-e GOOGLE_CLOUD_PROJECT='<your project id>' \
-e CONTAINER_CONFIG='<config string>' \
gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Etiketleme sunucusunun dağıtıldığı sisteme bağlı olarak, kimlik bilgilerini bağlamanın farklı yolları olabilir. Örneğin, Kubernetes ve Docker Swarm, gizli anahtarların yönetimi için kılavuzlar sunar. Daha fazla bilgi için ilgili sistemin kılavuzunu inceleyin.

Kimlik bilgilerinizi korumak için en iyi uygulamaları uyguladığınızdan emin olun.

Önizleme sunucusunu manuel olarak hazırlama

Önizleme sunucusu, sunucu kapsayıcısını önizlemenizi sağlar. Önizleme sunucusunu çalıştırmak için Docker görüntüsünü, Docker ortamına iletilen aşağıdaki ortam değişkenleriyle çalıştırın.

Zorunlu ayarlar

  • CONTAINER_CONFIG: Sunucu kapsayıcısı için yapılandırma dizesi. Etiket Yöneticisi'nde sunucu kapsayıcı çalışma alanınıza gidin ve sayfanın sağ üst kısmındaki kapsayıcı kimliğini tıklayın. Kapsayıcı Yapılandırması değerini bulmak için Etiketleme sunucusunu manuel olarak hazırlayın'ı tıklayın.

  • RUN_AS_PREVIEW_SERVER: Sunucuyu önizleme sunucusu olarak ayarlamak için bu değeri true olarak ayarlayın.

Docker komut satırı aracının kullanımına örnek

Yerel olarak bir önizleme sunucusu sağlamak için aşağıdakileri çalıştırın:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

http://localhost:8080/healthz adresine gönderilen bir istek için 200 yanıtı görebilirsiniz. İsterseniz bağlantı noktasını değiştirmek için PORT ortam değişkenini kullanabilirsiniz.

En iyi uygulamalar

  • Tam olarak 1 önizleme sunucusu dağıtmanız gerekir. Otomatik ölçeklendirmeyi 1 örnekten fazla olacak şekilde yapılandırmayın.
  • Docker'ı kullanarak bir önizleme sunucusu oluşturduktan sonra, önizleme sunucusunu işaret edecek bir HTTPS URL'si yapılandırın. Bu, SST kümesini ayarlamak için gereklidir.
  • Yük dengeleyicinizin veya CDN'nizin zaman aşımı 20 saniyeden uzun olmalıdır. Aksi takdirde önizleme modu düzgün çalışmaz.

Sunucu tarafı etiketleme kümesini manuel olarak hazırlama

SST kümesi giriş noktası olarak hizmet eder, önizleme isteklerini önizleme sunucusuna proxy olarak iletir ve Sunucu tarafı etiketlemeye giriş bölümünde açıklandığı gibi diğer tüm isteklerini işler. Docker'ı destekleyen herhangi bir ortamda SST kümesi sağlamak için etiketleme sunucusu Docker görüntüsüyle aşağıdaki gerekli ayarları kullanın.

Zorunlu ayarlar

  • CONTAINER_CONFIG: Sunucu kapsayıcısı için yapılandırma dizesi. Etiket Yöneticisi'nde sunucu kapsayıcı çalışma alanınıza gidin ve sayfanın sağ üst kısmındaki kapsayıcı kimliğini tıklayın. Container Config değerini bulmak için Etiketleme sunucusunun manuel olarak temel hazırlığını yap'ı tıklayın.

  • PREVIEW_SERVER_URL - Önizleme sunucusunun HTTPS URL'si. Bu ayar yalnızca etiketleme sunucusunu sağlama için ayarlanmalıdır ve önizleme sunucusunu sağlama için gerekli değildir. Önizleme sunucusunu ayarlamayla ilgili kılavuz için yukarıdaki bölüme bakın.

Docker komut satırı aracını kullanan örnek

Tek bir etiketleme sunucusunu yerel olarak sağlamak için aşağıdaki komutu çalıştırın:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

http://localhost:8080/healthz adresine gönderilen bir istek için 200 yanıtı görürsünüz. İsteğe bağlı olarak, bağlantı noktasını değiştirmek için PORT ortam değişkenini kullanın.

En iyi uygulamalar

  • Sunucu tarafı etiketleme sunucuları tek bir sunucu veya küme olarak hazırlanabilir. Daha iyi kullanılabilirlik, ölçeklenebilirlik ve performans için küme olarak temel hazırlığı yapmanızı öneririz. Küme olarak temel hazırlığı yaparken her sunucu örneğinin aynı CONTAINER_CONFIG ve PREVIEW_SERVER_URL ortam değişkenleriyle yapılandırılması gerektiğini lütfen unutmayın.
  • Etiketleme sunucunuzu mevcut web sitenizin aynı kaynakta (en iyi uygulama) veya alt alan adında barındırdığınızdan emin olun. Örneğin, uygulamanız example.com adresinde web trafiği sunuyorsa etiketleme sunucunuz için example.com/analytics gibi bir yol kullanın. Özel alan yapılandırması hakkında daha fazla bilgi edinin.
  • Docker'ı kullanarak bir SST kümesi oluşturduktan sonra SST kümesini işaret edecek bir HTTPS URL'si yapılandırın.
  • Sunucularınızın SST için en son kod güncellemelerine sahip olduğundan emin olmak üzere düzenli olarak yeniden başlattığınızdan emin olun. Aksi takdirde, yeni SST özellikleriyle uyumlu olmayan işlevler görebilirsiniz. Sunucunun ne zaman yeniden başlatılması gerektiğini öğrenmenin bir yolu, canlılık kontrolleri ayarlamaktır. Bu konu aşağıda daha ayrıntılı olarak açıklanmıştır. Ayrıca, sunucu kapsayıcınızda yayınlanan güncellemelerin yeniden başlatma olmadan da uygulanacağını lütfen unutmayın.
  • Etkinlik kontrolleri ayarlamak için etiketleme sunucularınızdaki mevcut /healthz uç noktasını (ör. https://analytics.example.com/healthz) kullanın. Durumu iyi olmayan bir yanıt, sunucunun yeniden başlatılması gerektiğini gösterir.
  • Docker kapsayıcısı, /healthz uç noktasını düzenli olarak sorgulayan varsayılan bir durum denetimi komutu (HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]) içerir. Docker sağlık kontrolünü kullanıyorsanız Docker talimatlarını uygulayarak ayarları değiştirebilirsiniz.
  • Önizleme sunucusu ve etiketleme sunucusu aynı kaynaktaysa önizleme sunucusunu etiketleme sunucusundan farklı bir yolda barındırın. Yolu da dahil ederek PREVIEW_SERVER_URL değerini belirtin.
  • Yapılandırılmış sunucularda en fazla 1 vCPU bulunmalıdır. Ek vCPU'lar kullanılmaz ve otomatik ölçeklendirmeyi olumsuz etkiler.

Doğrulama

Sunucu kapsayıcısı URL'sini yapılandırma

Etiket Yöneticisi'nde sunucu kapsayıcınıza gidin. Yönetici > Kapsayıcı Ayarları bölümünde, etiketleme sunucusunun URL'sini Sunucu kapsayıcısı URL'si alanına girin ve Kaydet'i tıklayın.

Önizleme moduyla doğrula

Etiket Yöneticisi çalışma alanında, Önizle'yi tıklayarak kapsayıcıyı önizleyin ve önizleme sayfasının yüklendiğini kontrol edin. Başka bir tarayıcı sekmesinde, Sunucu kapsayıcı URL'sindeki herhangi bir yola gidin. Önizleme sayfasında gönderilen istek gösteriliyorsa her şey doğru şekilde ayarlanmıştır.

Birden fazla alt alan adını tek bir etiketleme sunucusuyla eşlediyseniz ve her alt alan adında önizleme yapmak istiyorsanız Yönetici > Kapsayıcı Ayarları bölümünde ek Sunucu kapsayıcı URL'leri ekleyin. Birden fazla URL sağlanırsa tüm URL yolları eşleşmelidir (alan adından sonra gelen bilgi dizesi). Örneğin, example.com/abc ve example2.com/abc'te önizleme yapabilirsiniz ancak example.com/abc ve example2.com/def'de önizleme yapamazsınız. Birden fazla URL eklenirse Önizle düğmesinin yanında, önizlenecek URL'yi seçmenize olanak tanıyan bir simge görürsünüz.

Etiketleme sunucusu sürümünü güncelleme

gtm-cloud-image resmi, Node.js'i ve etiketleme sunucusunun çalışması için gereken kitaplıkları içerir. Docker resmi, güvenlik düzeltmeleri ve yeni özellikler için düzenli olarak güncellenir. Etiketleme sunucunuzu en azından her büyük sürüm sürümü için güncellemenizi öneririz (ör. 1.x.x sürümünden 2.x.x sürümüne yükseltme).

Docker görüntünüzü güncellemek için:

  1. gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable adresindeki mevcut resim sürümünü alın.
  2. Sunucunuzu önceki dağıtımla aynı ayarları kullanarak dağıtın.
  3. Tek önizleme sunucusunu ve kümedeki tüm etiketleme sunucularını güncelleyin.
  4. Eski sunucuları kapatın.

Güncellemenin başarılı olduğunu doğrulamak için:

  1. Yeni bir hata ayıklama oturumu başlatmak ve ayrı bir sekmede istek göndermek için sunucu kapsayıcınızda Önizleme düğmesini tıklayın.
  2. Özet bölümünde Konsol sekmesini seçin ve etiketleme sunucusunu güncellemenizi isteyen bir mesaj olmadığından emin olun.

Etiket Yöneticisi, etiketleme sunucunuzu güncellemenizin istendiği mesajları, sunucu başarıyla güncellendikten bir gün sonraya kadar gösterebilir. Ancak önizleme sayfasında, etiketleme sunucusu sürümü hakkında güncel bir mesaj gösterilir.