Manual setup guide

The automatic provisioning flow can be used to deploy the tagging server to Cloud Run in just a few clicks. If you want 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.

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.
• Keep your tagging server version updated after provisioning the server.

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

Note: When you set up your tagging server, the owner of the server environment (whether it is a cloud provider or on-premise) may have access to your data. Refer to that organization's terms of service for more details.

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 server_bin.js --help

(Optional) Include Google Cloud credentials

To use the BigQuery or Firestore API outside of Google Cloud, you must provide a service account credential that is authorized to access those resources.

1. Follow this guide to create a service account with the BigQuery Data Editor role for BigQuery access or the Cloud Datastore User role for Firestore access 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.
• Your load balancer or CDN must have a timeout longer than 20 seconds, otherwise preview mode will not work correctly.

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 host your tagging server in the same origin (best practice) or as a subdomain of your current website. For example, if your application serves web traffic at example.com, use a path such as example.com/analytics for your tagging server. Learn more about custom domain configuration.
• 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.
• The Docker container includes a default health check command—HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]—that queries the /healthz endpoint periodically. If you depend on the Docker health check, you may change the settings by following the Docker instructions.
• If the preview server and tagging server are on the same origin, host the preview server on a different path than the tagging server. Specify the PREVIEW_SERVER_URL including the path.
• The provisioned servers should have at most 1 vCPU. Additional vCPUs are not utilized and affect autoscaling negatively.

Validation

Configure the server container URL

In Tag Manager, navigate to your server container. Under Admin > Container Settings put the URL of the tagging server into the Server container 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 Server container URL. If the preview page shows the request that was sent, then everything is set up correctly.

If you have mapped multiple subdomains to a single tagging server and you want to preview on each subdomain, add additional Server container URLs under Admin > Container Settings. If multiple URLs are provided, all URL paths must match (the string of information that comes after the domain name). For example, you can preview on example.com/abc and example2.com/abc but you cannot preview on example.com/abc and example2.com/def. If multiple URLs are added, you will see an icon next to the Preview button that allows you to select the URL to preview on.

Update the tagging server version

Note: If you provisioned your tagging servers using the Cloud Run setup guide or App Engine setup guide, follow the instructions listed there.

The gtm-cloud-image image contains Node.js and the libraries needed for the tagging server to function. The Docker image is periodically updated for security fixes and new features. We recommend at least updating your tagging server for each major version release (e.g. upgrading from version 1.x.x to 2.x.x).

To update your Docker image:

1. Fetch the current image version at gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
2. Deploy your server with the same settings as the previous deployment.
3. Update the single preview server and all tagging servers in the cluster.
4. Shut down any old servers.

To verify that the update was successful:

1. In your server container, click the Preview button to start a new debug session and send a request on a separate tab.
2. In the Summary, select the Console tab and make sure there are no messages asking you to update the tagging server.

Tag Manager may show messages asking you to update your tagging server for up to a day after the server has been updated successfully. However, the preview page will show an up to date message about the tagging server version.