Custom runtimes let you build apps that run in an environment defined by a Dockerfile. By using a Dockerfile, you can use languages and packages that are not part of the Google Cloud Platform and use the same resources and tooling that are used in the App Engine flexible environment.
In this quickstart, an nginx web server is launched to App Engine using a custom runtime.
Before you begin
Before running the sample app in this quickstart, you need to set up your environment and create a new GCP project for App Engine:
Create a new GCP project by using the GCP Console:
Download and install the Google Cloud SDK and then initialize the
Run the following
gcloudcommand to create an App Engine application and specify in which geographical region that you want your app to run:
gcloud app create
App Engine Locations
App Engine is regional, which means the infrastructure that runs your apps is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.
Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your apps are run. You can generally select the region nearest to your app's users but you should consider the location of the other GCP products and services that are used by your app. Using services across multiple locations can affect your app's latency as well as pricing.
App Engine is available in the following regions:
southamerica-east1(São Paulo) *
* For customers using the São Paulo region, all regional product SLAs remain in force. However, multi-region and cross-region functionality that span across North America and South America might temporarily have reduced availability or performance.
You cannot change an app's region after you set it.
If you already created an App Engine application, you can view the
region by running the
gcloud app describe command or opening the
App Engine Dashboard in the GCP Console.
The region of your App Engine application is listed under
Download the Hello World app
Choose one of the following to download the Hello World sample app from GitHub, to your local machine:
Clone the Hello World sample app from the following repository:
git clone https://github.com/GoogleCloudPlatform/appengine-custom-runtimes-samples
Download the sample as a .zip file and then extract it to a local directory.
Navigate to the
nginxdirectory where the sample code is located, for example:
Running Hello World on your local machine
You can test the sample app by downloading and installing Docker, and then running the Hello World container on your local machine.
There are no App Engine specific steps here so you can test the sample app using the tools and approach that you prefer.
Deploying Hello World to App Engine
When you are ready to deploy the sample app to App Engine, perform the following steps:
From the directory where your
Dockerfileare located, run the following command:
gcloud app deploy
Learn about the optional flags.
To see your app running at
http://YOUR_PROJECT_ID.appspot.com, run the following command to launch your browser:
gcloud app browse
gcloud command flags
--versionflag to specify an ID that uniquely identifies that version of your app, otherwise one is generated for you. Example:
--projectflag to specify an alternate GCP project ID to what you initialized as the default in the
gcloud app deploy --version pre-prod-5 --project my-sample-app
To avoid incurring charges, you can delete your GCP project to stop billing for all the resources used within that project.
- In the GCP Console, go to the Projects page.
- In the project list, select the project you want to delete and click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Hello World is the simplest possible App Engine app, as it creates a single container that runs only one service and one version. This section describes each of the app's files in detail.
Specifies the configuration of the app. The
app.yamlfile must reside in the same directory as the
runtime: custom env: flex
runtime: customentry tells App Engine to look for a
Dockerfilethat will define your runtime's image and
env: flexspecifies that you are deploying to the flexible environment.
For more information, see the
Defines the set of instructions that are used to create the Docker image for the sample app's container. The
Dockerfilefile must reside in the same directory as the
Dockerfileinstalls the nginx web server and copies some basic configuration:
# The standard nginx container just runs nginx. The configuration file added # below will be used by nginx. FROM nginx # Copy the nginx configuration file. This sets up the behavior of nginx, most # importantly, it ensure nginx listens on port 8080. Google App Engine expects # the runtime to respond to HTTP requests at port 8080. COPY nginx.conf /etc/nginx/nginx.conf # create log dir configured in nginx.conf RUN mkdir -p /var/log/app_engine # Create a simple file to handle heath checks. Health checking can be disabled # in app.yaml, but is highly recommended. Google App Engine will send an HTTP # request to /_ah/health and any 2xx or 404 response is considered healthy. # Because 404 responses are considered healthy, this could actually be left # out as nginx will return 404 if the file isn't found. However, it is better # to be explicit. RUN mkdir -p /usr/share/nginx/www/_ah && \ echo "healthy" > /usr/share/nginx/www/_ah/health # Finally, all static assets. ADD www/ /usr/share/nginx/www/ RUN chmod -R a+r /usr/share/nginx/www
The FROM command builds a base image using the official docker image for the nginx web server.
Dockerfile, your container image will contain nginx and all content in the
www/directory is available to your application.
The Hello World sample app also includes an
file, which contains the basic nginx configuration information, as well was the
file, which serves as the root page for the nginx web server.
Learn more about Dockerfiles at the Dockerfile reference.
For information on how to create your own custom runtime, see Building Custom Runtimes.