Build and run images

Use a prebuilt image
Build a local image

Use a prebuilt image

While you are just testing out data changes, you don’t need to build the website, but can just use a prebuilt Data Commons image.

Data Commons provides two prebuilt images in the Google Artifact Registry that you can download to run in a Docker container (and use as the container in a Google Cloud Run service):

gcr.io/datcom-ci/datacommons-data:stable: the data import container
gcr.io/datcom-ci/datacommons-services:stable: the web services container

You can see the images with their tags at https://console.cloud.google.com/artifacts/docker/datcom-ci/us/gcr.io/datacommons-data and https://console.cloud.google.com/artifacts/docker/datcom-ci/us/gcr.io/datacommons-services.

To pick up the most recent stable prebuilt image(s) locally, do the following:

From your repo root directory (e.g. website), run the following command:

docker pull gcr.io/datcom-ci/datacommons-services:stable
docker pull gcr.io/datcom-ci/datacommons-data:stable

Rerun the containers:

Bash script
Docker commands

./run_cdc_dev_docker.sh

    docker run \
    --env-file $PWD/custom_dc/env.list \
    -v INPUT_DIRECTORY:INPUT_DIRECTORY \
    -v OUTPUT_DIRECTORY:OUTPUT_DIRECTORY \
    gcr.io/datcom-ci/datacommons-data:stable

    docker run -it \
    -p 8080:8080 \
    -e DEBUG=true \
    --env-file $PWD/custom_dc/env.list \
    -v INPUT_DIRECTORY:INPUT_DIRECTORY \
    -v OUTPUT_DIRECTORY:OUTPUT_DIRECTORY \
    gcr.io/datcom-ci/datacommons-services:stable

To pick up the latest versions of either prebuilt image in Google Cloud Platform, see Manage your service.

Build a local image

You will need to build a local image whenever you make changes to the website UI.

Building from the master branch includes the very latest changes in Github, that may not have been tested. Instead, we recommend that you use the tested “stable” branch equivalent of the stable Docker image. This branch is customdc_stable, and is available at https://github.com/datacommonsorg/website/tree/customdc_stable.

Note: If you are working on a large-scale customization, we recommend that you use a version control system to manage your code. We provide some procedures for Github.

Clone the stable branch only

Use this procedure if you are not using Github, or if you are using Github and want to create a new source directory and start from scratch.

Run the following command:
```
git clone https://github.com/datacommonsorg/website --branch customdc_stable --single-branch  [DIRECTORY]
```
This creates a new local branch called customdc_stable set to track the Data Commons repo branch.
To verify, run:
```
cd website | cd DIRECTORY
git branch -vv
```
You should see output like the following:
```
* customdc_stable 83732891 [origin/customdc_stable] 2024-11-06 Custom DC stable release (#4710)
```
Rather than developing on this default branch, we recommend that you create another branch.

Sync code to the stable branch

The following procedure uses Github. If you are using another version control system, use the appropriate methods for updating submodules and syncing.

Switch to the directory where you have cloned the Data Commons code:
```
cd website | cd DIRECTORY
```
Update files:
```
git pull origin customdc_stable
```
Note that origin here refers to the source datacommonsorg/website repo. You may be using another remote name to point to that repo.

You should see output like the following:
```
From https://github.com/datacommonsorg/website
* branch              customdc_stable -> FETCH_HEAD
Already up to date.
```

Create and update the necessary submodules:

git submodule update --init --recursive

You should see output like the following:

Submodule 'import' (https://github.com/datacommonsorg/import.git) registered for path 'import'
Submodule 'mixer' (https://github.com/datacommonsorg/mixer.git) registered for path 'mixer'
Submodule path 'import': checked out '7d197583b6ad0dfe0568532f919482527c004a8e'
Submodule path 'mixer': checked out '478cd499d4841a14efaf96ccf71bd36b74604486'

Build the repo and run the services locally

Run the following command to build the repo (and run it locally):

Bash script
Docker commands

To build the image without running it:

./run_cdc_dev_docker.sh --actions build --image IMAGE_NAME:IMAGE_TAG

To build the image and start just the service container:

./run_cdc_dev_docker.sh --actions build_run --container service --image IMAGE_NAME:IMAGE_TAG

To build the image and start both containers:

./run_cdc_dev_docker.sh --actions build_run --image IMAGE_NAME:IMAGE_TAG

Build the image:

      docker build --tag IMAGE_NAME:IMAGE_TAG \
      -f build/cdc_services/Dockerfile .

Restart the services container with the custom image:

docker run -it \
      --env-file $PWD/custom_dc/env.list \
      -p 8080:8080 \
      -e DEBUG=true \
      -v INPUT_DIRECTORY:INPUT_DIRECTORY \
      -v OUTPUT_DIRECTORY:OUTPUT_DIRECTORY \
      -v $PWD/server/templates/custom_dc/PROJECT_DIRECTORY:/workspace/server/templates/custom_dc/PROJECT_DIRECTORY \
      -v $PWD/static/custom_dc/PROJECT_DIRECTORY:/workspace/static/custom_dc/PROJECT_DIRECTORY \
      IMAGE_NAME:IMAGE_TAG

The project directory is the directory you have set up for your development environment, as described in Set up your environment (or custom if you are using the default).
The image name is a meaningful name, such as datacommons-services.
The image tag is a meaningful description of the version you are building, such as latest.

It will take several minutes to build.

Once the services are up and running, visit your local instance by pointing your browser to http://localhost:8080.

To upload and deploy the container to the Cloud, see Deploy services to Google Cloud for procedures.

If you encounter any issues, look at the detailed output log on the console, and visit the Troubleshooting Guide for detailed solutions to common problems.

Page last updated: April 30, 2026 • Send feedback about this page