Configuration

Environment variables

Freeturn uses django-environ to configure the application over environment variables and dotenv files. All the environment variables can be found in .env_template, here they are:

# recaptcha config for the forms
RECAPTCHA_PUBLIC_KEY=
RECAPTCHA_PRIVATE_KEY=
# sentry project id
SENTRY_DSN=
# email url, see django-environ docs for more info
EMAIL_URL=
# oauth2 social auth config for google login
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=
# aws access keys
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
# static and media storage aws s3 bucket name
AWS_STORAGE_BUCKET_NAME=
# aws storage account id and user for s3 policy config, see https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html
AWS_STORAGE_ACCOUNT_ID=
AWS_STORAGE_USER=
# redis url using django-environ notation
REDIS_URL='rediscache://127.0.0.1:6379/1?client_class=django_redis.client.DefaultClient'
# google analytics id
GOOGLE_ANALYTICS_ID=UA-123456-7
# django debug mode, dont' set in prod
DEBUG=True
# django debug toolbar, see https://django-debug-toolbar.readthedocs.io/en/latest/
DEBUG_TOOLBAR=
# secret key for your project, see https://djecrety.ir/
SECRET_KEY=1234567
# use redis to cache templates
CACHE_TEMPLATES=
# set in prod while using https as transport and heroku
SECURE_PROXY_SSL=
# whitenoise storage compresses the media assets, recommended in prod
WHITENOISE_STORAGE=
# path to set wkhtml binary, usually /usr/bin/wkhtmltopdf, for heroku buildback /app/bin/wkhtmltopdf
# use which wkhtmltopdf in the container to make sure it's there
WKHTMLTOPDF_CMD=

Django environ built-in env

Additionally django environ offers (see docs) - DATABASE_URL for configuring the database, defaults to ./db.sqlite3 - REDIS_URL for configuring redis / cache urls (caches default to locmemcache) - EMAIL_URL for configuring email (defaults to consolemail)

Most of the activation different services and features in freeturn, default values are not suitable for production. Let's dig into it.

Database

DATABASE_URL = 'sqlite:///<PROJECT_DIR>/db.sqlite3'

The default config uses locally stored sqlite database, which is particularly comfortable for local development, because of it's speed and quick setup. Besides that docker container and heroku dynos don't have persistent storages out of box, which makes them easily disposable and reproducable.

Long story short, this is not convenient for production use. Heroku dynos offer free postgres add-ons, which inject the database URL over the env variable DATABASE_URL, which makes it plug and play ready. Of course you are free to use any DBMS of your choice, consult django-environ docs for correct building of database URLs.

Storage

For same reason as the filesystem based databases are not suitable for production, the local filesystem storage won't work for heroku. This makes storing the uploads aka media files over heroku quite a peculiar task. Heroku recommends using AWS S3 for that, here is how it can be done.

AWS credentials

AWS_ACCESS_KEY_ID = ''
AWS_SECRET_ACCESS_KEY = ''

AWS credentials are the main key pair for you to access your AWS services. Freeturn utilizes django-storages for accessing the s3 storage and configuring it. Find more information on s3 in particular here.

S3 bucket

AWS_STORAGE_BUCKET_NAME = ''

s3 bucket is an analog of a hard drive in terms of AWS cloud storage. s3 as such mimics the popular filesystems, with multiple differences though. Freeturn needs to know which bucket in your AWS account to use.

S3 bucket policy

AWS_STORAGE_ACCOUNT_ID = ''
AWS_STORAGE_USER = ''

Freeturn depends on wagtail-storages for managing the sensitive uploads securely, which requires some addional configuration steps. You can either copypast the wagtail-storages's or manually create the s3 bucket policy for your storage, that doesn't require AWS_STORAGE_ACCOUNT_ID nor AWS_STORAGE_USER to be configured. What you need those settings for, is that if you want to install the policy from template, which you can find in s3_policy.json.template. This is pretty much the recommended policy from wagtail-storages, where the user name and account id are injected as context. See the corresponding AWS docs to know how you can find out your account id and username.

Recaptcha

RECAPTCHA_PUBLIC_KEY = ''
RECAPTCHA_PRIVATE_KEY = ''

Wagtail exposes the the forms to the wild internet, which means without any DoS protection. Freeturn uses django-recaptcha2 for enabling the google's recaptcha and make the submission process easy and comfortable for the visitors. In order to enable the recaptcha support, you would need the recaptcha public and private keys. See the recaptcha docs to know where you get the keys.

Email

EMAIL_URL = 'consolemail://'

Freeturn would notify about different event over the email, in order to configure it, email url must be set. Consult django-environ docs to learn how those URLs are built and also make sure you to take at least a brief look at django email backends docs to find out the difference.

Google oauth2

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ''

In order to activate the gmail integration, freeturn uses wonderful python-social-auth and it's google oauth2 integration. Consulte the official docs to find the access keys.

Setting up mail checker

Once freeturn's google email integration is configured, you'd need to set up the checker 'cron'. This utility checks if there are any emails in your inbox tagged CRM, parses their content and created the project entry for them. Find more info here.

The checker itself is called over the CLI invoke command inv mail. Put it in the crontab or if you use heroku, you could use heroku scheduler.

Sentry

SENTRY_DSN = ''

Sentry is an outstanding bug monitoring tool, which allows you to see the exhaustive information about the incidents happening in your application. Sentry has both open source and free on premise version and cloud version, which is free for developers and small businesses. While you don't necessary need those for the production use, you could find it useful to find out the additional info for bugfixing. Follow the sign up wizard and you will be offered to add a project, which then will reveal your DSN - resource identification you'd put in the freeturn configuration.

ENVIRONMENT = ''

Sentry environments will be configured automatically for review apps if ENVIRONMENT is not set, using HEROKU_APP_NAME env.

Frontend caching

CACHE_TEMPLATES = False

While caching is more necessary for highly loaded sites, enabling caching in the admin can significantly speed up the admin interface on basic computing power. Set this variable to True to enable redis cache.

WHITENOISE_STORAGE = False

In order to speed up the static serving, freeturn uses django-whitenoise for compressing, preprocessing and minifying the static files. Set this variable to true to enable this feature.

Google analytics

GOOGLE_ANALYTICS_ID = 'UA-123456-7'

Google analytics is a monstrous analytics tool to analyze your site performance and user behavior. Consult this docs to find out where you get this tracking id.

Debug toolbar

DEBUG_TOOLBAR = False

Enables django debug toolbar. Django debug toolbar is a an extremely useful tool for finding the templates used, SQL queries made and much more, which you would probably need for development.

WKHTML to PDF

WKHTML is a tool for rendering html pages to pdf documents. Freeturn uses it for creating pdf documents such as cvs and invoices. In order to make it work wkhtml within your container must be installed and understood by django-wkhtmltopdf. Heroku luckily several buildpacks for it, wkhtmltopdf-buildpack is recommended.

Gettext and heroku

Django requires gettext to be installed for using the built in i18n mechanics. heroku-buildpack-gettext proved working with no troubles.