View on GitHub


Test Coverage
# Configuration

## Environment variables

Freeturn uses [django-environ](https://github.com/joke2k/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
# sentry project id
# email url, see django-environ docs for more info
# oauth2 social auth config for google login
# aws access keys
# static and media storage aws s3 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
# redis url using django-environ notation
# google analytics id
# django debug mode, dont' set in prod
# django debug toolbar, see https://django-debug-toolbar.readthedocs.io/en/latest/
# secret key for your project, see https://djecrety.ir/
# use redis to cache templates
# set in prod while using https as transport and heroku
# whitenoise storage compresses the media assets, recommended in prod
# 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

### Django environ built-in env

Additionally django environ offers (see [docs](https://github.com/joke2k/django-environ#supported-types))
- `DATABASE_URL` for configuring the database, defaults to `./db.sqlite3`
- `REDIS_URL` for configuring redis / cache urls (caches default to [locmemcache](https://docs.djangoproject.com/en/3.0/topics/cache/#local-memory-caching))
- `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](https://github.com/joke2k/django-environ#supported-types) 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](https://help.heroku.com/K1PPS2WM/why-are-my-file-uploads-missing-deleted). 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 credentials are the main key pair for you to access your AWS services. Freeturn utilizes [django-storages](https://django-storages.readthedocs.io/en/latest/)
for accessing the s3 storage and configuring it. Find more information on s3 in particular [here](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html).

### S3 bucket

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

Freeturn depends on [wagtail-storages](https://github.com/torchbox/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](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html) to know
how you can find out your account id and username.

## Recaptcha


Wagtail exposes the the forms to the wild internet, which means without any DoS protection. Freeturn uses [django-recaptcha2](https://github.com/kbytesys/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](https://developers.google.com/recaptcha/intro)
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](https://github.com/joke2k/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](https://docs.djangoproject.com/en/3.0/topics/email/#email-backends)
to find out the difference.

## Google oauth2

In order to activate the [gmail integration](crm.md#messages), freeturn uses wonderful [python-social-auth](https://python-social-auth.readthedocs.io/en/latest/)
and it's [google oauth2 integration](https://python-social-auth.readthedocs.io/en/latest/backends/google.html#google-oauth2).
Consulte [the official docs](https://developers.google.com/identity/protocols/oauth2) to find the access keys.

!!! warning
    python-social-auth backend will be only used if the keys are not empty

## 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](crm.md#messages).

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](https://devcenter.heroku.com/articles/scheduler).

!!! warning
    Heroku scheduler adds up to your usage metrics

## Sentry

[Sentry](https://sentry.io/organizations/sergey-cheparev/issues/) 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.


[Sentry environments](https://docs.sentry.io/enriching-error-data/environments/?platform=python) will be configured
automatically for review apps if ENVIRONMENT is not set, using HEROKU_APP_NAME env.

## Frontend caching


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](#django-environ-built-in-env).


In order to speed up the static serving, freeturn uses [django-whitenoise](http://whitenoise.evans.io/en/stable/) for
compressing, preprocessing and minifying the static files. Set this variable to true to enable this feature.

## Google analytics


Google analytics is a monstrous analytics tool to analyze your site performance and user behavior. Consult [this docs](https://support.google.com/analytics/thread/13109681?hl=en)
to find out where you get this tracking id.

## Debug toolbar

Enables [django debug toolbar](https://django-debug-toolbar.readthedocs.io/en/latest/). 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](https://github.com/wkhtmltopdf/wkhtmltopdf) is a tool for rendering html pages to pdf documents. Freeturn uses
it for creating pdf documents such as [cvs](crm.md#cvs) and [invoices](crm.md#generating-invoices).
In order to make it work wkhtml within your container must be installed and understood by [django-wkhtmltopdf](https://pypi.org/project/django-wkhtmltopdf/).
Heroku luckily several buildpacks for it,  [wkhtmltopdf-buildpack](https://github.com/dscout/wkhtmltopdf-buildpack) is recommended.

!!! warning
    wkhtmltopdf-buildpack has it's binary paths slightly different than standard ubuntu packages. Make sure you set
    the following env: `WKHTMLTOPDF_CMD=/app/bin/wkhtmltopdf` and `WKHTMLTOPDF_VERSION=0.12.4`

## Gettext and heroku

Django requires gettext to be installed for using the built in [i18n mechanics](https://docs.djangoproject.com/en/3.0/topics/i18n/).
proved working with no troubles.