Merge pull request #1996 from pydanny/docs/heroku

Docs/heroku

docs/deployment-on-heroku.rst

@@ -17,11 +17,8 @@ Run these commands to deploy the project to Heroku:
 
     heroku addons:create heroku-redis:hobby-dev
 
-    # If using mailgun:
     heroku addons:create mailgun:starter
 
-    heroku addons:create sentry:f1
-
     heroku config:set PYTHONHASHSEED=random
     
     heroku config:set WEB_CONCURRENCY=4
@@ -52,3 +49,70 @@ Run these commands to deploy the project to Heroku:
     heroku run python manage.py check --deploy
 
     heroku open
+
+
+.. warning::
+
+    .. include:: mailgun.rst
+
+
+Optional actions
+----------------
+
+Celery
+++++++
+
+Celery requires a few extra environment variables to be ready operational. Also, the worker is created,
+it's in the ``Procfile``, but is turned off by default:
+
+.. code-block:: bash
+
+    # Set the broker URL to Redis
+    heroku config:set CELERY_BROKER_URL=`heroku config:get REDIS_URL`
+    # Scale dyno to 1 instance
+    heroku ps:scale worker=1
+
+Sentry
+++++++
+
+If you're opted for Sentry error tracking, you can either install it through the `Sentry add-on`_:
+
+.. code-block:: bash
+
+    heroku addons:create sentry:f1
+
+
+Or add the DSN for your account, if you already have one:
+
+.. code-block:: bash
+
+    heroku config:set SENTRY_DSN=https://xxxx@sentry.io/12345
+
+.. _Sentry add-on: https://elements.heroku.com/addons/sentry
+
+
+Gulp & Bootstrap compilation
+++++++++++++++++++++++++++++
+
+If you've opted for a custom bootstrap build, you'll most likely need to setup
+your app to use `multiple buildpacks`_: one for Python & one for Node.js:
+
+.. code-block:: bash
+
+    heroku buildpacks:add --index 1 heroku/nodejs
+
+At time of writing, this should do the trick: during deployment,
+the Heroku should run ``npm install`` and then ``npm build``,
+which runs Gulp in cookiecutter-django.
+
+If things don't work, please refer to the Heroku docs.
+
+.. _multiple buildpacks: https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app
+
+About Heroku & Docker
+---------------------
+
+Although Heroku has some sort of `Docker support`_, it's not supported by cookiecutter-django.
+We invite you to follow Heroku documentation about it.
+
+.. _Docker support:: https://devcenter.heroku.com/articles/build-docker-images-heroku-yml

docs/deployment-with-docker.rst

@@ -43,6 +43,11 @@ You will probably also need to setup the Mail backend, for example by adding a `
 .. _Mailgun: https://mailgun.com
 
 
+.. warning::
+
+    .. include:: mailgun.rst
+
+
 Optional: Use AWS IAM Role for EC2 instance
 -------------------------------------------
 

docs/mailgun.rst

@@ -0,0 +1,13 @@
+If your email server used to send email isn't configured properly (Mailgun by default),
+attempting to send an email will cause an Internal Server Error.
+
+By default, django-allauth is setup to `have emails verifications mandatory`_,
+which means it'll send a verification email when an unverified user tries to
+log-in or when someone tries to sign-up.
+
+This may happen just after you've setup your Mailgun account, which is running in a
+sandbox subdomain by default. Either add your email to the list of authorized recipients
+or verify your domain.
+
+
+.. _have emails verifications mandatory: https://django-allauth.readthedocs.io/en/latest/configuration.html?highlight=ACCOUNT_EMAIL_VERIFICATION

docs/troubleshooting.rst

@@ -11,5 +11,7 @@ This page contains some advice about errors and problems commonly encountered du
 
 #. New apps not getting created in project root: This is the expected behavior, because cookiecutter-django does not change the way that django startapp works, you'll have to fix this manually (see `#1725`_)
 
+#. .. include:: mailgun.rst
+
 .. _#528: https://github.com/pydanny/cookiecutter-django/issues/528#issuecomment-212650373
 .. _#1725: https://github.com/pydanny/cookiecutter-django/issues/1725#issuecomment-407493176