Manuel kurulum kılavuzu

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

Etiketleme sunucusunun manuel olarak temel hazırlığının yapılması için sunucu tarafı etiketleme (SST) kümesinin ve önizleme sunucusunun ayrı olarak temel hazırlığı gerekir. SST kümesi, etiketleme sunucusuna yapılan tüm istekler için giriş noktasıdır ve istekleri, Sunucu tarafı etiketlemeye giriş bölümünde açıklandığı gibi ele alır. Bir kapsayıcıyı önizlemek için önizleme sunucusuna ihtiyacınız vardır.

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

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

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

Bu kılavuzda aşağıdakilerin nasıl yapılacağı açıklanmaktadır:

  • Docker görüntüsü için mevcut tüm ayarları görüntüleyin.
  • (İsteğe bağlı) BigQuery kimlik bilgilerini ekleyin
  • 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ığını doğrulayın.
  • Sunucu temel hazırlığını yaptıktan sonra etiketleme sunucunuzun sürümünü 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öster

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

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

Etiketleme sunucusu ve önizleme sunucusu aynı Docker görüntüsünü farklı işaretlerle kullanır. Bu bölümde, Docker görüntüsüyle kullanılabilecek tüm ayarları nasıl arayacağınızdan bahsedeceğiz.

Mevcut tüm ayarları görmek için docker komut satırı aracını kullanarak aşağıdaki komutu ç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 ekleyin

BigQuery veya Firestore API'yi Google Cloud dışında kullanmak için bu kaynaklara erişim 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 olan bir hizmet hesabı oluşturmak ve JSON kimlik bilgilerini local_service_account_key.json dosya adıyla dışa aktarmak için bu kılavuzdaki adımları uygulayın.
  2. JSON kimlik bilgisini, görüntünün erişebileceği bir birime ekleyin. docker run kullanarak, kimlik bilgilerini görüntüye eklemek için -v local_service_account_key.json:/app/service_account_key.json öğesini 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 projenizin kimliğini belirtin.
  5. Sunucuyu çalıştırın. Aşağıdaki komut, etiketleme sunucusunu kimlik bilgileri eklenmiş olarak ç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 hangi sisteme dağıtıldığına bağlı olarak kimlik bilgilerini eklemenin farklı yolları olabilir. Örneğin Kubernetes ve Docker Swarm, gizli anahtarları yönetmek için kılavuzlar sağlar. Daha fazla bilgi için ilgili sistem kılavuzuna bakın.

Kimlik bilgilerinizi korumak için en iyi uygulamaları takip edin.

Önizleme sunucusunun manuel olarak temel hazırlığını yapma

Önizleme sunucusu, sunucu kapsayıcısını önizlemenize olanak tanır. Ö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.

Gerekli ayarlar

  • CONTAINER_CONFIG: Sunucu kapsayıcısının 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 temel hazırlığını manuel olarak yapın'ı tıklayın.

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

Docker komut satırı aracını kullanma örneği

Önizleme sunucusunun yerel olarak temel hazırlığını yapmak için aşağıdaki komutu ç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 için yapılan bir istekte 200 yanıtı görebilirsiniz. Bağlantı noktasını değiştirmek için PORT ortam değişkenini de kullanabilirsiniz.

En iyi uygulamalar

  • Tam olarak 1 önizleme sunucusu dağıtmanız gerekir. Otomatik ölçeklendirmeyi 1 örneğin ötesinde 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 dengeleyiciniz veya CDN'niz, 20 saniyeden uzun bir zaman aşımına sahip olmalıdır. Aksi takdirde, önizleme modu düzgün çalışmaz.

Sunucu tarafı etiketleme kümesini manuel olarak sağlama

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

Gerekli ayarlar

  • CONTAINER_CONFIG: Sunucu kapsayıcısının 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 temel hazırlığını manuel olarak yapın'ı tıklayın.

  • PREVIEW_SERVER_URL: Önizleme sunucusunun HTTPS URL'si. Bu ayar yalnızca etiketleme sunucusunun temel hazırlığı için belirlenmelidir ve önizleme sunucusunun temel hazırlığı için gerekli değildir. Önizleme sunucusunun ayarlanmasıyla ilgili kılavuz için yukarıdaki bölüme bakın.

Docker komut satırı aracını kullanma örneği

Yerel olarak tek bir etiketleme sunucusu 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 için gönderilen istekte 200 yanıtı görürsünüz. Bağlantı noktasını değiştirmek için PORT ortam değişkenini de kullanabilirsiniz.

En iyi uygulamalar

  • Sunucu tarafı etiketleme sunucuları tek bir sunucu veya küme olarak sağlanabilir. Daha iyi kullanılabilirlik, ölçeklenebilirlik ve performans için küme olarak sağlamanızı öneririz. Küme olarak temel hazırlık 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.
  • SST kümesi dağıtımınızı, web sitenizde uygulamanıza hizmet veren alt alan adından ayrı yeni bir alt alan adına yönlendirdiğinizden emin olun. Örneğin, uygulamanız web trafiğini example.com adresinde sunuyorsa etiketleme sunucunuz için analytics.example.com gibi bir alt alan adı kullanın.
  • 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 için sunucuları düzenli olarak yeniden başlattığınızdan emin olun. Aksi takdirde yeni SST özellikleri için uyumsuz işlevler ortaya çıkabilir. Sunucunun ne zaman yeniden başlatılması gerektiğini bilmenin bir yolu, aşağıda daha ayrıntılı bir şekilde açıklanan canlılık denetimlerini ayarlamaktır. Ayrıca, sunucu kapsayıcınızda yayınlanan güncellemelerin yeniden başlatılmadan uygulanmaya devam edeceğini de unutmayın.
  • Canlılık kontrollerini ayarlamak için etiketleme sunucularınızda mevcut /healthz uç noktasını (ör. https://analytics.example.com/healthz) kullanın. Kötü durumda olmayan bir yanıt, sunucunun yeniden başlatılması gerektiğini belirtir.
  • 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 durum denetimine bağlıysanı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 ekleyerek PREVIEW_SERVER_URL öğesini belirtin.
  • Temel hazırlığı yapılan sunucularda en fazla 1 vCPU olmalıdır. Ek vCPU'lar kullanılmaz ve otomatik ölçeklendirmeyi olumsuz etkiler.

Doğrulama

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

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

Önizleme modunda doğrulama

Etiket Yöneticisi çalışma alanında Önizleme'yi tıklayarak kapsayıcıyı önizleyin ve önizleme sayfasının yüklendiğini görün. 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ış demektir.

Birden çok alt alan adını tek bir etiketleme sunucusuyla eşlediyseniz ve her bir alt alanda önizleme yapmak istiyorsanız Yönetici > Kapsayıcı Ayarları'nın altına ilave 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 üzerinde önizleme yapabilirsiniz ancak example.com/abc ve example2.com/def üzerinde önizleme yapamazsınız. Birden fazla URL eklenirse Önizle düğmesinin yanında, önizleme yapılacak URL'yi seçmenize olanak tanıyan bir simge görürsünüz.

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

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

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

  1. gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable adresindeki mevcut görüntü sürümünü getirin.
  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. Sunucu kapsayıcınızda, yeni bir hata ayıklama oturumu başlatmak ve ayrı bir sekmede istek göndermek için Önizle düğmesini tıklayın.
  2. Özet bölümünde Konsol sekmesini seçin ve etiketleme sunucusunu güncellemenizi isteyen herhangi bir mesaj olmadığından emin olun.

Etiket Yöneticisi, sunucu başarıyla güncellendikten sonra bir gün içinde etiketleme sunucunuzu güncellemenizi isteyen mesajlar gösterebilir. Ancak önizleme sayfasında, etiketleme sunucusu sürümü hakkında güncel bir mesaj görüntülenir.