scotch is a toolkit to deploy many WSGI-applications onto a single server. It will allow you to specify how an app should be deployed and generate nginx, uwsgi-configuration files and virtualenvs.
First, install scotch (preferably on a Debian or Ubuntu system). Then create a file named /etc/scotch/apps-enabled/dram.cfg
as follows:
[app]
src=git@github.com:mbr/scotch-sample-app
Now simply run (as root):
$ scotch deploy dram
after which the sample app should greet you at http://localhost. See the source of the sample application for some ideas on how an app can be configured.
First, scotch is set up on the system by providing a suitable global configuration, called the site configuration. The shipped default is suitable for Debian stable and Ubuntu LTS deployments, other distros may need different settings.
In theory multiple application and webservers are supported through the plugin architecture, however currently scotch ships only with nginx and uWSGI support, so make sure these are installed.
Each app has its own configuration configuration file, found at /etc/scotch/apps-enabled. Deploying an app is done by triggering the two-step deployment process by running:
$ scotch deploy myapp
The first step is called checkout. A new instance of the app will be created (per default in /var/local/scotch/appname
). An instance is a directory that contains (almost) all of the deployment.
The application's source code is copied into the source dir at instance_dir/src
. The default source is a git repository, however the resulting copy will just be a plain directory.
Afterwards a new virtualenv is created and dependencies of the app are installed.
Now that that it is runnable, the app will register as the second step; i.e. the configuration files for web and application servers will be generated and the affected servers will be reloaded or restartet. Afterwards, the app is live.
When using nginx and uwsgi, you can check the sites-enabled
and scotch-apps
subdirectories of /etc/nginx/
for nginx configuration, as well as /etc/uwsgi/apps-enabled
for the uwsgi ini files created.
Configuration files for scotch are loaded in the following order for each app instance. Files loaded later can overwrite values from files loaded earlier:
- Built-in defaults (for scotch and plugins).
- Site configuration:
./scotch.cfg
,~/.scotch.cfg
and/etc/scotch.cfg
. These locations can be overridden by the-c
command line option, which is helpful for non-root testing. - App configuration, in
/etc/scotch/apps.enabled/myapp.cfg
(for an app named "myapp"). This path is configurable as${paths:configuration}
(see below).
Configuration files use the configparser
module found in the Python 3 stdlib or its backport on Python 2. The extended interpolation <https://docs.python.org/3.3/library/configparser.html #configparser.ExtendedInterpolation> is also used.
The site configuration is meant to be used to smooth away differences between different distributions and web or application servers.
For educational purposes, here is an example for a more exotic /etc/scotch.cfg
:
[app]
interpreter=/usr/local/custom-python/bin/python
venv_path=/virtualenvs/${name}
[paths]
configuration=/nfs/conf/scotch
instances=/nfs/scotch-instances
This will enables a custom compiled interpreter and configuration and instances store on an (assumed) nfs volume, while virtual environments are kept on the local machine. Note that configuration files are just merged together, there's no technical distinction between a defaults-file, site configuration or app configuration.
Each app configuration can override any option of the configuration, however most often those in the [app] section are overriden. See the defaults file (https://github.com/mbr/scotch/blob/master/scotch/defaults.cfg) for commented options.