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.

secrets¶

See secrets documentation.

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.

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

http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/narr/assets.html#cache-busting-and-asset-overrides

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.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.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().

Default: true

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

See Notebook documentation

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.

Configuration¶

Configuration structure¶

base.ini¶

development.ini¶

test.ini¶

production.ini¶

staging.ini¶

secrets¶

Configuration inclusion¶

Websauna configuration variables¶

websauna.activate_redirect¶

websauna.admin_as_superuser¶

websauna.cachebust¶

websauna.activation_token_expiry_seconds¶

websauna.allow_email_auth¶

websauna.allowed_hosts¶

websauna.allow_inactive_login¶

websauna.cache_max_age_seconds¶

websauna.autologin¶

websauna.celery_config¶

websauna.error_test_trigger¶

websauna.global_config¶

websauna.log_internal_server_error¶

websauna.login_after_activation¶

websauna.login_redirect¶

websauna.logout_redirect¶

websauna.mailer¶

websauna.require_activation¶

websauna.request_password_reset_redirect¶

websauna.reset_password_redirect¶

websauna.sample_html_email¶

websauna.sanity_check¶

websauna.social_logins¶

websauna.secrets_file¶

websauna.secrets_strict¶

websauna.site_id¶

websauna.site_name¶

websauna.site_url¶

websauna.site_tag_line¶

websauna.site_email_prefix¶

websauna.site_time_zone¶

websauna.superusers¶

websauna.template_debugger¶

websauna.test_web_server_port¶

Configuration from other packages¶

Celery¶

Alembic¶

pyramid_redis¶

pyramid_mailer¶

mail.default_sender_name¶

sqlalchemy¶

sqlalchemy.url¶

Python logging¶

pyramid_notebook¶