Onegov Server API


class onegov.server.application.Application[source]

WSGI applications inheriting from this class can be served by onegov.server.

allowed_hosts_expression = None

If the host passed by the request is not localhost, then it is checked against the allowed_hosts expression. If it doesn’t match, the request is denied.

allowed_hosts = None

Additional allowed hosts may be added to this set. Those are not expressions, but straight hostnames.

namespace = None

The namespace of the application, set before the application is configured in configure_application().


Called once when the application is instantiated, with the configuration values defined for this application.

This will be called before set_application_base_path() is called, as this happens before the request.

Be sure to call this method from any subclasses you create. The server adds its own configuration here!


Sets the application id before __call__ is called. That is, before each request.

The application id consists of two values, delimitd by a ‘/’. The first value is the namespace of the application, the second value is the last fragment of the base_path.

That is namespace/app for all requests in the following config:

    'applications': [
            path: '/app',
            namespace: 'namespace'

And namespace/blog for a /sites/blog request in the following config:

    'applications': [
            path: '/sites/*',
            namespace: 'namespace'

Sets the base path of the application before __call__ is called. That is, before each request.

The base_path of static applications is equal to path the application was configured to run under.

The base_path of wildcard applications includes the path matched by the wildcard. For example, if the application is configured to run under /sites/*, the base_path would be /sites/blog if /sites/blog/login was requested.


Called at least once per request with the given hostname.

If True is returned, the request with the given hostname is allowed. If False is returned, the request is denied.

You usually won’t need to override this method, as allowed_hosts_expression and allowed_hosts already gives you a way to influence its behavior.

If you do override, it’s all on you though (except for localhost requests).


Called at least once per request with the given application id.

If True is returned, the request with the given application_id is allowed. If False is returned, the request is denied.

By default, all application ids are allowed.

alias(application_id, alias)[source]

Adds an alias under which this application is available on the server.

The alias only works for wildcard applications - it has no effect on static applications!

This is how it works:

An application running under /sites/main can be made available under /sites/blog by running self.alias(‘main’, ‘blog’).

Aliases must be unique, so this method will fail with a onegov.server.errors.ApplicationConflictError if an alias is already in use by another application running under the same path.

Note that an application opened through an alias will still have the application_id set to the actual root, not the alias. So /sites/blog in the example above would still lead to an application_id of main instead of blog.

This is mainly meant to be used for dynamic DNS setups. Say you have an application available through (pointing to /sites/test). You now want to make this site available through You can do this as follows:


If your server has a catch-all rule that sends unknown domains to /sites/domain_without_dots, then you can add domains dynamically and the customer just points the DNS to your ip address.

handle_exception(exception, environ, start_response)[source]

Default exception handling - this can be used to return a different response when an unhandle exception occurs inside a request or before a request is handled by the application (when any of the above methods are called).

By default we just raise the exception.

Typically, returning an error is what you might want to do:

def handle_exception(exception, environ, start_response):
    if isinstance(exception, UnderMaintenanceError):
        error = webob.exc.HTTPInternalServerError()
        return error(environ, start_response)

Core Functionality

class onegov.server.core.Server(config, configure_morepath=True, post_mortem=False, environ_overrides=None, exception_hook=None)[source]

A WSGI application that hosts multiple WSGI applications in the same process.

Not to be confused with Morepath’s mounting functionality. The morepath applications hosted by this WSGI application are root applications, not mounted applications.

See Morepath’s way of nesting applications

Applications are hosted in two ways:

  1. As static applications under a base path (/app)

  2. As wildcard applications under a base path with wildcard (/sites/*)

There is no further nesting and there is no way to run an application under /.

The idea for this server is to run a number of WSGI applications that are relatively independent, but share a common framework. Though thought to be used with Morepath this module does not try to assume anything but a WSGI application.

Since most of the time we will be running morepath applications, this server automatically configures morepath for the applications that depend on it.

If morepath autoconfig is not desired, set configure_morepath to False.


Configures the python logging.


A dictionary that is understood by python’s logging.config.dictConfig method.


Configures morepath automatically, if any application uses it.

Commandline Interface

The onegov.server can be run through the ‘onegov-server’ command after installation.

Said command runs the onegov server with the given configuration file in the foreground.

Use this for debugging/development only.


onegov-server --config-file test.yml

The onegov-server will load ‘onegov.yml’ by default and it will restart when any file in the current folder or any file somewhere inside ‘./src’ changes.

Changes to omlette directories require a manual restart.

A onegov.yml file looks like this:

  - path: /apps/*
    namespace: apps
      allowed_hosts_expression: '^[a-z]'
      dsn: postgres://username:password@localhost:5432/db
      identity_secure: false
      identity_secret: very-secret-key

      format: '%(asctime)s - %(levelname)s: %(message)s'
      datefmt: '%Y-%m-%d %H:%M:%S'

    class: logging.StreamHandler
    formatter: simpleFormater
    level: DEBUG
    stream: ext://sys.stdout

    level: DEBUG
    handlers: [console]
class onegov.server.cli.WSGIRequestMonitorMiddleware(app)[source]

Measures the time it takes to respond to a request and prints it at the end of the request.

class onegov.server.cli.WsgiProcess(app_factory, host='', port=8080, env={}, enable_tracemalloc=False)[source]

Runs the WSGI reference server in a separate process. This is a debug process, not used in production.


Method to be run in sub-process; can be overridden in sub-class

class onegov.server.cli.WsgiServer(app_factory, host='', port=8080, **kwargs)[source]

Wraps the WSGI process, providing the ability to restart the process and acting as an event-handler for watchdog.


If anything of significance changed, restart the process.


class onegov.server.config.Config(configuration)[source]

Represents the configuration of the server.

classmethod from_yaml_file(yaml_file)[source]

Load the given yaml file and return a new Configuration instance with the configuration values found in the yaml file.

classmethod from_yaml_string(yaml_string)[source]

Load the given yaml string and return a new Configuration instance with the configuration values found in the yaml string.

class onegov.server.config.ApplicationConfig(configuration)[source]

Represents an application config entry loaded from a dictionary like this:

    'path': '/application',
    'application': 'my.module.StaticApp',
    'namespace': 'my-namespace'
    'configuration': {
        'my': 'custom',
        'config': 'values'

It may contain the following keys:


The path of the application is the prefix under which the application is running. For each path onegov.server loads and caches an application.

Applications are basically WSGI containers that are run independently in the same process.

See Application for more.

There are two types of applications, static applications without a wildcard (*) in their path and wildcard applications with a wildcard in their path.

Static applications always have the same application_id (ns/static, if the path is /static and the namespace is ns).

Wildcard applications have the application_id set to the wildcard part of the path: (/wildcard/* can result in an applicaiton_id of ns/blog if /wildcard/blog is opened and the namespace is ns).

See also: set_application_id().

Nested paths are not supported. /static works and /wildcard/* works, but not /static/site or /wildcard/site/*.


The application class or string to an application class that inherits from Application.

If application is a string, the class it points to is loaded immediately.


Each application has a namespace that must be unique. It is used make the application_id unique. Dashes in the namespace are replaced by underscores.


A dictionary that is passed to the application once it is initialized. See application.Application.configure_application().

property root

The path without the wildcard such that /app and /app/* produce the same root (/app).

property is_static

True if the application is static (has no ‘*’ in the path).

List of Applications

class onegov.server.collection.CachedApplication(application_class, namespace, configuration={})[source]

Wraps an application class with a configuration, returning a new instance the first time get() is called and the same instance very time after that.

class onegov.server.collection.ApplicationCollection(applications=None)[source]

Keeps a list of applications and their roots.

The applications are registered lazily and only instantiated/configured once the get() is called.

register(root, application_class, namespace, configuration={})[source]

Registers the given path for the given application_class and configuration.


Returns the applicaton for the given path, creating a new instance if none exists already.


Iterates through the applications that depend on morepath.


exception onegov.server.errors.OnegovServerError(message)[source]

Base class for all errors raised by onegov.server.

exception onegov.server.errors.ApplicationConflictError(message)[source]

Raised if an application conflicts with another application.

exception onegov.server.errors.ApplicationConfigError(message)[source]

Raised when there’s an error in an application configuration.