Thanks for previewing Google's new tag platform documentation! This site is in public beta. (Feedback)

Manual setup guide

The automatic provisioning flow can be used to deploy the tagging server to App Engine in just a few clicks. If you wish to provision the tagging server in other environments, you can do so manually. The tagging server is a Node.js server inside of a Docker image.

Manually provisioning the tagging server requires provisioning the server-side tagging (SST) cluster and a preview server separately. The SST cluster is the entry point for all requests to the tagging server and will handle requests as described in An introduction to server-side tagging. The preview server is needed for previewing a container.

See figure 1 for an illustration of the data interaction between the tagging servers and the preview server.

Diagram of tagging servers and preview server data flow

Figure 1: A diagram of the tagging servers and preview server data flow.

This guide explains how to:

  • View all available settings for the Docker image.
  • (Optional) Include BigQuery credentials
  • Manually provision a preview server using the SST Docker image.
  • Manually provision a SST cluster using the SST Docker image.
  • Verify that the preview server and SST cluster are configured correctly.

In order to run the Docker commands in this guide, you must first install Docker on your computer.

View all available settings for the Docker image

The tagging server Docker image can found at this URL:

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

The tagging server and preview server use the same Docker image with different flags. In this section, we'll walk through how to look up all available settings that can be used with the Docker image.

To see all available settings, run the following using the docker command line tool:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable /bin/bash -c "node server_bin.js --help"

(Optional) Include BigQuery credentials

To use the BigQuery API outside of Google Cloud, you must provide a service account credential that is authorized to write into the BigQuery table.

  1. Follow this guide to create a service account with the BigQuery Data Editor role and export its JSON credentials with the filename local_service_account_key.json.
  2. Mount the JSON credential in a volume accessible to the image. Using docker run, you can specify -v local_service_account_key.json:/app/service_account_key.json to mount the credentials in the image.
  3. Point the GOOGLE_APPLICATION_CREDENTIALS environment variable to the credential.
  4. Optionally, specify your Google Cloud project ID in the GOOGLE_CLOUD_PROJECT environment variable to let the tagging server implicitly choose the project.
  5. Run the server. The following command runs the tagging server with the credentials included:

    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
    

Depending on what system the tagging server is deployed to, there may be different ways to mount the credentials. For example, Kubernetes and Docker Swarm provide guides for managing secrets. Refer to your respective system's guide for more information.

Make sure to follow the best practices to protect your credentials.

Manually provision a preview server

The preview server enables you to preview the server container. In order to run the preview server, run the Docker image with the following environment variables passed to the Docker environment.

Required settings

  • CONTAINER_CONFIG - The configuration string for the server container. In Tag Manager, navigate to your server container workspace and click on the container ID at the top-right of the page. Click on Manually provision tagging server to find the Container Config value.

  • RUN_AS_PREVIEW_SERVER - Set this to true to provision the server as a preview server.

Example using the Docker command line tool

To provision a preview server locally, run the following:

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

You should be able to see a 200 response from a request to http://localhost:8080/healthz. Optionally, use the PORT environment variable to change the port.

Best practices

  • You must deploy exactly 1 preview server. Do not configure autoscaling beyond 1 instance.
  • Once you've set up a preview server using Docker, configure an HTTPS URL to point to the preview server. This is needed for setting up the SST cluster.

Manually provision a server-side tagging cluster

The SST cluster serves as the entry point, proxies preview requests to the preview server, and handles all other requests as described in An introduction to server-side tagging. Use the following required settings with the tagging server Docker image to provision a SST cluster in any environment that supports Docker.

Required settings

  • CONTAINER_CONFIG - The configuration string for the server container. In Tag Manager, navigate to your server container workspace and click on the container ID at the top-right of the page. Click on Manually provision tagging server to find the Container Config value.

  • PREVIEW_SERVER_URL - The HTTPS URL for the preview server. This setting should only be set for provisioning the tagging server and is not needed for provisioning the preview server. See the above section for a guide on setting up the preview server.

Example using the Docker command line tool

To provision a single tagging server locally, run the following:

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

You should see a 200 response from a request to http://localhost:8080/healthz. Optionally, use the PORT environment variable to change the port.

Best practices

  • Server-side tagging servers can be provisioned as either a single server or as a cluster. We recommend that you provision it as a cluster for better availability, scalability, and performance. Please note that when provisioning as a cluster, each server instance must be configured with the same CONTAINER_CONFIG and PREVIEW_SERVER_URL environment variables.
  • Make sure to point your SST cluster deployment to a new subdomain on your website that is separate from the subdomain that serves your application. For example, if your application serves web traffic at example.com, use a subdomain such as analytics.example.com for your tagging server.
  • Once you've set up a SST cluster using Docker, configure an HTTPS URL to point to the SST cluster.
  • Make sure to restart the servers periodically to ensure your servers have the latest code updates for SST. Failure to do so may result in incompatible functionality for new SST features. One way to know when the server needs to restart is to set up liveness checks, which is explained further below. Also, please note that any published updates to your server container will still be applied without a restart.
  • Utilize the existing /healthz endpoint (e.g. https://analytics.example.com/healthz) on your tagging servers to set up liveness checks. A non-healthy response indicates that the server should be restarted.

Validation

Configure the tagging server URL

Navigate to your server-side Tag Manager container under Admin > Container Settings. Put the URL of the SST cluster into the Tagging server URL field and click Save.

Verify through Preview Mode

In the Tag Manager workspace, preview the container by clicking Preview and see that the preview page loads. On another browser tab, navigate to any path on the tagging server URL. If the preview page shows the request that was sent, then everything is set up correctly.