English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Hello, World!

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's begin by implementing a tiny application that displays a short message.

## Creating a Simple HTTP Handler

Create a directory named `myapp`. All files for this application reside in this directory.

Inside the `myapp` directory, create another directory named `hello`. This will contain the Go source files for our `hello` package.

Inside the `hello` directory, create a file named `hello.go`, and give it the following contents:

    package hello

    import (
        "fmt"
        "http"
    )

    func init() {
        http.HandleFunc("/", handler)
    }

    func handler(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "Hello, world!")
    }

This Go package responds to any request by sending a response containing the message `Hello, world!`.

Note: When writing a stand-alone Go program we would place this code in package `main`. The Go App Engine Runtime provides a special `main` package, so you should put HTTP handler code in a package of your choice (in this case, `hello`).

## Creating 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.

Inside the `myapp` directory, create a file named `app.yaml` with the following contents:

    application: helloworld
    version: 1
    runtime: go
    api_version: 3

    handlers:
    - url: /.*
      script: _go_app

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 in this tutorial, you will select a unique identifier, and update this value. This value can be anything during development. For now, leave it set to `helloworld`.
- This is version number `1` of this application's code. 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 `go` runtime environment, with API version `3`.
- Every request to a URL whose path matches the regular expression `/.*` (all URLs) should be handled by the Go program. The `_go_app` value is a magic string recognized by the `dev_appserver.py`; it is ignored by the production App Engine servers.

Note: the Go SDK does things differently than the Python and Java SDKs: 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.

The syntax of this file is YAML. For a complete list of configuration options, see the app.yaml reference.

## Testing the Application

With the `hello` package and configuration file mapping every URL to the Go program, the application is complete. You can now test it with the web server included with the App Engine SDK.

Check that you have everything in its right place. The application's directory structure should look like this:

    myapp/
      app.yaml
      hello/
        hello.go

Run the following command, giving it the path to the `myapp` directory, to compile your app and start the development web server:

    /path/to/google_appengine/dev_appserver.py myapp/

(You may drop the `/path/to/google_appengine/` if you added it to your `PATH`, as suggested earlier.)

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 Dev Web Server reference, or run the command with the option `--help`.

## Iterative Development

The development app server knows to watch for changes in your file. As you update your source, it recompiles them and relaunches your local app. There's no need to restart `dev_appserver.py`.

Try it now: leave the web server running, then edit `hello.go` to change `Hello, world!` 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).

Leave the web server running for the rest of this tutorial. If you need to stop it, you can restart it again by running the command above.

## Next...

You now have a complete App Engine application! You could deploy this simple greeting right now and share it with users worldwide. But before we deploy it, let's add some features.

Continue to Using the Users Service.