Setting up Your Project and Application

Set up and structure a basic App Engine application, test it locally, and deploy the application.

This page and sample are part of an extended learning example of a simple blog application where users can upload posts. You should already be familiar with the Go programming language and basic web development. To see an overview of all the pages in this example, go to Building an App with Go.

Costs

There are no costs associated with running this guide. Running this sample app alone does not exceed your free quota.

Before you begin

Before developing your application, complete the following steps:

Create a new Google Cloud Platform project and App Engine application using the Google Cloud Platform Console:

Go to the GCP Console

When prompted, select the region where you want your App Engine application located. After your application is created, you will be on the App Engine Dashboard.
Download and install Cloud SDK and then initialize the gcloud tool:

Download Cloud SDK
Install Go.
Get the required external App Engine library:
```
go get -u google.golang.org/appengine/...
```

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:

northamerica-northeast1 (Montréal)
us-central (Iowa)
us-west2 (Los Angeles)
us-east1 (South Carolina)
us-east4 (Northern Virginia)
southamerica-east1 (São Paulo)
europe-west (Belgium)
europe-west2 (London)
europe-west3 (Frankfurt)
europe-west6 (Zürich)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
asia-east2 (Hong Kong)
asia-south1 (Mumbai)
australia-southeast1 (Sydney)

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 http://[YOUR_PROJECT_ID].appspot.com.

Structuring your application project

At the end of this example, you'll have a project named go-app with the following structure:

go-app/: Project root directory.
- app.yaml: Configuration settings for your App Engine application.
- main.go: Your application code.

Creating your `app.yaml` file

app.yaml sets the basic configuration for your App Engine application's settings.

To set up your app.yaml file:

Create your project root directory:
```
mkdir $GOPATH/src/go-app
```
Change directory to your project root:
```
cd $GOPATH/src/go-app
```
Create app.yaml in your project root directory.

Add the following lines to app.yaml:

appengine/gophers/gophers-1/app.yaml

View on GitHub

# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

runtime: go
api_version: go1

handlers:

# All URLs are handled by the Go application script
- url: /.*
  script: _go_app

When App Engine receives a web request for your application, the server calls the handler script corresponding to the URL, as specified in app.yaml. The handler then calls the application object to perform actions to service the request, prepare a response, and return it as a list of strings.

For information about the settings available for app.yaml, see the app.yaml reference documentation.

Creating your `main.go` file

This simple sample uses the net/http package to create an HTTP server that prints the title of your application, Gopher Network.

To set up your main.go file:

Create main.go in your project root directory.
Add the package main statement to treat your code as an executable program:
```
package main
```
Import the following packages to main.go:

appengine/gophers/gophers-1/main.go

View on GitHub
```
import (
	"fmt"
	"net/http"

	"google.golang.org/appengine" // Required external App Engine library
)
```
The google.golang.org/appengine package provides basic functionality for App Engine applications.

The net/http package provides the HandlerFunc type, which you use to respond to different HTTP requests.

Define your HTTP handler in main.go:

appengine/gophers/gophers-1/main.go

View on GitHub

func indexHandler(w http.ResponseWriter, r *http.Request) {
	// if statement redirects all invalid URLs to the root homepage.
	// Ex: if URL is http://[YOUR_PROJECT_ID].appspot.com/FOO, it will be
	// redirected to http://[YOUR_PROJECT_ID].appspot.com.
	if r.URL.Path != "/" {
		http.Redirect(w, r, "/", http.StatusFound)
		return
	}

	fmt.Fprintln(w, "Hello, Gopher Network!")
}

The http.ResponseWriter value assembles the HTTP server response; by writing to it, you send data to the browser. The http.Request is a data structure that represents the incoming HTTP request.

Register your HTTP handler in main.go:

appengine/gophers/gophers-1/main.go

View on GitHub
```
func main() {
	http.HandleFunc("/", indexHandler)
	appengine.Main() // Starts the server to receive requests
}
```
The main function is the entry point of your executable program, so it starts the application. It begins with a call to the http.HandleFunc function which tells the http package to handle all requests to the web root ("/") with the indexHandler function.

Running your application locally

Run and test your application using the local development server (dev_appserver.py), which is included with the Cloud SDK.

From the project root directory where your application's app.yaml is located, start the local development server with the following command:
```
dev_appserver.py app.yaml
```
The local development server is now running and listening for requests on port 8080. Something go wrong?
Visit http://localhost:8080/ in your web browser to view the app.

Running the local development server (`dev_appserver.py`)

To run the local development server, you can either run dev_appserver.py by specifying the full directory path or you can add dev_appserver.py to your PATH environment variable:

If you installed the original App Engine SDK, the tool is located at:
```
[PATH_TO_APP_ENGINE_SDK]/dev_appserver.py
```
If you installed the Google Cloud SDK, the tool is located at:
```
[PATH_TO_CLOUD_SDK]/google-cloud-sdk/bin/dev_appserver.py
```
Tip: To add the Google Cloud SDK tools to your PATH environment variable and enable command-completion in your shell, you can run:
```
[PATH_TO_CLOUD_SDK]/google-cloud-sdk/install.sh
```

For more information about running the local development server including how to change the port number, see the Local Development Server reference.

Making code changes

The local development server watches for changes in your project files, so it recompiles and re-launches your application after you make code changes.

Try it now: Leave the local development server running and then try editing main.go to change "Gopher Network" to something else.
Reload http://localhost:8080/ to see the change.

Deploying your application

Deploy your application to App Engine using the following command from the project root directory where the app.yaml file is located:

gcloud app deploy

Viewing your application

To launch your browser and view your application at http://[YOUR_PROJECT_ID].appspot.com, run the following command:

gcloud app browse

What's next

You just set up and deployed your web application to App Engine!

Next, learn how to securely serve static content such as HTML pages, CSS files, or images from your application.

Was this page helpful? Let us know how we did:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated June 3, 2019.