You can control a website, mobile backend and SendGrid all from within the Windows Azure management portal. We’ll get to all three of these in this tutorial.
To start, create a SendGrid account from the management portal:
- Click NEW at the bottom left
- Click STORE to load up the list of Add-ons
- Find SendGrid in the list and click it
- Then click the arrow at the lower right to go to step 2
- Choose the Free plan for now for 25,000 free emails per month
- Proceed to step 3 and click Purchase
Now, we’ll create a Windows Azure Website:
- Click NEW at the bottom left
- Click Website, then Quick Create
- Set the URL, such as website.azurewebsites.net
- Click Create Web Site on the bottom right
That’s it! You now have a website running on Azure. Now let’s create something cool.
SendGrid can both send and receive email for your domain name. The playlist app uses incoming mail, which means setting up DNS at your domain registrar or host. The process to do this is going to be different depending on who controls your DNS. This tutorial will walk through the Azure and SendGrid part of this process, but you may need to ask for help on changing DNS in your system.
It’s a good idea to choose a subdomain like playlist.example.com, rather than a domain itself. That’s because the Inbound Parse API must collect all mail and you don’t want to interrupt other email for your domain. To use custom domains in Windows Azure, your web site need to run either in Shared mode or the Standard tier; however, Shared mode is currently not available.
Find your IP address and note the further instructions in the management portal:
- Select your website from the list and then click SCALE along the top menu bar.
- Change the Web Site Mode to Shared, and click Save, then Yes
- Click CONFIGURE at the top menu bar, then scroll down to click Manage Domains
- Add your full subdomain plus domain, like playlist.example.com and click the check mark
- Note the IP address and the instructions on this page. You’ll use these at your host or registrar when you modify your DNS settings.
Now you need to update your own DNS settings outside of the Windows Azure interface. This points your domain’s web traffic to Windows Azure and your email to SendGrid. How you change your DNS depends on where your DNS is administered, which could be your host or domain registrar.
You’ll need to make three updates to your DNS:
- Create an A record for playlist.example.com that points to the IP noted above
- Create a CNAME record according to the instructions on the screen where you obtained the IP Address
- Create an MX record pointing to mx.sendgrid.net.
DNS changes can take an hour or more to propagate. Back at Windows Azure’s domain management page, look for the red exclamation point to become a green checkmark.
While we’re waiting for DNS to be ready, we can prepare your SendGrid Incoming Parse API webhook. From the Windows Azure interface:
- Click the SendGrid App Service from your all items list
- In the management section, click the “Go to the SendGrid web site for next steps” link
- Now you’re looking at the SendGrid interface–click Developers at the top
- Click “Parse Incoming Emails” on the right and you’ll see some fields to fill out
Fill in the values you’ve used for your hostname and URL. For example:
- Click “Add host & URL”
Once the DNS has propagated, you’ll be able to receive email to any email address @playlist.example.com. In the next step, we’ll make sure your website on Windows Azure is ready to accept those emails.
Before we can put the code in place, we need to prepare our source control system, which will be Git in our case. Make sure you have Git installed on your local machine before proceeding. There are downloads for Windows, Mac, Linux and Solaris. Now set up your repository within the Windows Azure interface:
- Click the website name from your all items list
- Under quick glance, click “Set up deployment from source control”
- Choose “Local Git repository”
- Copy the Git URL to your clipboard–you will need it later, and it should look similar to https://email@example.com/playlist.git
Now, we need to set some environment variables, so we don’t expose these credentials in our code. First, to find these credentials.
You can find the SendGrid credentials within the Windows Azure management portal:
- Click SendGrid from the all items list.
- In the bar on the bottom, click Connection Info
- A screen will pop up with your password, SMTP server and username
To get your Rdio API Key, which we’ll use to create our playlist, follow the “How to get started” instructions here: http://developer.rdio.com.
With the credentials in hand, it’s time to add them as environment variables within the Windows Azure management portal:
- Click your web site from the all items list, then click Configure
Under “app settings” set the following KEY VALUE pairs
SENDGRID_USER = username
SENDGRID_PASS = password
DOMAIN = playlist.example.com
RDIO_KEY = your_key
RDIO_SECRET = your_secret
XHR_POLLING_ONLY = 1
- Click SAVE at the bottom
With source control and environment variables set, it’s time to download the code that makes this app run. Then we’ll upload that code to our Azure account.
Open up your command line on your local machine and prepare it for code:
- Create a local folder to house the code (e.g. mkdir playlist)
- Clone the code into that directory by executing this command: git clone git://github.com/theycallmeswift/playlist.sendgriddemos.com.git
- cd playlist.sendgriddemos.com
git remote add azure git_url
- This is the long URL you saved from Windows Azure after setting up source control.
git push azure master
- This is the command that pushes this code to Azure cloud
One last thing, we need to update the receiving email address:
- Open up public/index.html
- Change the email in index.html (line 25) to the email address you want to use. Something like firstname.lastname@example.org
git add .
- This adds the modified file for upload
- git commit -m “Updating email address”
git push azure master
- Again, this pushes it to Azure cloud
With your changes pushed to Azure, you can restart the server from the button at the bottom of the web server’s dashboard. Then click the browse button within the same menu to see your website live. At this point people can send in their song requests, assuming DNS has propagated.
Windows Azure can also run a backend-as-a-service for your app, which allows you to store data, authenticate users, send push notifications and do other common mobile tasks. This backend can also be used for non-mobile applications.
Let’s enable Mobile Services from the Windows Azure interface:
- Click New at the bottom left, select Mobile Service, then click Create
- Choose a URL – this is up to you, it will be internal to your app
- Click Next
- Choose a Server Login Name and Password
- Choose Configure Advanced Database Settings
- Click Next, then review and click Complete
Now you need to add a table to the database:
- Click on the name of your mobile service to access its settings
- Click Data then Add a Table
- Choose a table name, update permissions and click Complete
In your index.html file add the following code near the closing body tag to add the Windows Mobile Services library to your app:
In the js/app.js file, after the “$(“#queue”).append …” line, add the following code:
1 2 3
Now, to allow for your app to have access to the DB, your URL to the cross origin resource sharing (cors) setting.
Add your changes via .git and push to Azure.
Now your website, mobile service and SendGrid account are all in harmony on Windows Azure. You could stop here, but to see the real power of Mobile Services, you’ll want to create a native mobile application.
The Windows Azure Mobile Services SDK simplifies the process of standing up a backend for your app in Windows Azure. The Windows Azure team also has SDKs for Android, HTML, Windows Store and Windows Phone, but we’re going to stick to iOS here.
We can download a pre-packaged mobile app from within the Windows Azure interface:
- Click the name of your mobile service from the all items menu
- You should see the quickstart tab. Click iOS then Create a new iOS app.
- Click the download button to grab the source code.
To create a native iPhone app, you’ll need to have XCode installed on a Mac. It’s a big download (over 1 GB), so find something to do while you wait.
Now you’ll want to edit the sample app you downloaded from Windows Azure:
- Expand the files on your computer and open the project file using XCode.
- Update the credentials and table name in QSTodoService.m with those that you used when you created your mobile service.
- Update the function refreshDataOnSuccess in QSTodoService.m to return all from the queue. Remove the existing code there and replace it with:
1 2 3 4 5 6 7 8 9 10
4. Now, go to the file QSToDoListViewController.m, and replace the onAdd function’s contents with:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
Now let’s make some adjustments to the interface:
- Click on the storyboard, then the text input field.
- On the right, change the placeholder text to read: “Enter your song request”
- Next, double click on the button and rename it to “Send”. You will have to adjust the size of the text box and button by single clicking and adjusting.
Your project in XCode should look like the above screenshot. And when you run the iPhone app, you should be able to see requested songs and add your own songs to the shared playlist.
The code for this tutorial is available at our Github page. Enjoy!