How to Deploy a Go Web App to the Google App Engine 101
Table of Contents
Who is the book for?
Are you new to Go and taking part in the Go Challenge? Some of the challenges might require you to create a web app in Go and deploy it to the Google App Engine. Don’t know how? If yes, then this eBook is for you and will show you how it’s done.
What will you learn?
In the end, you will understand and know the how to deploy web apps to the Google App Engine.
Using Code Examples
All of the code in this book can be used pretty much anywhere and anyhow you please.
How to Contact Me
I can be reached via e-mail at firstname.lastname@example.org. Please contact me if you have any questions, comments, kudos or criticism on the eBook. Constructive criticism is definitely appreciated; I want this eBook to get better through your feedback.
Thanks for downloading and checking out this eBook. As part of the lean publishing philosophy, you’ll be able to interact with me as the eBook is completed. I’ll be able to change things, reorganize parts, and generally make a better eBook. I hope you enjoy.
Google App Engine
Google App Engine is different from most other cloud systems because it is neither IaaS (Infrastructure-as-a-Service, e.g., Amazon EC2) nor SaaS (Software-as-a-Service, e.g., Salesforce). It is something in-between - PaaS (Platform-as-a-Service). Instead of a fixed application (SaaS) or raw hardware (IaaS), App Engine manages your infrastructure for users. Furthermore, it provides a development platform… users get to create apps, not use the ones provided by the cloud vendor, and it leverages the infrastructure as a hosting platform.
Google App Engine lets you run web applications on Google’s infrastructure. With App Engine, there are no servers to maintain: You just upload your application, and it is ready to serve your users. App Engine costs nothing to get started. All applications can use up to 1 GB of storage and enough CPU and bandwidth to support an efficient app serving around 5 million page views a month, absolutely free.
Creating an App Engine application is easy, and only takes a few minutes. And it is free to start: upload your app and share it with users right away, at no charge and with no commitment required.
Developers would not be interested in letting other applications/users get any kind of access to their application code or data. To ensure this, all App Engine applications run in a restricted environment known as a sandbox.
The App Engine team has created a set of higher-level APIs/services for developers to use. Want your app to send and receive e-mail or instant messages? That’s what the e-mail and XMPP APIs are for! Want to reach out to other web applications? Use the
URLfetch service! Need Memcache? Google has a global Memcache API. Need a database? Google provides both its traditional NoSQL scalable datastore and access to the relational MySQL-compatible Google Cloud SQL service.
The list of all the services that are available to users changes quite often as new APIs are created.
The Administration Console
The Google App Engine Administration Console gives you complete access to the public version of your application. Access the Console by visiting this link in your web browser. Google recommends that you use the Google Developers Console instead. The Developers Console supports all the Cloud Platform products, including App Engine, as well as other Google developer APIs.
Applications (web and non-web)
While many applications running on Google App Engine are web-based apps, they are certainly not limited to those. App Engine is also a popular backend system for mobile apps. When developing such apps, it’s much safer to store data in a distributed manner and not solely on devices which could get lost, stolen, or destroyed. Putting data in the cloud improves the user experience because recovery is simplified and users have more access to their data.
App Engine Datastore is a schemaless object datastore providing robust, scalable storage for your web application. This means that you can’t run MongoDB, for example, on the Google App Engine (GAE). You need to use the Google datastore. However, GAE now supports Google Cloud SQL a fully managed MySQL service hosted on Google Cloud Platform.
The Go runtime environment
With the Google App Engine for Go, you can build web applications using the Go Programming Language. Your Go application runs on Google’s scalable infrastructure and uses large-scale persistent storage and services.
App Engine builds and executes Go application code using a safe “sandboxed” environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.
The Go runtime environment uses the latest version of Go version 1.4. The SDK includes the Go compiler and standard library, so it has no additional dependencies. As with the other runtimes, not all the standard library’s functionality is available inside the sandbox. For example, attempts to open a socket or write to a file will return an
The SDK includes an automated build service to compile your app, so you’ll never need to invoke the compiler yourself. And your app will be automatically re-built whenever you change the source.
Go apps run inside a secure “sandbox” environment with a reduced set of libraries. For instance, an app cannot write data to the local file system or make arbitrary network connections. Instead, apps use scalable services provided by App Engine to store data and communicate over the Internet.
Download and Install the App Engine SDK
To start developing Google App Engine applications in Go, you first download and set up the App Engine Go software development kit (SDK).
The Go SDK includes a web server application that simulates the App Engine environment, including a local version of the datastore, Google Accounts, and the ability to fetch URLs and send email directly from your computer using the App Engine APIs.
The Go SDK will run on any Intel-based Mac OS X, Linux or Windows computer with Python 2.7. If necessary, download and install Python 2.7 for your platform from the Python web site. Most Mac OS X users already have Python 2.7 installed. If you have issues with the Python tools, please ensure you have Python 2.7 installed.
Let us now download the App Engine SDK. Next follow the instructions on the download page to install the SDK on your computer.
I installed the App Engine SDK to
C:\go_appengine on my Windows 7 desktop.
Later on in this article, we will use the following two commands from the SDK:
- goapp serve - for running a local development server
- goapp deploy - for uploading your app to App Engine
You can find these commands in the
C:\go_appengine directory. To simplify development and deployment, consider adding this directory to your
PATH environment variable.
Let us build a small app (mytext.go) locally
The local development environment lets you develop and test complete App Engine applications before showing them to the world. Let us write some code.
Go App Engine applications communicate with the outside world via a web server compatible with Go’s http package. This makes writing Go App Engine applications very similar to writing stand-alone Go web applications.
Let us begin by implementing a tiny application that displays a short message to a user.
Inside the folder
$GOPATH/src/github.com/SatishTalim create the folder
Next inside the
mytext folder, create a file named
mytext.go, and give it the following contents:
This Go package responds to any request by sending a response containing the message:
Hello. This is our first Go web app for the Google App Engine!
- when writing a stand-alone Go program we would place this code in package
main. The Go App Engine Runtime provides a special
mainpackage, so you should put HTTP handler code in a package of your choice (in this case,
- to work with some printing functions, we import the package fmt.
- the App Engine Go API uses the standard
httppackage as an interface between your Go program and the App Engine servers. Thus for web related
httpfunctionality, we import the package http. Any functions within that we refer as
- within the
initprogram, we redirect any incoming requests to the
handlerfunction. We do this by calling http.HandleFunc and passing it two parameters - the first one is a part of the incoming url, and the second is the method capable of handling it.
- the function
http.Requestas its arguments.
- when a user connects, the programs responds with a text that is sent back to the browser. The
http.ResponseWritervalue assembles the HTTP server’s response; by writing to it, we send data to the HTTP client.
http.Requestis a data structure that represents the client HTTP request.
- all the parameters of a request can be received via the parameter
handler. You can get the URL, the input values and other details.
Create the Configuration File
An App Engine application has a configuration file called
app.yaml. Among other things, this file tells the App Engine service which runtime to use and which URLs should be handled by our Go program.
$GOPATH/src/github.com/SatishTalim/mytext directory, create a file named
app.yaml with the following contents:
From top to bottom, this configuration file says the following about this application:
- The application identifier is
helloworld. When you register your application with App Engine later on, you will select a unique identifier, and update this value (later on we will update the value to
gochgmsg). This value can be anything during development. For now, leave it set to
- This is version number
1-0of this application’s code. Your application versioning information can contain alphanumeric characters, and hyphens. If you adjust this before uploading new versions of your application software, App Engine will retain previous versions, and let you roll back to a previous version using the administrative console.
- This code runs in the
goruntime environment, with API version
- There are two kinds of handlers: script handlers, and static file handlers. A script handler runs a Go script in your application to determine the response for the given URL. A static file handler returns the contents of a file, such as an image, as the response.
urlis a URL prefix. This value uses regular expression syntax (and so regexp special characters must be escaped
\). All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path.
- Every request to a URL whose path matches the regular expression
/.*(all URLs) should be handled by the Go program.
- For Go apps,
scriptshould always have a value of
Note: All Go packages for a given app are built into a single executable, and request dispatch is handled by the Go program itself. This is why we call
http.HandleFunc inside the
init function to associate our handler with the web root (
"/"). However, you may still use the
app.yaml file to configure paths that serve static files or require special permissions.
For a complete list of configuration options, see the Go Application Configuration page.
Test the App
You can now test your app with the web server included with the App Engine SDK.
The application’s directory should contain the files
$GOPATH/src/github.com/SatishTalim directory run the following command, to compile your app and start the development web server:
goapp serve mytext/
The web server is now running, listening for requests on port 8080. Test the application by visiting the following URL in your web browser: http://localhost:8080/. For more information about running the development web server, including how to change which port it uses, see the Development Server reference.
The development app server knows to watch for changes in your file. As you update your source, it re-compiles them and relaunches your local app. There’s no need to restart
Try it now: leave the web server running, then edit
mytext.go to change
Hello. This is our first Go web app for the Google App Engine! to something else. Reload http://localhost:8080/ to see the change.
To shut down the web server, make sure the terminal window is active, then press
Control-C (or the appropriate “break” key for your console).
You now have a complete App Engine application! You could deploy this simple program right now and share it with users worldwide.
Uploading Your App to Google’s App Engine
Registering the App
You will now need to have a Google account. If you do not have a Google account, you can create a Google account with an email address and password.
You create and manage App Engine web applications from the Developer’s Console. Sign in to App Engine using your Google account.
To create a new application, click the “Create a Project” button. A screen pops up as shown below:
gochgmsg for the Project name. It creates a unique project ID which in our case is
We have elected to use the free “appspot.com” domain name. With that, the full URL for the application will be
app.yaml file, then change the value of the application: setting from
Upload and Access the app
From the folder:
$GOPATH/src/github.com/SatishTalim folder, type:
If you see compilation errors, fix the source and re-run
goapp deploy; it won’t launch (or update) your app until compilation is successful.
Note: One issue that users could face while deploying the app — if you have multiple Google Accounts and the default one in which you are logged in currently is not the one that is containing the App Engine project, then the
goapp deploy will fail with the error “The application does not exist ..<appid>", etc. Unfortunately, the only recourse then is that the default account is the one owning the App Engine app or you have to use the `appcfg.py` command to set the no_cookies, etc. and do the deploy again.</appid>
App Engine determines that an incoming request is intended for your application using the domain name of the request. A request whose domain name is
http://your_app_id.appspot.com is routed to the application whose ID is
your_app_id. Every application gets an
appspot.com domain name for free.
Requests for these URLs all go to the version of your application that you have selected as the default version in the App Engine Administration Console. Each version of your application also has its own URL, so you can deploy and test a new version before making it the default version. The version-specific URL uses the version identifier from your app’s configuration file in addition to the
appspot.com domain name, in this pattern: