From 9018ced860acbae8bc9fb3e240de57ad52e24b7e Mon Sep 17 00:00:00 2001 From: zkan Date: Sat, 7 Oct 2017 21:37:47 +0700 Subject: [PATCH 1/3] Add tutorial to deploy simple Django app on Heroku --- USE_CASES.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) diff --git a/USE_CASES.md b/USE_CASES.md index 14619413a..b35473122 100644 --- a/USE_CASES.md +++ b/USE_CASES.md @@ -4,6 +4,7 @@ This documentation provides examples for specific use cases. Please [open an iss * [Transactional Templates](#transactional_templates) * [Attachment](#attachment) +* [Deploy a simple Hello Email Django app on Heroku](#hello_email_django_on_heroku) # Transactional Templates @@ -169,3 +170,183 @@ print(response.status_code) print(response.body) print(response.headers) ``` + + +# Deploy a simple Hello Email Django app on Heroku + +This tutorial explains how we set up a simple Django app to send an email with the SendGrid Python SDK and how we deploy our app to Heroku. + +## Create a Django project + +We first create a project folder. + +``` +$ mkdir hello-sendgrid +$ cd hello-sendgrid +``` + +We assume you have created and activated a [virtual environment](https://virtualenv.pypa.io/) (See [venv](https://docs.python.org/3/tutorial/venv.html) for Python 3+) for isolated Python environments. + +Run the command below to install Django, Gunicorn (a Python WSGI HTTP server), and SendGrid Python SDK. + +``` +$ pip install django gunicorn sendgrid +``` + +It is a good practice for Python dependency management. We will pin the requirements with a file `requirements.txt`. + +``` +$ pip freeze > requirements.text +``` + +Run the command below to initialize a Django project. + +``` +$ django-admin startproject hello_sendgrid +``` + +The folder structure should look like this: + +``` +hello-sendgrid +├── hello_sendgrid +│   ├── hello_sendgrid +│   │   ├── __init__.py +│   │   ├── settings.py +│   │   ├── urls.py +│   │   └── wsgi.py +│   └── manage.py +└── requirements.txt +``` + +Let's create a page to generate and send an email to a user when you hit the page. + +We first create a file `views.py` and put it under the folder `hello_sendgrid/hello_sendgrid`. Add the minimum needed code below. + +```python +import os + +from django.http import HttpResponse + +import sendgrid +from sendgrid.helpers.mail import * + + +def index(request): + sg = sendgrid.SendGridAPIClient( + apikey=os.environ.get('SENDGRID_API_KEY') + ) + from_email = Email('test@example.com') + to_email = Email('test@example.com') + subject = 'Sending with SendGrid is Fun' + content = Content( + 'text/plain', + 'and easy to do anywhere, even with Python' + ) + mail = Mail(from_email, subject, to_email, content) + response = sg.client.mail.send.post(request_body=mail.get()) + + return HttpResponse('Email Sent!') +``` + +Now the folder structure should look like this: + +``` +hello-sendgrid +├── hello_sendgrid +│   ├── hello_sendgrid +│   │   ├── __init__.py +│   │   ├── settings.py +│   │   ├── urls.py +│   │   ├── views.py +│   │   └── wsgi.py +│   └── manage.py +└── requirements.txt +``` + +Next we open the file `urls.py` in order to add the view we have just created to the Django URL dispatcher. + +```python +from django.conf.urls import url +from django.contrib import admin + +from .views import index + + +urlpatterns = [ + url(r'^admin/', admin.site.urls), + url(r'^sendgrid/', index, name='sendgrid'), +] +``` + +We also assume that you have set up your development environment with your `SENDGRID_API_KEY`. If you have not done it yet, please do so. See the section [Setup Environment Variables](https://github.com/sendgrid/sendgrid-python#setup-environment-variables). + +Now we should be able to send an email. Let's run our Django development server to test it. Find the file `manage.py` then run: + +``` +$ python manage.py runserver +``` + +By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". + +## Deploy to Heroku + +Before we start the deployment, let's log in to your Heroku account and create a Heroku app. This tutorial uses `hello-sendgrid`. + +We also need to do a couple things: + +1. Add `'*'` or your Heroku app domain to `ALLOWED_HOSTS` in the file `settings.py`. +2. Add `Procfile` with the code below to declare what commands are run by your application's dynos on the Heroku platform. + +``` +web: cd hello_sendgrid && gunicorn hello_sendgrid.wsgi --log-file - +``` + +The final folder structure looks like this: + +``` +hello-sendgrid +├── hello_sendgrid +│   ├── hello_sendgrid +│   │   ├── __init__.py +│   │   ├── settings.py +│   │   ├── urls.py +│   │   ├── views.py +│   │   └── wsgi.py +│   └── manage.py +├── Procfile +└── requirements.txt +``` + +There are different deployment methods we can choose. In this tutorial, we choose to deploy our app using the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). Therefore, let's install it before we go further. + +Once you have the Heroku CLI installed, run the command below to log in to your Heroku account if you haven't already. + +``` +$ heroku login +``` + +Go to the root folder then initialize a Git repository. + +``` +$ git init +$ heroku git:remote -a hello-sendgrid +``` + +Since we do not use any static files, we will disable `collectstatic` for this project. + +``` +$ heroku config:set DISABLE_COLLECTSTATIC=1 +``` + +Commit the code to the repository and deploy it to Heroku using Git. + +``` +$ git add . +$ git commit -am "Create simple Hello Email Django app using SendGrid" +$ git push heroku master +``` + +We have not finished yet. We need to go to the Heroku settings and add your `SENDGRID_API_KEY` as one of the Heroku environment variables in the Config Variables section. + +After that, let's verify if our app is working or not by accessing the Heroku app domain and going to `/sendgrid/`. You should see the page says "Email Sent!" and on the Activity Feed page in the SendGrid dashboard, you should see a new feed with the email `test@example.com`. From 9b8c86c737ee60c09c60f40c8edb5653cda5ea01 Mon Sep 17 00:00:00 2001 From: zkan Date: Tue, 24 Oct 2017 09:43:01 +0700 Subject: [PATCH 2/3] Revise tutorial according to review --- USE_CASES.md | 78 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/USE_CASES.md b/USE_CASES.md index 20a7b6776..a35103c74 100644 --- a/USE_CASES.md +++ b/USE_CASES.md @@ -4,7 +4,8 @@ This documentation provides examples for specific use cases. Please [open an iss * [Transactional Templates](#transactional_templates) * [Attachment](#attachment) -* [Deploy a Simple Hello Email Django App on Heroku](#hello_email_django_on_heroku) +* [Create a Django app to send email with SendGrid](#create-a-django-app-to-send-email-with-sendgrid) + * [Deploy to Heroku](#deploy-to-heroku) * [Asynchronous Mail Send](#asynchronous-mail-send) @@ -172,8 +173,8 @@ print(response.body) print(response.headers) ``` - -# Deploy a Simple Hello Email Django App on Heroku + +# Create a Django app to send email with SendGrid This tutorial explains how we set up a simple Django app to send an email with the SendGrid Python SDK and how we deploy our app to Heroku. @@ -181,7 +182,7 @@ This tutorial explains how we set up a simple Django app to send an email with t We first create a project folder. -``` +```bash $ mkdir hello-sendgrid $ cd hello-sendgrid ``` @@ -190,19 +191,19 @@ We assume you have created and activated a [virtual environment](https://virtual Run the command below to install Django, Gunicorn (a Python WSGI HTTP server), and SendGrid Python SDK. -``` +```bash $ pip install django gunicorn sendgrid ``` -It is a good practice for Python dependency management. We will pin the requirements with a file `requirements.txt`. +It's a good practice for Python dependency management. We'll pin the requirements with a file `requirements.txt`. -``` -$ pip freeze > requirements.text +```bash +$ pip freeze > requirements.txt ``` Run the command below to initialize a Django project. -``` +```bash $ django-admin startproject hello_sendgrid ``` @@ -250,6 +251,8 @@ def index(request): return HttpResponse('Email Sent!') ``` +**Note:** It would be best to change your to email from `test@example.com` to your own email, so that you can see the email you receive. + Now the folder structure should look like this: ``` @@ -274,6 +277,15 @@ from django.contrib import admin from .views import index +urlpatterns = [ + url(r'^admin/', admin.site.urls), + url(r'^$', index, name='sendgrid'), +] +``` + +These paths allow the root URL to send the email. For a true Django app, you may want to move this code to another URL like so: + +```python urlpatterns = [ url(r'^admin/', admin.site.urls), url(r'^sendgrid/', index, name='sendgrid'), @@ -282,23 +294,45 @@ urlpatterns = [ We also assume that you have set up your development environment with your `SENDGRID_API_KEY`. If you have not done it yet, please do so. See the section [Setup Environment Variables](https://github.com/sendgrid/sendgrid-python#setup-environment-variables). -Now we should be able to send an email. Let's run our Django development server to test it. Find the file `manage.py` then run: +Now we should be able to send an email. Let's run our Django development server to test it. ``` +$ cd hello_sengrid +$ python manage.py migrate $ python manage.py runserver ``` By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". +**Note:** If you use `test@example.com` as your from email, it's likely to go to your spam folder. To have the emails show up in your inbox, try using an email address at the domain you registered your SendGrid account. + + ## Deploy to Heroku -Before we start the deployment, let's log in to your Heroku account and create a Heroku app. This tutorial uses `hello-sendgrid`. +There are different deployment methods we can choose. In this tutorial, we choose to deploy our app using the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). Therefore, let's install it before we go further. + +Once you have the Heroku CLI installed, run the command below to log in to your Heroku account if you haven't already. + +``` +$ heroku login +``` + +Before we start the deployment, let's create a Heroku app by running the command below. This tutorial names the Heroku app `hello-sendgrid`. + +```bash +$ heroku create hello-sendgrid +``` + +**Note:** If you see Heroku reply with "Name is already taken", please add a random string to the end of the name. We also need to do a couple things: -1. Add `'*'` or your Heroku app domain to `ALLOWED_HOSTS` in the file `settings.py`. -2. Add `Procfile` with the code below to declare what commands are run by your application's dynos on the Heroku platform. +1. Add `'*'` or your Heroku app domain to `ALLOWED_HOSTS` in the file `settings.py`. It will look like this: +```python +ALLOWED_HOSTS = ['*'] +``` +2. Add `Procfile` with the code below to declare what commands are run by your application's dynos on the Heroku platform. ``` web: cd hello_sendgrid && gunicorn hello_sendgrid.wsgi --log-file - ``` @@ -319,19 +353,19 @@ hello-sendgrid └── requirements.txt ``` -There are different deployment methods we can choose. In this tutorial, we choose to deploy our app using the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). Therefore, let's install it before we go further. - -Once you have the Heroku CLI installed, run the command below to log in to your Heroku account if you haven't already. +Go to the root folder then initialize a Git repository. ``` -$ heroku login +$ git init +$ heroku git:remote -a hello-sendgrid ``` -Go to the root folder then initialize a Git repository. +**Note:** Change `hello-sendgrid` to your new Heroku app name you created earlier. + +Add your `SENDGRID_API_KEY` as one of the Heroku environment variables. ``` -$ git init -$ heroku git:remote -a hello-sendgrid +$ heroku config:set SENDGRID_API_KEY= ``` Since we do not use any static files, we will disable `collectstatic` for this project. @@ -348,9 +382,7 @@ $ git commit -am "Create simple Hello Email Django app using SendGrid" $ git push heroku master ``` -We have not finished yet. We need to go to the Heroku settings and add your `SENDGRID_API_KEY` as one of the Heroku environment variables in the Config Variables section. - -After that, let's verify if our app is working or not by accessing the Heroku app domain and going to `/sendgrid/`. You should see the page says "Email Sent!" and on the Activity Feed page in the SendGrid dashboard, you should see a new feed with the email `test@example.com`. +After that, let's verify if our app is working or not by accessing the root domain of your Heroku app. You should see the page says "Email Sent!" and on the Activity Feed page in the SendGrid dashboard, you should see a new feed with the email you set in the code. # Asynchronous Mail Send From 50ea2f4c75bd86e373b2e77b7464022bb598389c Mon Sep 17 00:00:00 2001 From: zkan Date: Fri, 1 Dec 2017 09:18:42 +0700 Subject: [PATCH 3/3] Use only URL /sendgrid/ to send email - Remove the root URL setup part that may confuse readers - Revise the text --- USE_CASES.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/USE_CASES.md b/USE_CASES.md index cb7da43cc..d81857fb0 100644 --- a/USE_CASES.md +++ b/USE_CASES.md @@ -280,21 +280,14 @@ from django.contrib import admin from .views import index -urlpatterns = [ - url(r'^admin/', admin.site.urls), - url(r'^$', index, name='sendgrid'), -] -``` - -These paths allow the root URL to send the email. For a true Django app, you may want to move this code to another URL like so: - -```python urlpatterns = [ url(r'^admin/', admin.site.urls), url(r'^sendgrid/', index, name='sendgrid'), ] ``` +These paths allow the URL `/sendgrid/` to send the email. + We also assume that you have set up your development environment with your `SENDGRID_API_KEY`. If you have not done it yet, please do so. See the section [Setup Environment Variables](https://github.com/sendgrid/sendgrid-python#setup-environment-variables). Now we should be able to send an email. Let's run our Django development server to test it.