From cac05d5e7fa7931fbbc9e55980d251b497d9a773 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Mon, 4 Apr 2016 15:07:21 -0700 Subject: [PATCH] Improve READMEs for App Engine samples. These are linked to from https://cloud.google.com/java/, so we should have a more welcoming landing page than the existing list of folders. --- appengine/README.md | 101 ++++++++++++++++++++++++++++++++ appengine/appidentity/README.md | 7 ++- appengine/helloworld/README.md | 17 ++++-- appengine/mailgun/README.md | 11 ++++ appengine/sendgrid/README.md | 28 +++++++-- appengine/twilio/README.md | 36 +++++++++--- managed_vms/README.md | 11 ++-- managed_vms/sendgrid/README.md | 28 +++++++-- managed_vms/twilio/README.md | 36 +++++++++--- 9 files changed, 240 insertions(+), 35 deletions(-) create mode 100644 appengine/README.md create mode 100644 appengine/mailgun/README.md diff --git a/appengine/README.md b/appengine/README.md new file mode 100644 index 00000000000..6781e06b6c1 --- /dev/null +++ b/appengine/README.md @@ -0,0 +1,101 @@ +# Google App Engine Standard Environment Java Samples + +This is a repository that contains Java code samples for [Google App Engine +standard environment][ae-docs]. + +[ae-docs]: https://cloud.google.com/appengine/docs/java/ + +## Prerequisites + +### Download Maven + +These samples use the [Apache Maven][maven] build system. Before getting +started, be sure to [download][maven-download] and [install][maven-install] it. +When you use Maven as described here, it will automatically download the needed +client libraries. + +[maven]: https://maven.apache.org +[maven-download]: https://maven.apache.org/download.cgi +[maven-install]: https://maven.apache.org/install.html + +### Create a Project in the Google Cloud Platform Console + +If you haven't already created a project, create one now. Projects enable you to +manage all Google Cloud Platform resources for your app, including deployment, +access control, billing, and services. + +1. Open the [Cloud Platform Console][cloud-console]. +1. In the drop-down menu at the top, select **Create a project**. +1. Give your project a name. +1. Make a note of the project ID, which might be different from the project + name. The project ID is used in commands and in configurations. + +[cloud-console]: https://console.cloud.google.com/ + + +## Samples + +### Hello World + +This sample demonstrates how to deploy an application on Google App Engine. + +- [Documentation][ae-docs] +- [Code](helloworld) + +### Sending Email + +#### Sending Email with Mailgun + +This sample demonstrates how to send email using the [Mailgun API][mailgun-api]. + +- [Documentation][mailgun-sample-docs] +- [Code](mailgun) + +[mailgun-api]: https://documentation.mailgun.com/ +[mailgun-sample-docs]: https://cloud.google.com/appengine/docs/java/mail/mailgun + +#### Sending Email with SendGrid + +This sample demonstrates how to send email using the [SendGrid][sendgrid]. + +- [Documentation][sendgrid-sample-docs] +- [Code](sendgrid) + +[sendgrid]: https://sendgrid.com/docs/User_Guide/index.html +[sendgrid-sample-docs]: https://cloud.google.com/appengine/docs/java/mail/sendgrid + +### Sending SMS with Twilio + +This sample demonstrates how to use [Twilio](https://www.twilio.com) on [Google +App Engine standard environment][ae-docs]. + +- [Documentation][twilio-sample-docs] +- [Code](twilio) + +[twilio-sample-docs]: https://cloud.google.com/appengine/docs/java/sms/twilio + +### App Identity + +This sample demonstrates how to use the [App Identity API][appid] to discover +the application's ID and assert identity to Google and third-party APIs. + +- [Documentation][appid] +- [Code](appidentity) + +[appid]: https://cloud.google.com/appengine/docs/java/appidentity/ + +### Other Samples + +- [Sample Applications][sample-apps] + +[sample-apps]: https://cloud.google.com/appengine/docs/java/samples + + +## Contributing changes + +See [CONTRIBUTING.md](../CONTRIBUTING.md). + +## Licensing + +See [LICENSE](../LICENSE). + diff --git a/appengine/appidentity/README.md b/appengine/appidentity/README.md index a60a9fafdc1..5f5c13bd111 100644 --- a/appengine/appidentity/README.md +++ b/appengine/appidentity/README.md @@ -1,5 +1,10 @@ # App Identity sample for Google App Engine -This sample demonstrates how to use the App Identity APIs on Google App Engine + +This sample demonstrates how to use the [App Identity API][appid] on [Google App +Engine][ae-docs]. + +[appid]: https://cloud.google.com/appengine/docs/java/appidentity/ +[ae-docs]: https://cloud.google.com/appengine/docs/java/ ## Running locally This example uses the diff --git a/appengine/helloworld/README.md b/appengine/helloworld/README.md index cab559c289d..9cdb309b185 100644 --- a/appengine/helloworld/README.md +++ b/appengine/helloworld/README.md @@ -1,8 +1,17 @@ -# Appengine Helloworld sample for Google App Engine -This sample demonstrates how to deploy an application on Google App Engine +# Google App Engine Standard Environment Hello World Sample + +This sample demonstrates how to deploy an application on Google App Engine. + +See the [Google App Engine standard environment documentation][ae-docs] for more +detailed instructions. + +[ae-docs]: https://cloud.google.com/appengine/docs/java/ + ## Setup -1. Update the tag in src/main/webapp/WEB-INF/appengine-web.xml with your project name -1. Update the tag in src/main/webapp/WEB-INF/appengine-web.xml with your version name +1. Update the `` tag in `src/main/webapp/WEB-INF/appengine-web.xml` + with your project name. +1. Update the `` tag in `src/main/webapp/WEB-INF/appengine-web.xml` + with your version name. ## Running locally $ mvn appengine:devserver diff --git a/appengine/mailgun/README.md b/appengine/mailgun/README.md new file mode 100644 index 00000000000..582771ddb34 --- /dev/null +++ b/appengine/mailgun/README.md @@ -0,0 +1,11 @@ +# Java Mailgun Email Sample for Google App Engine Standard Environment + +This sample demonstrates how to use [Mailgun][mailgun-api] on [Google App Engine +standard environment][ae-docs]. + +See the [sample application documentaion][sample-docs] for more detailed +instructions. + +[ae-docs]: https://cloud.google.com/appengine/docs/java/ +[mailgun-api]: https://documentation.mailgun.com/ +[sample-docs]: https://cloud.google.com/appengine/docs/java/mail/mailgun diff --git a/appengine/sendgrid/README.md b/appengine/sendgrid/README.md index 4a76dd9fd2b..76032775b7a 100644 --- a/appengine/sendgrid/README.md +++ b/appengine/sendgrid/README.md @@ -1,13 +1,31 @@ -# Java SendGrid email sample for Google Managed VMs -This sample demonstrates how to use [SendGrid](https://www.sendgrid.com) on Google Managed VMs -For more information about SendGrid, see their [documentation](https://sendgrid.com/docs/User_Guide/index.html). +# Java SendGrid Email Sample for Google App Engine Standard Environment + +This sample demonstrates how to use [SendGrid](https://www.sendgrid.com) on +[Google App Engine standard environment][ae-docs]. + +See the [sample application documentaion][sample-docs] for more detailed +instructions. + +For more information about SendGrid, see their +[documentation](https://sendgrid.com/docs/User_Guide/index.html). + +[ae-docs]: https://cloud.google.com/appengine/docs/java/ +[sample-docs]: https://cloud.google.com/appengine/docs/java/mail/sendgrid + ## Setup + Before you can run or deploy the sample, you will need to do the following: -1. [Create a SendGrid Account](http://sendgrid.com/partner/google). As of September 2015, Google users start with 25,000 free emails per month. -1. Configure your SendGrid settings in the environment variables section in ``src/main/appengine/app.yaml``. + +1. [Create a SendGrid Account](http://sendgrid.com/partner/google). As of + September 2015, Google users start with 25,000 free emails per month. +1. Configure your SendGrid settings in the environment variables section in + [`src/main/webapp/WEB-INF/appengine-web.xml`](src/main/webapp/WEB-INF/appengine-web.xml). + ## Running locally + You can run the application locally and send emails from your local machine. You will need to set environment variables before starting your application: + $ export SENDGRID_API_KEY=[your-sendgrid-api-key] $ export SENDGRID_SENDER=[your-sendgrid-sender-email-address] $ mvn clean jetty:run diff --git a/appengine/twilio/README.md b/appengine/twilio/README.md index d9da6335902..16c71862da1 100644 --- a/appengine/twilio/README.md +++ b/appengine/twilio/README.md @@ -1,16 +1,36 @@ -# Java Twilio voice and SMS sample for Google Managed VMs -This sample demonstrates how to use [Twilio](https://www.twilio.com) on Google Managed VMs -For more information about Twilio, see their [Java quickstart tutorials](https://www.twilio.com/docs/quickstart/java). +# Java Twilio Voice and SMS Sample for Google App Engine Standard Environment + +This sample demonstrates how to use [Twilio](https://www.twilio.com) on [Google +App Engine standard environment][ae-docs]. + +See the [sample application documentaion][sample-docs] for more detailed +instructions. + +For more information about Twilio, see their [Java quickstart +tutorials](https://www.twilio.com/docs/quickstart/java). + +[ae-docs]: https://cloud.google.com/appengine/docs/java/ +[sample-docs]: https://cloud.google.com/appengine/docs/java/sms/twilio + + ## Setup + Before you can run or deploy the sample, you will need to do the following: -1. [Create a Twilio Account](http://ahoy.twilio.com/googlecloudplatform). Google App Engine -customers receive a complimentary credit for SMS messages and inbound messages. -1. Create a number on twilio, and configure the voice request URL to be ``https://your-app-id.appspot.com/call/receive`` -and the SMS request URL to be ``https://your-app-id.appspot.com/sms/receive``. -1. Configure your Twilio settings in the environment variables section in ``src/main/appengine/app.yaml``. + +1. [Create a Twilio Account](http://ahoy.twilio.com/googlecloudplatform). Google + App Engine customers receive a complimentary credit for SMS messages and + inbound messages. +1. Create a number on twilio, and configure the voice request URL to be + ``https://your-app-id.appspot.com/call/receive`` and the SMS request URL to + be ``https://your-app-id.appspot.com/sms/receive``. +1. Configure your Twilio settings in the environment variables section in + [`src/main/webapp/WEB-INF/appengine-web.xml`](src/main/webapp/WEB-INF/appengine-web.xml). + ## Running locally + You can run the application locally to test the callbacks and SMS sending. You will need to set environment variables before starting your application: + $ export TWILIO_ACCOUNT_SID=[your-twilio-accoun-sid] $ export TWILIO_AUTH_TOKEN=[your-twilio-auth-token] $ export TWILIO_NUMBER=[your-twilio-number] diff --git a/managed_vms/README.md b/managed_vms/README.md index 2d3368f5333..3941b4fc74c 100644 --- a/managed_vms/README.md +++ b/managed_vms/README.md @@ -1,11 +1,14 @@ -## Google Managed VMs Java Samples +# Google App Engine Flexible Environment Java Samples -This is a repository that contains Java code samples for Google Managed VMs +This is a repository that contains Java code samples for [Google App Engine +flexible environment][aeflex-docs]. -See our other [Google Cloud Platform github +See our other [Google Cloud Platform GitHub repos](https://github.com/GoogleCloudPlatform) for sample applications and scaffolding for other frameworks and use cases. +[aeflex-docs]: https://cloud.google.com/appengine/docs/flexible/ + ## Run Locally 1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/), including the [gcloud tool](https://cloud.google.com/sdk/gcloud/), and [gcloud app component](https://cloud.google.com/sdk/gcloud-app). 1. Setup the gcloud tool. @@ -17,7 +20,7 @@ scaffolding for other frameworks and use cases. 1. Clone this repo. ``` - git clone https://github.com/GoogleCloudPlatform/.git + git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git ``` 1. Run this project locally from the command line. diff --git a/managed_vms/sendgrid/README.md b/managed_vms/sendgrid/README.md index 4a76dd9fd2b..d7786659624 100644 --- a/managed_vms/sendgrid/README.md +++ b/managed_vms/sendgrid/README.md @@ -1,13 +1,31 @@ -# Java SendGrid email sample for Google Managed VMs -This sample demonstrates how to use [SendGrid](https://www.sendgrid.com) on Google Managed VMs -For more information about SendGrid, see their [documentation](https://sendgrid.com/docs/User_Guide/index.html). +# Java SendGrid Email Sample for Google App Engine Flexible Environment + +This sample demonstrates how to use [SendGrid](https://www.sendgrid.com) on +[Google App Engine flexible environment][aeflex-docs]. + +See the [sample application documentaion][sample-docs] for more detailed +instructions. + +For more information about SendGrid, see their +[documentation](https://sendgrid.com/docs/User_Guide/index.html). + +[aeflex-docs]: https://cloud.google.com/appengine/docs/flexible/ +[sample-docs]: https://cloud.google.com/appengine/docs/flexible/java/sending-emails-with-sendgrid + ## Setup + Before you can run or deploy the sample, you will need to do the following: -1. [Create a SendGrid Account](http://sendgrid.com/partner/google). As of September 2015, Google users start with 25,000 free emails per month. -1. Configure your SendGrid settings in the environment variables section in ``src/main/appengine/app.yaml``. + +1. [Create a SendGrid Account](http://sendgrid.com/partner/google). As of + September 2015, Google users start with 25,000 free emails per month. +1. Configure your SendGrid settings in the environment variables section in + [`src/main/appengine/app.yaml`](src/main/appengine/app.yaml). + ## Running locally + You can run the application locally and send emails from your local machine. You will need to set environment variables before starting your application: + $ export SENDGRID_API_KEY=[your-sendgrid-api-key] $ export SENDGRID_SENDER=[your-sendgrid-sender-email-address] $ mvn clean jetty:run diff --git a/managed_vms/twilio/README.md b/managed_vms/twilio/README.md index d9da6335902..a1234c78af6 100644 --- a/managed_vms/twilio/README.md +++ b/managed_vms/twilio/README.md @@ -1,16 +1,36 @@ -# Java Twilio voice and SMS sample for Google Managed VMs -This sample demonstrates how to use [Twilio](https://www.twilio.com) on Google Managed VMs -For more information about Twilio, see their [Java quickstart tutorials](https://www.twilio.com/docs/quickstart/java). +# Java Twilio Voice and SMS Sample for Google App Engine Flexible Environment + +This sample demonstrates how to use [Twilio](https://www.twilio.com) on [Google +App flexible environment][aeflex-docs]. + +See the [sample application documentaion][sample-docs] for more detailed +instructions. + +For more information about Twilio, see their [Java quickstart +tutorials](https://www.twilio.com/docs/quickstart/java). + +[aeflex-docs]: https://cloud.google.com/appengine/docs/flexible/ +[sample-docs]: https://cloud.google.com/appengine/docs/flexible/java/using-sms-and-voice-services-via-twilio + + ## Setup + Before you can run or deploy the sample, you will need to do the following: -1. [Create a Twilio Account](http://ahoy.twilio.com/googlecloudplatform). Google App Engine -customers receive a complimentary credit for SMS messages and inbound messages. -1. Create a number on twilio, and configure the voice request URL to be ``https://your-app-id.appspot.com/call/receive`` -and the SMS request URL to be ``https://your-app-id.appspot.com/sms/receive``. -1. Configure your Twilio settings in the environment variables section in ``src/main/appengine/app.yaml``. + +1. [Create a Twilio Account](http://ahoy.twilio.com/googlecloudplatform). Google + App Engine customers receive a complimentary credit for SMS messages and + inbound messages. +1. Create a number on twilio, and configure the voice request URL to be + ``https://your-app-id.appspot.com/call/receive`` and the SMS request URL to + be ``https://your-app-id.appspot.com/sms/receive``. +1. Configure your Twilio settings in the environment variables section in + ``src/main/appengine/app.yaml``. + ## Running locally + You can run the application locally to test the callbacks and SMS sending. You will need to set environment variables before starting your application: + $ export TWILIO_ACCOUNT_SID=[your-twilio-accoun-sid] $ export TWILIO_AUTH_TOKEN=[your-twilio-auth-token] $ export TWILIO_NUMBER=[your-twilio-number]