This guide covers how to structure the services and related resources of yourApp Engine app.

Directory structure

Each version of your App Engine service is defined in anapp.yamlconfiguration file. For simple apps, the minimum requirement for deployment isto define theapp.yaml file. Theapp.yaml file acts as a deploymentdescriptor and defines the scaling type and theruntime, handlers, and other resourcesettings for a specificversion of a service. If you are deploying several versions of a service, youcan create multiple YAML files in the same directory to represent theconfiguration for each of your versions.

The otheroptional configuration files shouldreside in the root directory or repository of thedefault service of your app. These optionalconfiguration files apply app-wide settings that are not specific to aparticular service, including thedispatch.yaml,index.yaml, andcron.yamlfiles.

Examples

A simple app only requires theapp.yaml to be added in the same location asthe app's source files. For a single service app, that app will only include thedefault service and all the files can live in the samedirectory, at the root of that app:

The following example demonstrates how to structure what an app with three services might looklike if you are developing your app locally. The optionaldispatch.yaml file hasbeen added to that app in the root directory. Also in the root are threedirectories for each of the app's services. The subdirectory forservice1includes the source and configuration files for that service. Similarly, bothservice2 andservice3 are in separate directories, which contain eachservice's files, althoughservice3 includes two versions of the YAMLconfiguration file:

In the following example, a single service has the optionaldispatch.yaml fileand two configuration files that represent different versions of that service,service1.yaml andservice2.yaml:

Design considerations for instance uptime

Hardware or software failures that cause early termination or frequent instancerestarts can occur without warning and can take considerable time to resolve.Your application should be able to handle such failures.

Here are some good strategies for avoiding downtime due to instance restarts:

• Reduce the amount of time it takes for your instances restart or for new onesto start.
• For long-running computations, periodically create checkpoints so that youcan resume from that state.
• Your app should be "stateless" so that nothing is stored on the instance.
• Use queues for performing asynchronous task execution.
• If you configure your instances to manual scaling:
  • Use load balancing across multiple instances.
  • Configure more instances than required to handle normal traffic.
  • Write fall-back logic that uses cached results when a manual scalinginstance is unavailable.

Learn more about instances atHow instances aremanaged.

Thedefault service

Every App Engine application includes adefault service. You mustdeploy the initial version of your app to thedefault service before you cancreate and deploy additional services to your app.

The default service can be optionally specified in theapp.yaml with the settingservice: default.

If you use Java and the legacy bundled services, you canspecify the default service in theappengine-web.xml with thesetting<service>default</service>.

Requests sent to your app using your Google Cloud project are sent to thedefault service, for example,https://PROJECT_ID.REGION_ID.r.appspot.com. To learnmore about targeting your other services, seeCommunicating BetweenServices.

Optional configuration files

The following configuration files control optional features that apply to all ofthe services in an individual app. See the following topics for details abouteach of the optional features:

• cron.yamlconfigures regularly scheduled tasks that operate at defined times or regularintervals.
• dispatch.yamloverrides routing default rules by sending incoming requests to a specificservice based on the path or hostname in the URL.
• index.yamlspecifies which indexes your app needs if using Datastore queries.

File names

App Engine runs apps in a container on an up-to-date Ubuntu Linuxdistribution. The file names you use in the App Engine standard environment must beUTF-8 compatible, either UTF-8 or something that can be safely auto-convertedto UTF-8. If your file names use different encodings, deploy your app from a machinewith UTF-8 compatible filename language settings.

Deployment fails if file names are not UTF-8 compatible. Note thatthere's no restriction on the characterencoding you use within a file.

Data and file storage considerations

From App Engine, you can easily access other Google Cloudservices such asDatastore,Cloud SQL, andCloud Storage.

You also have the option to use an external or third-party database if thatdatabase is supported by your language and accessible from yourApp Engine instance.

For details about storing files in Google Cloud or externally, seeUnderstanding Data and File Storage.

You can also choose how you want to serve your static content. You can serveyour app's static content directly from that app in App Engine, hostyour static content on a Google Cloud option likeCloud Storage, or use a third-party content delivery network (CDN).For more information about serving static content, seeServing StaticFiles.

What's next

If you are working with multiple services and want to deploy them together, see the steps todeploy multiple services.