Guida alla configurazione manuale

Il flusso di provisioning automatico può essere utilizzato per eseguire il deployment del server di tagging su Cloud Run in pochi clic. Se vuoi eseguire il provisioning del server di tagging in altri ambienti, puoi farlo manualmente. Il server di tagging è un server Node.js all'interno di un'immagine Docker.

Il provisioning manuale del server di tagging richiede il provisioning separato del cluster di tagging lato server (SST) e di un server di anteprima. Il cluster SST è il punto di accesso per tutte le richieste al server di tagging e gestirà le richieste come descritto in Introduzione al tagging lato server. Il server di anteprima è necessario per visualizzare l'anteprima di un contenitore.

Consulta la Figura 1 per un'illustrazione dell'interazione dei dati tra i server di tagging e il server di anteprima.

Diagramma del flusso di dati dei server di tagging e del server di anteprima

Figura 1: un diagramma del flusso di dati dei server di tagging e del server di anteprima.

Questa guida spiega come:

  • Visualizza tutte le impostazioni disponibili per l'immagine Docker.
  • (Facoltativo) Includi le credenziali BigQuery
  • Esegui manualmente il provisioning di un server di anteprima utilizzando l'immagine Docker SST.
  • Esegui il provisioning manuale di un cluster SST utilizzando l'immagine Docker SST.
  • Verifica che il server di anteprima e il cluster SST siano configurati correttamente.
  • Mantieni aggiornata la versione del server di tagging dopo il provisioning del server.

Per eseguire i comandi Docker in questa guida, devi prima installare Docker sul tuo computer.

Visualizza tutte le impostazioni disponibili per l'immagine Docker

L'immagine Docker del server di tagging è disponibile a questo URL:

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

Il server di tagging e il server di anteprima utilizzano la stessa immagine Docker con flag diversi. In questa sezione, esamineremo come cercare tutte le impostazioni disponibili che possono essere utilizzate con l'immagine Docker.

Per visualizzare tutte le impostazioni disponibili, esegui il seguente comando utilizzando lo strumento a riga di comando Docker:

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

(Facoltativo) Includi le credenziali Google Cloud

Per utilizzare l'API BigQuery o Firestore al di fuori di Google Cloud, devi fornire una credenziale del service account autorizzata ad accedere a queste risorse.

  1. Segui questa guida per creare un service account con il ruolo Editor dati BigQuery per l'accesso a BigQuery o il ruolo Utente Cloud Datastore per l'accesso a Firestore ed esporta le relative credenziali JSON con il nome file local_service_account_key.json.
  2. Monta le credenziali JSON in un volume accessibile all'immagine. Utilizzando docker run, puoi specificare -v local_service_account_key.json:/app/service_account_key.json per montare le credenziali nell'immagine.
  3. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS in modo che punti alla credenziale.
  4. (Facoltativo) Specifica l'ID progetto Google Cloud nella variabile di ambiente GOOGLE_CLOUD_PROJECT per consentire al server di tagging di scegliere implicitamente il progetto.

  5. Esegui il server. Il seguente comando esegue il server di tagging con le credenziali incluse:

    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

A seconda del sistema su cui viene implementato il server di tagging, potrebbero esistere diversi modi per montare le credenziali. Ad esempio, Kubernetes e Docker Swarm forniscono guide per la gestione dei secret. Per ulteriori informazioni, consulta la guida del tuo sistema.

Assicurati di seguire le best practice per proteggere le tue credenziali.

Esegui manualmente il provisioning di un server di anteprima

Il server di anteprima ti consente di visualizzare l'anteprima del contenitore del server. Per eseguire il server di anteprima, esegui l'immagine Docker con le seguenti variabili di ambiente passate all'ambiente Docker.

Impostazioni obbligatorie

  • CONTAINER_CONFIG: la stringa di configurazione per il contenitore del server. In Tag Manager, vai al workspace del contenitore server e fai clic sull'ID contenitore in alto a destra nella pagina. Fai clic su Esegui il provisioning manuale del server di tagging per trovare il valore di Configurazione contenitore.

  • RUN_AS_PREVIEW_SERVER: imposta questo valore su true per eseguire il provisioning del server come server di anteprima.

Esempio di utilizzo dello strumento a riga di comando Docker

Per eseguire il provisioning di un server di anteprima in locale, esegui questo comando:

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

Dovresti visualizzare una risposta 200 da una richiesta a http://localhost:8080/healthy. (Facoltativo) Utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

  • Devi eseguire il deployment di esattamente un server di anteprima. Non configurare la scalabilità automatica oltre 1 istanza.
  • Dopo aver configurato un server di anteprima utilizzando Docker, configura un URL HTTPS in modo che punti al server di anteprima. È necessario per configurare il cluster SST.
  • Il bilanciatore del carico o la CDN deve avere un timeout superiore a 20 secondi, altrimenti la modalità di anteprima non funzionerà correttamente.

Esegui manualmente il provisioning di un cluster di tagging lato server

Il cluster SST funge da punto di ingresso, esegue il proxy delle richieste di anteprima al server di anteprima e gestisce tutte le altre richieste come descritto in Introduzione al tagging lato server. Utilizza le seguenti impostazioni obbligatorie con l'immagine Docker del server di tagging per eseguire il provisioning di un cluster SST in qualsiasi ambiente che supporti Docker.

Impostazioni obbligatorie

  • CONTAINER_CONFIG: la stringa di configurazione per il contenitore del server. In Tag Manager, vai al workspace del contenitore server e fai clic sull'ID contenitore in alto a destra nella pagina. Fai clic su Esegui il provisioning manuale del server di tagging per trovare il valore di Configurazione contenitore.

  • PREVIEW_SERVER_URL: l'URL HTTPS del server di anteprima. Questa impostazione deve essere configurata solo per il provisioning del server di tagging e non è necessaria per il provisioning del server di anteprima. Consulta la sezione precedente per una guida alla configurazione del server di anteprima.

Esempio di utilizzo dello strumento a riga di comando Docker

Per eseguire il provisioning di un singolo server di tagging in locale, esegui il comando seguente:

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

Dovresti visualizzare una risposta 200 da una richiesta a http://localhost:8080/healthy. (Facoltativo) Utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

  • I server di tagging lato server possono essere sottoposti a provisioning come singolo server o come cluster. Ti consigliamo di eseguirne il provisioning come cluster per una migliore disponibilità, scalabilità e prestazioni. Tieni presente che durante il provisioning come cluster, ogni istanza del server deve essere configurata con le stesse variabili di ambiente CONTAINER_CONFIG e PREVIEW_SERVER_URL.
  • Assicurati di ospitare il server di tagging nella stessa origine (best practice) o come sottodominio del tuo sito web attuale. Ad esempio, se la tua applicazione invia traffico web a example.com, utilizza un percorso come example.com/analytics per il server di tagging. Scopri di più sulla configurazione del dominio personalizzato.
  • Dopo aver configurato un cluster SST utilizzando Docker, configura un URL HTTPS in modo che punti al cluster SST.
  • Assicurati di riavviare periodicamente i server per assicurarti che abbiano gli aggiornamenti del codice più recenti per SST. In caso contrario, le nuove funzionalità SST potrebbero non essere compatibili. Un modo per sapere quando il server deve essere riavviato è configurare i controlli di attività, descritti più avanti. Tieni inoltre presente che gli aggiornamenti pubblicati al contenitore server verranno comunque applicati senza riavvio.
  • Utilizza l'endpoint /healthy esistente (ad es. https://analytics.example.com/healthy) sui server di tagging per configurare i controlli di attività. Una risposta non integra indica che il server deve essere riavviato.
  • Il container Docker include un comando di controllo di integrità predefinito, HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"], che esegue query sull'endpoint /healthy periodicamente. Se utilizzi il controllo di integrità di Docker, puoi modificare le impostazioni seguendo le istruzioni di Docker.
  • Se il server di anteprima e il server di tagging si trovano sulla stessa origine, ospita il server di anteprima su un percorso diverso da quello del server di tagging. Specifica il PREVIEW_SERVER_URL, incluso il percorso.
  • I server di cui è stato eseguito il provisioning devono avere al massimo 1 vCPU. Le vCPU aggiuntive non vengono utilizzate e influiscono negativamente sulla scalabilità automatica.

Convalida

Configurare l'URL del contenitore del server

In Tag Manager, vai al contenitore del server. In Amministrazione > Impostazioni contenitore, inserisci l'URL del server di tagging nel campo URL contenitore server e fai clic su Salva.

Verifica tramite la modalità di anteprima

Nel workspace di Tag Manager, visualizza l'anteprima del container facendo clic su Anteprima e verifica che la pagina di anteprima venga caricata. In un'altra scheda del browser, vai a qualsiasi percorso nell'URL contenitore del server. Se la pagina di anteprima mostra la richiesta inviata, allora tutto è configurato correttamente.

Se hai mappato più sottodomini a un singolo server di tagging e vuoi visualizzare l'anteprima su ogni sottodominio, aggiungi altri URL del contenitore del server in Amministrazione > Impostazioni contenitore. Se vengono forniti più URL, tutti i percorsi degli URL devono corrispondere (la stringa di informazioni che segue il nome di dominio). Ad esempio, puoi visualizzare l'anteprima su example.com/abc e example2.com/abc, ma non su example.com/abc e example2.com/def. Se vengono aggiunti più URL, vedrai un'icona accanto al pulsante Anteprima che ti consente di selezionare l'URL da visualizzare in anteprima.

Aggiornare la versione del server di tagging

L'immagine gtm-cloud-image contiene Node.js e le librerie necessarie per il funzionamento del server di tagging. L'immagine Docker viene aggiornata periodicamente per correzioni della sicurezza e nuove funzionalità. Ti consigliamo di aggiornare almeno il server di tagging per ogni release della versione principale (ad es. l'upgrade dalla versione 1.x.x alla 2.x.x).

Per aggiornare l'immagine Docker:

  1. Recupera la versione corrente dell'immagine all'indirizzo gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
  2. Esegui il deployment del server con le stesse impostazioni del deployment precedente.
  3. Aggiorna il singolo server di anteprima e tutti i server di tagging nel cluster.
  4. Chiudi tutti i server precedenti.

Per verificare che l'aggiornamento sia riuscito:

  1. Nel contenitore server, fai clic sul pulsante Anteprima per avviare una nuova sessione di debug e inviare una richiesta in una scheda separata.
  2. Nel riepilogo, seleziona la scheda Console e assicurati che non siano presenti messaggi che ti chiedono di aggiornare il server di tagging.

Tag Manager potrebbe mostrare messaggi che ti chiedono di aggiornare il server di tagging fino a un giorno dopo l'aggiornamento del server. Tuttavia, la pagina di anteprima mostrerà un messaggio aggiornato sulla versione del server di tagging.