Manuel kurulum kılavuzu

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

Etiketleme sunucusunun manuel olarak hazırlanması için sunucu taraflı etiketleme (SST) kümesinin ve önizleme sunucusunun ayrı ayrı hazırlanması gerekir. SST kümesi, etiketleme sunucusuna yapılan tüm isteklerin giriş noktasıdır ve istekleri Sunucu tarafı etiketlemeye giriş başlıklı makalede açıklandığı şekilde işler. Kapsayıcıyı önizlemek için önizleme sunucusu gerekir.

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

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

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

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

  • Docker görüntüsü için kullanılabilen tüm ayarları görüntüleyin.
  • (İsteğe bağlı) BigQuery kimlik bilgilerini ekleyin
  • SST Docker görüntüsünü kullanarak önizleme sunucusunu manuel olarak sağlama
  • SST Docker görüntüsünü kullanarak SST kümesini manuel olarak sağlama.
  • Önizleme sunucusunun ve SST kümesinin doğru şekilde yapılandırıldığını doğrulayın.
  • Sunucuyu sağladıktan sonra etiketleme sunucunuzun sürümünü güncel tutun.

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

Docker görüntüsü için kullanılabilen 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şaretlere sahip aynı Docker görüntüsünü kullanır. Bu bölümde, Docker görüntüsüyle kullanılabilecek tüm ayarların nasıl aranacağını ele alacağız.

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 ekleyin

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 üzere bu kılavuzu uygulayın ve JSON kimlik bilgilerini local_service_account_key.json dosya adıyla dışa aktarın.
  2. JSON kimlik bilgisini, görüntüye erişilebilen bir birime bağlayın. docker run kullanarak, resimdeki kimlik bilgilerini bağlamak 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 örtülü 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, kimlik bilgilerini içeren etiketleme sunucusunu ç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, sırları yönetmeyle ilgili kılavuzlar sunar. Daha fazla bilgi için ilgili sisteminizin kılavuzuna bakın.

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ın önizlemesini yapmanızı sağlar. Önizleme sunucusunu çalıştırmak için Docker görüntüsünü, Docker ortamına aktarılan 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ısı ç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 sağlama'yı tıklayın.

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

Docker komut satırı aracını kullanan ö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/healthy adresine yapılan bir isteğe 200 yanıtı görebilmeniz gerekir. İsteğe bağlı olarak, bağlantı noktasını değiştirmek için PORT ortam değişkenini kullanın.

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ı süresi 20 saniyeden uzun olmalıdır. Aksi takdirde önizleme modu düzgün çalışmaz.

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

SST kümesi giriş noktası olarak işlev görür, önizleme isteklerini önizleme sunucusuna yönlendirir ve Sunucu tarafı etiketlemeye giriş bölümünde açıklandığı gibi diğer tüm istekleri 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 zorunlu ayarları kullanın.

Gerekli ayarlar

  • CONTAINER_CONFIG: Sunucu kapsayıcısının yapılandırma dizesi. Etiket Yöneticisi'nde sunucu kapsayıcısı ç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 sağlama'yı 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 ayarlama kılavuzu için yukarıdaki bölüme bakın.

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

Tek bir etiketleme sunucusunu yerel olarak hazırlamak için aşağıdakileri ç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/healthy adresine yapılan bir isteğe 200 yanıtı almanız gerekir. İ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 taraflı etiketleme sunucuları tek bir sunucu veya küme olarak hazırlanabilir. Daha iyi kullanılabilirlik, ölçeklenebilirlik ve performans için bunu küme olarak sağlamanızı öneririz. Küme olarak sağlarken 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 aynı kaynakta (en iyi uygulama) veya mevcut web sitenizin alt alan adı olarak barındırdığınızdan emin olun. Örneğin, uygulamanız web trafiğini example.com adresinde sunuyorsa etiketleme sunucunuz için example.com/analytics gibi bir yol kullanın. Özel alan adı yapılandırması hakkında daha fazla bilgi edinin.
  • Docker kullanarak bir SST kümesi oluşturduktan sonra SST kümesine yönlendirecek bir HTTPS URL'si yapılandırın.
  • Sunucularınızın SST için en son kod güncellemelerine sahip olmasını sağlamak amacıyla sunucuları düzenli olarak yeniden başlattığınızdan emin olun. Bunu yapmamanız, yeni SST özelliklerinin işlevselliğinin uyumsuz olmasına neden olabilir. Sunucunun ne zaman yeniden başlatılması gerektiğini öğrenmenin bir yolu, aşağıda daha ayrıntılı olarak açıklanan canlılık kontrolleri ayarlamaktır. Ayrıca, sunucu kapsayıcınızda yayınlanan güncellemelerin yeniden başlatma olmadan uygulanmaya devam edeceğini lütfen unutmayın.
  • Etkinlik kontrollerini ayarlamak için etiketleme sunucularınızda mevcut /healthy uç noktasını (ör. https://analytics.example.com/healthy) kullanın. Sağlıklı olmayan bir yanıt, sunucunun yeniden başlatılması gerektiğini gösterir.
  • Docker kapsayıcısı, /healthy 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ı kaynakta bulunuyorsa önizleme sunucusunu etiketleme sunucusundan farklı bir yolda barındırın. Yol da dahil olmak üzere PREVIEW_SERVER_URL özelliğini belirtin.
  • Sağlanan sunucularda en fazla 1 vCPU olmalıdır. Ek sanal CPU'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ğ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ısı URL'sindeki herhangi bir yola gidin. Önizleme sayfasında gönderilen istek gösteriliyorsa her şey doğru şekilde ayarlanmıştır.

Tek bir etiketleme sunucusuna birden fazla alt alan adı 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ısı URL'leri ekleyin. Birden fazla URL girilirse tüm URL yolları (alan adından sonra gelen bilgi dizesi) eşleşmelidir. Örneğin, example.com/abc ve example2.com/abc üzerinde önizleme yapabilirken example.com/abc ve example2.com/def üzerinde önizleme yapamazsınız. Birden fazla URL eklenirse Önizleme 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'yi 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. Her ana sürüm yayınında (ör. 1.x.x sürümünden 2.x.x sürümüne yükseltme) etiketleme sunucunuzu en azından güncellemenizi öneririz.

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

  1. Mevcut resim sürümünü gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable adresinden getirin.
  2. Sunucunuzu önceki dağıtımla aynı ayarlarla 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'te Konsol sekmesini seçin ve etiketleme sunucusunu güncellemenizi isteyen mesajların olmadığından emin olun.

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