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¶
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.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.
Default: login
websauna.reset_password_redirect¶
The pyramid route name where the user is taken after performing a password reset via email.
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¶
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.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¶
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)