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](https://nodejs.org/about/)
server inside of a [Docker](https://docs.docker.com/get-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](https://developers.google.com/tag-platform/tag-manager/server-side/intro). 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](https://developers.google.com/static/tag-platform/tag-manager/server-side/img/tagging-servers-preview-server-diagram.png)

*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](https://docs.docker.com/get-docker) on your computer.

> [!NOTE]
> **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](https://docs.docker.com/engine/reference/commandline/cli/):

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

## (Optional) Include Google Cloud credentials

To use the [`BigQuery`](https://developers.google.com/tag-platform/tag-manager/server-side/api#bigquery) or [`Firestore`](https://developers.google.com/tag-platform/tag-manager/server-side/api#firestore) API outside of Google Cloud, you must
provide a service account credential that is authorized to access those
resources.

1. Follow this [guide](https://cloud.google.com/docs/authentication/production#create_service_account) 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](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets) and
[Docker Swarm](https://docs.docker.com/engine/reference/commandline/secret/) provide guides for managing secrets. Refer to your respective
system's guide for more information.

Make sure to follow the [best practices](https://cloud.google.com/docs/authentication/production#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/healthy`. 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](https://developers.google.com/tag-platform/tag-manager/server-side/intro). 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](https://developers.google.com/tag-platform/tag-manager/server-side/manual-setup-guide#manually_provision_a_preview_server) 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/healthy`.
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](https://developers.google.com/tag-platform/tag-manager/server-side/custom-domain?option=same-origin).
- 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 `/healthy` endpoint (e.g. `https://analytics.example.com/healthy`) 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 `/healthy` endpoint periodically. If you depend on the Docker health check, you may change the settings by following the [Docker instructions](https://docs.docker.com/engine/reference/run/#healthcheck).
- 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]
> **Note:** If you provisioned your tagging servers using the [Cloud Run setup guide](https://developers.google.com/tag-platform/tag-manager/server-side/cloud-run-setup-guide#update_the_tagging_server_version) or [App Engine setup guide](https://developers.google.com/tag-platform/tag-manager/server-side/app-engine-setup#update_the_tagging_server_version), follow the instructions listed there.

The [gtm-cloud-image](https://gcr.io/cloud-tagging-10302018/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](https://developers.google.com/tag-platform/tag-manager/server-side/manual-setup-guide#manually_provision_a_preview_server) and all [tagging servers in the cluster](https://developers.google.com/tag-platform/tag-manager/server-side/manual-setup-guide#manually_provision_a_server-side_tagging_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](https://developers.google.com/tag-platform/tag-manager/server-side/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.