Configuration

Websauna uses INI-based configuration files, from Paste and Pyramid legacy. To avoid copy-pasted configuration settings

Configuration structure

Websauna INI configuration files are extensible. You can include base INI configuration files in your settings file from file system and other Python packages.

The default app scaffold drops five files specific to your app

  • base.ini
  • development.ini
  • test.ini
  • staging.ini
  • production.ini

All these files extend Websauna base configuration files using the configuration inclusion mechhanism explained below.

All files can have corresponding secrets INI file which does not go to the version control and must be hand placed around.

base.ini

This is the base for all configuration files. It should not be used standalone, but it is base for all settings.

  • Set up loggers
  • Set up core settings like Jinja 2 templating
  • Set up default websauna configuration variables

See base.ini.

development.ini

This is the configuration file for running the local development server

  • No outgoing email
  • Celery jobs are executed eagerly, no need to run Celery process
  • No backups
  • Development databases
  • Enable all Pyramid debug options.
  • Enable pyramid_debugtoolbar.

See development.ini.

test.ini

Settings for running unit tests

  • No outgoing email
  • Test database
  • Jinja templates in strict mode (raise exception on missing template variable)

See development.ini.

production.ini

Settings for running Websauna on production server.

  • Mail out
  • Production database
  • No debugging
  • Cached static files

See production.ini.

staging.ini

Same as production.ini, but with staging secrets, so that you can use different API credentials for a staging server and production server.

Configuration inclusion

For examples see any INI file produced by scaffold.

Note

Configuration inclusion system will be phased out in the future versions to be replaced with more generic configuration solution.

Example continuos-integration.ini which extends other INI files and overrides some settings:

[includes]
include_ini_files =
    resource://websauna/conf/test.ini
    resource://websauna/conf/base.ini

[app:main]
use = egg:websauna
websauna.init = websauna.Initializer
sqlalchemy.url = postgres://ci:ci:@localhost:5434/test

Websauna configuration variables

The following variables are available.

websauna.activate_redirect

The Pyramid route name where the user is taken after clicking the email activation link.

See websauna.system.user.registrationservice.DefaultRegistrationService.activate_by_email().

Default: registration_complete.

websauna.admin_as_superuser

All members in admin group are also superusers.

Note

It is only safe to enable this settings on your local computer. Never enable this in an environment which can be accessed over Internet.

Default: true in development.ini, false otherwise.

See also websauna.superusers.

websauna.cachebust

Use Pyramid cache busting mechanism when serving static assets.

This option controls whether or not static assets are served in production deployment or CDN mode.

Enable this in production deployments to have never expiring URLs for all items referred by request.static_url() or {{ 'xxx'|static_url }} in templates.

URLs are tagged by file MD5 hash. If the source asset file (CSS, JS image) changes a new URL is generated, invalidating the cache.

Default:: false.

More info

websauna.activation_token_expiry_seconds

How quickly email activation and password reset token turns sour.

Default: 24 hours

websauna.allow_email_auth

Allow users to sign in by email (besides username).

Default: true.

websauna.allowed_hosts

Whitespace separated list of hostnames this site is allowed to respond.

This is a security feature preventing direct IP access of sites.

Set this to list of your production domain names:

websauna.allowed_hosts =
    libertymusicstore.net
    upload.libertymusicstore.net

Default: localhost.

websauna.allow_inactive_login

Allow users who have not verified their email to sign in.

Default: false.

websauna.cache_max_age_seconds

How long static assets are cached. Any non-zero value enables caching busting.

Default: 0 (development), 2 weeks (production)

websauna.autologin

Automatically sign in the user after completing the sign up form.

See websauna.systme.user.registrationservice.DefaultRegistrationService.sign_up().

Default: false.

websauna.celery_config

A Python dictionary to configure Celery.

See Celery manual for configuration.

See ws-celery.

See websauna.system.Initializer.configure_tasks().

See Tasks documentation.

Example:

[app:main]
# ...
websauna.celery_config =
    {
        "broker_url": "redis://localhost:6379/3",
        "accept_content": ['json'],
        "task_always_eager": False,
        "beat_schedule": {
            # config.scan() scans a Python module
            # and picks up a celery task named test_task
            "test_task": {
                "task": "foobar",
                "schedule": timedelta(seconds=1)
            }
        }
    }

websauna.error_test_trigger

If set enable a view at path /error-trigger that generates a runtime error.

You can use this view to generate an error and see that your logging and error monitoring system functions correctly.

Default: false.

websauna.global_config

This is a reference to global_config object which is used to initialize Pyramid application. It is a dictionary. Example:

{'__file__': '/Users/mikko/code/trees/trees/development.ini', 'here': '/Users/mikko/code/trees/trees'}

websauna.log_internal_server_error

When the user is being served 500 internal server error (websauna.system.core.views.internalservererror.internal_server_error()) send the error traceback to standard Python logger.

Disabling this is most useful for testing where you do not want to see tracebacks polluting your log output.

Default: true

websauna.login_after_activation

Are users automatically logged in after clicking the email verification link.

See websauna.system.user.registrationservice.DefaultRegistrationService.activate_by_email().

Default: false.

websauna.login_redirect

The Pyramid route name where the user is redirected after successful login.

See websauna.system.user.loginservice.DefaultLoginService.authenticate_user().

Default: home.

websauna.logout_redirect

The Pyramid route name where the user is redirected after successful login.

See websauna.system.user.loginservice.DefaultLoginService.logout().

Default: login.

websauna.mailer

Choose the mail backend class.

Available options

  • websauna.system.mail.mailer.StdoutMailer - dump email to stdout. Default in development.
  • mail - use the SMTP configured for pyramid_mailer. Default in production.
  • pyramid_mailer.mailer.DummyMailer - No any kind of mail out. Default in testing.

See also websauna.system.Initializer.configure_mail().

See also below pyramid_mailer for configuring the actual mail server details.

websauna.require_activation

Do user need to verify their email before they can sign in.

See websauna.system.user.registrationservice.DefaultRegistrationService.sign_up().

Default: true.

websauna.request_password_reset_redirect

The pyramid route name where the user is taken after submitting a password reset request.

See websauna.system.user.credentialactivityservice.DefaultCredentialActivityService.create_forgot_password_request().

Default: login

websauna.reset_password_redirect

The pyramid route name where the user is taken after performing a password reset via email.

See websauna.system.user.credentialactivityservice.DefaultCredentialActivityService.create_forgot_password_request().

Default: login

websauna.sample_html_email

Enable /sample-html-email view for testing HTML email looks.

Default: true in development.ini, false otherwise

websauna.sanity_check

Perform database sanity check after the startup. This will check all models have corresponding tables and columns in the database and there are no unsynced models.

Disabled for testing and various command line commands on a call to websauna.system.devop.cmdline.init_websauna().

See also websauna.system.Initializer.sanity_check().

Default: true

websauna.social_logins

List of configured social logins, or federated authentication, methods.

  • List can be space or new line separated
  • Each social login corresponds one entry in secrets INI file

Example value:

websauna.social_logins =
    facebook
    twitter

In which case your secrets INI would contain:

[facebook]
class = authomatic.providers.oauth2.Facebook
consumer_key = xxx
consumer_secret = yyy
scope = user_about_me, email
mapper = websauna.system.user.social.FacebookMapper

[twitter]
class = authomatic.providers.oauth1.Twitter
consumer_key = xxx
consumer_secret = yyy

websauna.secrets_file

Secrets file for API keys and tokens. Read secrets documentation for more information.

The value is in URL format resource://PYTHON_PACKAGE_NAME/PATH_TO_INI_FILE_INSIDE_PACKAGE.

Default value: resource://websauna/development-secrets.ini.

websauna.secrets_strict

If environment variables are missing in the secrets INI file interpolation, raise an exception.

See websauna.utils.secrets.read_ini_secrets().

Default value: true

websauna.site_id

An alphanumeric id for the site. If multiple sites are running on the same resources this can be used to discriminate between sites.

For example backup scripts tags backup archives with this identifier.

Default value: project name + “_prod”

websauna.site_name

See websauna.system.core.vars.site_name().

websauna.site_url

See websauna.system.core.vars.site_url().

Default: No default, must be set.

websauna.site_tag_line

See websauna.system.core.vars.site_tag_line().

Default: No default, must be set.

websauna.site_email_prefix

See websauna.system.core.vars.site_email_prefix().

Default: No default, must be set.

websauna.site_time_zone

See websauna.system.core.vars.site_time_zone().

Default: UTC.

websauna.superusers

List of superuser emails or usernames. Add your username on this list to make it super user.

Example:

websauna.superusers =
    admin
    [email protected]

Warning

Superuser permission allows executing arbitrary code on the server.

More information

websauna.template_debugger

Which debugger to invoke when hitting {{ debug() }} inside a page template.

See debug template variable.

Default: pdb.set_trace in development.ini, otherwise turned off.

websauna.test_web_server_port

A port where to run the test server for functional tests.

This is used by web_server py.test test fixture.

Default: 8521.

Configuration from other packages

Celery

Websauna uses pyramid_celery which allows you to put Celery configuration variables to a INI file.

For example see Websauna base.ini. For more information see Celery configuration.

Alembic

See Alembic.

pyramid_redis

See pyramid_redis.

pyramid_mailer

pyramid_mailer is underlying component used by email out. Also see websauna.mailer setting.

See pyramid_mailer configuration.

mail.default_sender_name

Set up envelope name for the sender.

Example:

mail.default_sender = [email protected]
mail.default_sender_name = Example Technologies

sqlalchemy

sqlalchemy.url

The connection string for the primary SQL database.

Follows SQLAlchemy engine configuration syntax.

Default: postgresql://localhost/yourappname_dev (for development.ini)

Python logging

See Python guide.

pyramid_notebook

See pyramid_notebook.