Google Tag Manager server side docker setup requires running two separate containers: the SST cluster for handling tagging requests and the preview server for debugging. You use the official Docker image provided by Google, configure specific environment variables like CONTAINER_CONFIG, and expose ports for both services. This method gives you full control over your infrastructure, allowing you to run the tagging server on any host that supports Docker, not just Google Cloud Run.
Why use Docker for Google Tag Manager server side
Most tutorials tell you to use Google Cloud Run. That is easy, but it locks you into Google's pricing model and infrastructure. If you want to run the tagging server on your own DigitalOcean droplet, an AWS EC2 instance, or a local machine for testing, Docker is the way to do it.
The tagging server is a Node.js application packaged inside a Docker image. When you run it manually, you are not installing Node.js or npm packages on your host. You are just pulling an image and starting a container. This keeps your server clean and makes updates simple. You pull the new image, stop the old container, and start the new one.
There are two distinct roles for this single image:
- The SST Cluster: This is the production entry point. Your website sends data to this server. It processes the tags and fires the appropriate pixels or API calls.
- The Preview Server: This is a separate instance of the same image. It handles preview requests from the Google Tag Manager interface. You need this to debug your tags without affecting live traffic.
You cannot run both roles in a single container. You must run two containers, each with different environment variables. The SST cluster needs to know where the preview server is located, and the preview server needs to know its own configuration.
Getting the Container Config string
Before you touch Docker, you need the configuration data from your Google Tag Manager account. This string tells the server which tags to fire and how to process them.
- Log in to Google Tag Manager.
- Select your Server Container workspace. Do not select your Web Container.
- Click the container ID in the top right corner (it looks like
GTM-XXXXXXX). - Select Manually provision tagging server from the dropdown menu.
- Copy the entire string from the Container Config field.
This string is long and contains JSON data. It includes your container ID, your workspace settings, and your tag configurations. You will paste this string into the CONTAINER_CONFIG environment variable for both containers.
If you do not have a Server Container yet, you must create one first. You can create a new account or add a server container to an existing account. The setup wizard will guide you through the initial steps, but you will still need to pull this config string for the Docker setup.
Setting up the Docker environment
You need Docker and Docker Compose installed on your machine. If you are using a fresh Linux server, install Docker first.
Create a directory for your project, for example, gtm-server-side. Inside this directory, create a file named docker-compose.yml. This file will define the two services.
Here is the structure you need:
version: '3.8'
services:
gtm-preview:
image: gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable
container_name: gtm-preview
ports:
- "8081:8080"
environment:
- CONTAINER_CONFIG=${CONTAINER_CONFIG}
- RUN_AS_PREVIEW_SERVER=true
gtm-sst:
image: gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable
container_name: gtm-sst
ports:
- "8080:8080"
environment:
- CONTAINER_CONFIG=${CONTAINER_CONFIG}
- PREVIEW_SERVER_URL=http://gtm-preview:8080
depends_on:
- gtm-preview
You also need a .env file in the same directory. This file holds your secrets. Create a file named .env and add your container config string:
CONTAINER_CONFIG={"containerConfig":"..."}
Replace the placeholder with the actual long string you copied from Google Tag Manager. Make sure the entire string is on one line. If you break it across lines, Docker will fail to parse it.
The PREVIEW_SERVER_URL for the SST container points to the preview service. Since they are on the same Docker network, you use the service name gtm-preview and the internal port 8080. The host port mapping 8081:8080 allows you to access the preview server from your browser on port 8081.
Starting and verifying the containers
Navigate to your project directory in your terminal. Run the following command to start the containers:
docker compose up -d
The -d flag runs the containers in the background. You can check their status with:
docker compose ps
Both containers should be listed as "Up". If one is restarting or exited, check the logs with:
docker compose logs gtm-sst
docker compose logs gtm-preview
Now, verify that the servers are responding. Open a browser or use curl to hit the health check endpoints.
For the preview server:
http://localhost:8081/healthz
For the SST cluster:
http://localhost:8080/healthz
Both should return 200 OK or similar success status. If you get a connection refused error, check that the ports are not already in use by another application. If you get a 404 error, check that the CONTAINER_CONFIG string is valid and not truncated.
You can use the GTM server side checker to verify if your server is reachable from the outside. It tells you whether the endpoint is live and responding to requests. This is useful if you are testing from a different machine or if you have firewall rules in place.
Configuring Google Tag Manager to use your server
Once your Docker containers are running, you need to tell Google Tag Manager to send traffic to your new server instead of the default Google endpoint.
- Go to your Server Container in Google Tag Manager.
- Click Admin in the top right.
- Click Container Settings.
- Find the Server Container URL field.
- Enter the public URL of your SST cluster.
If you are testing locally, you can use http://localhost:8080. If you are running this on a cloud server, use your server's public IP or domain name. For example: https://gtm.yourdomain.com.
If you are using a domain name, you need to set up DNS records pointing to your server IP. You also need to set up SSL/TLS certificates if you are using HTTPS. Most cloud providers offer free SSL certificates. Without HTTPS, some browsers may block the requests, or your data may be intercepted.
After saving the settings, publish your changes. It can take a few minutes for the new URL to propagate across Google's servers.
Handling BigQuery and Firestore credentials
If you want to send your tracking data to BigQuery or Firestore, you need to provide service account credentials. This is optional. If you are only using standard tags like Google Analytics 4 or Meta Pixel, you do not need this.
- Go to the Google Cloud Console.
- Create a service account.
- Assign the BigQuery Data Editor role if you are using BigQuery.
- Assign the Cloud Datastore User role if you are using Firestore.
- Create a JSON key for this service account and download it.
Name the file local_service_account_key.json. Place it in your project directory next to docker-compose.yml.
Update your docker-compose.yml to mount this file into the SST container:
gtm-sst:
image: gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable
container_name: gtm-sst
ports:
- "8080:8080"
environment:
- CONTAINER_CONFIG=${CONTAINER_CONFIG}
- PREVIEW_SERVER_URL=http://gtm-preview:8080
- GOOGLE_APPLICATION_CREDENTIALS=/app/local_service_account_key.json
- GOOGLE_CLOUD_PROJECT=your-gcp-project-id
volumes:
- ./local_service_account_key.json:/app/local_service_account_key.json:ro
depends_on:
- gtm-preview
The :ro flag makes the file read-only inside the container, which is a security best practice.
Restart the containers after making these changes:
docker compose down
docker compose up -d
Check the logs again to ensure there are no authentication errors.
Keeping the server updated
The Docker image gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable receives updates. To keep your server current, you need to pull the new image and restart the containers.
- Stop the containers:
docker compose down - Pull the latest image:
docker pull gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable - Start the containers:
docker compose up -d
This process is quick and usually does not cause downtime if you have a load balancer in front of your server. If you are running a single instance, there will be a brief moment where the server is down. Plan updates during low-traffic hours.
You can also set up a cron job to check for new images and restart the containers automatically. However, for most small businesses, manual updates are sufficient. Check the manual setup guide for the latest recommendations on versioning and updates.
Common issues and fixes
Port conflicts: If port 8080 or 8081 is already in use, Docker will fail to start. Change the host port mapping in docker-compose.yml. For example, use 8082:8080 for the SST cluster. Update your PREVIEW_SERVER_URL and GTM settings accordingly.
Invalid Container Config: If you paste the config string incorrectly, the server will crash on startup. Check the logs for JSON parse errors. Ensure the string is not truncated and that special characters are properly escaped.
Preview not working: If you can hit the health check but preview mode in GTM does not load, check that PREVIEW_SERVER_URL is correct. It must point to the preview container's internal address, not the host IP.
SSL errors: If you are using HTTPS, ensure your certificate is valid and trusted. Browsers will block mixed content if your site is HTTPS but the GTM server is HTTP.
For a deeper dive into configuring tags and troubleshooting specific pixel issues, you can read our guide on server-side tracking. It covers how to structure your tags for maximum efficiency and how to debug common firing problems.
By following these steps, you have a fully functional Google Tag Manager server side setup running on Docker. You have control over your infrastructure, your data, and your costs. This setup is robust, scalable, and easy to maintain.