Stay organized with collections
Save and categorize content based on your preferences.
During development, you can run and test your container image locally, prior
to deploying. You can use Cloud Code or
Docker installed locally to run and test
locally, including running locally with access to Google Cloud services.
Running in a Knative serving emulator
The Cloud Code plugin for
VS Code and JetBrains IDEs
lets you locally run and debug your container image in a Knative serving
emulator within your IDE. The emulator allows you configure an environment that is
representative of your service running on Knative serving.
You can configure properties like CPU and memory allocation,
specify environment variables, and set Cloud SQL
database connections.
Replace IMAGE_URL with a reference to the container image, for
example, gcr.io/cloudrun/hello.
The PORT environment variable specifies the port your application will
use to listen for HTTP or HTTPS requests. This is a requirement from
the Container Runtime Contract.
In this example, we use port 8080.
If you are new to working with containers, you may want to review the
Docker Getting Started guide. To learn
more about Docker commands, refer to the
Docker documentation.
Running locally using Docker with access to Google Cloud services
If you are using Google Cloud client libraries to integrate your application
with Google Cloud services, and have not yet secured those services to control external
access, you can set up your local container to authenticate with Google Cloud
services using a service account key.
The following Docker run flags inject the credentials and configuration from
your local system into the local container:
Use the --volume (-v) flag to inject the credential file into the container
(assumes you have already set your GOOGLE_APPLICATION_CREDENTIALS environment variable on your machine):
shown in the
example above is a reasonable location to place your credentials inside the container.
However, other directory locations will also work. The crucial requirement
is that the GOOGLE_APPLICATION_CREDENTIALS environment variable must
match the bind mount location inside the container.
Note also, that with some Google Cloud services, you may want to use an alternate
configuration to isolate local troubleshooting from production performance
and data.
What's next
To learn how to deploy your built containers, follow Deploying Services.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Local testing\n\nDuring development, you can run and test your container image locally, prior\nto deploying. You can use [Cloud Code](/code) or\n[Docker installed locally](https://docs.docker.com/install/) to run and test\nlocally, including running locally with access to Google Cloud services.\n\nRunning in a Knative serving emulator\n-------------------------------------\n\nThe [Cloud Code](https://cloud.google.com/code) plugin for\n[VS Code](https://code.visualstudio.com/) and [JetBrains IDEs](https://www.jetbrains.com/)\nlets you locally run and debug your container image in a Knative serving\nemulator within your IDE. The emulator allows you configure an environment that is\nrepresentative of your service running on Knative serving.\n\nYou can configure properties like CPU and memory allocation,\nspecify environment variables, and set Cloud SQL\ndatabase connections.\n\n1. Install Cloud Code for [VS Code](/code/docs/vscode/install) or a [JetBrains IDE](/code/docs/intellij/install).\n2. Follow the instructions for locally developing and debugging within your IDE.\n - **VS Code** : Locally [developing](/code/docs/vscode/developing-a-cloud-run-app) and [debugging](/code/docs/vscode/debugging-a-cloud-run-app)\n - **IntelliJ** : Locally [developing](/code/docs/intellij/developing-a-cloud-run-app) and [debugging](/code/docs/intellij/debugging-a-cloud-run-app)\n\nRunning locally using Docker\n----------------------------\n\nTo test your container image locally using Docker:\n\n1. Use the Docker command:\n\n ```bash\n PORT=8080 && docker run -p 9090:${PORT} -e PORT=${PORT} IMAGE_URL\n ```\n\n Replace \u003cvar translate=\"no\"\u003eIMAGE_URL\u003c/var\u003e with a reference to the container image, for\n example, `gcr.io/cloudrun/hello`.\n\n The `PORT` environment variable specifies the port your application will\n use to listen for HTTP or HTTPS requests. This is a requirement from\n the [Container Runtime Contract](/kubernetes-engine/enterprise/knative-serving/docs/reference/container-contract).\n In this example, we use port 8080.\n2. Open \u003chttp://localhost:9090\u003e in your browser.\n\nIf you are new to working with containers, you may want to review the\n[Docker Getting Started](https://docs.docker.com/get-started/) guide. To learn\nmore about Docker commands, refer to the\n[Docker documentation](https://docs.docker.com/engine/reference/run/).\n\nRunning locally using Docker with access to Google Cloud services\n-----------------------------------------------------------------\n\nIf you are using Google Cloud client libraries to integrate your application\nwith Google Cloud services, and have not yet secured those services to control external\naccess, you can set up your local container to authenticate with Google Cloud\nservices using a service account key.\n| **Note:** Service account keys are a security risk if not managed correctly. You should [choose a more secure alternative to service account keys](/docs/authentication#auth-decision-tree) whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by [Best practices for managing service account keys](/iam/docs/best-practices-for-managing-service-account-keys). If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see [Managing secure-by-default organization resources](/resource-manager/docs/secure-by-default-organizations).\n|\n|\n| If you acquired the service account key from an external source, you must validate it before use.\n| For more information, see [Security requirements for externally sourced credentials](/docs/authentication/external/externally-sourced-credentials).\n\nTo run locally:\n\n1. Refer to [Service account key](/docs/authentication/set-up-adc-on-premises#wlif-key)\n for help with setting up your credentials.\n\n2. The following Docker run flags inject the credentials and configuration from\n your local system into the local container:\n\n 1. Use the `--volume` (`-v`) flag to inject the credential file into the container (assumes you have already set your `GOOGLE_APPLICATION_CREDENTIALS` environment variable on your machine): \n\n ```bash\n -v $GOOGLE_APPLICATION_CREDENTIALS:/tmp/keys/FILE_NAME.json:ro\n ```\n 2. Use the `--environment` (`-e`) flag to set the `GOOGLE_APPLICATION_CREDENTIALS` variable inside the container: \n\n ```bash\n -e GOOGLE_APPLICATION_CREDENTIALS=/tmp/keys/FILE_NAME.json\n ```\n3. Optionally, use this fully configured Docker `run` command:\n\n ```bash\n PORT=8080 && docker run \\\n -p 9090:${PORT} \\\n -e PORT=${PORT} \\\n -e K_SERVICE=dev \\\n -e K_CONFIGURATION=dev \\\n -e K_REVISION=dev-00001 \\\n -e GOOGLE_APPLICATION_CREDENTIALS=/tmp/keys/FILE_NAME.json \\\n -v $GOOGLE_APPLICATION_CREDENTIALS:/tmp/keys/FILE_NAME.json:ro \\\n IMAGE_URL\n ```\n\n Note that the path \n\n ```\n /tmp/keys/FILE_NAME.json\n ```\n shown in the example above is a reasonable location to place your credentials inside the container.\n\n \u003cbr /\u003e\n\n However, other directory locations will also work. The crucial requirement\n is that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable must\n match the bind mount location inside the container.\n\n Note also, that with some Google Cloud services, you may want to use an alternate\n configuration to isolate local troubleshooting from production performance\n and data.\n\nWhat's next\n-----------\n\nTo learn how to deploy your built containers, follow [Deploying Services](/kubernetes-engine/enterprise/knative-serving/docs/deploying)."]]