Configuration Overview¶
While AWS credentials are handled separately, psiTurk reads configuration settings from the following three places, and in the following order, with former entries being preferred over later ones.
- Environment variables, optionally specified in a
.env
file. - A
config.txt
file (i.e., user-specified defaults) - A
.psiturkconfig
file - psiTurk defaults
That is to say, (4) there exist psiTurk-set defaults for many settings, (3) but a user
may specify preferred defaults in a config.txt
file, which they may override
in turn via a ~/.psiturkconfig
file, with (1) environment variables superseding
any previous setting.
Furthermore, psiTurk loads and uses the python-dotenv
library, which means that, on
platforms that respect it, you can store KEY=VALUE pairs in a file called .env
in your project’s root directory, and they will be read in as environment variables
by psiTurk.
Which go where? Consider security and privacy, as well as science replicability¶
While any setting can be set via environment variables, only some make sense to do so. For instance, configuration settings that are credentials-related should not be saved to source code repositories, from whence they may leak. Instead, they can be set via environment variables. Sensitive settings include the following:
- database_url, when it contains embedded credentials
- dashboard login username and password
In other instances, a different setting may be desired for “development” environments than in “production” ones. For example, local development may want to use one database, while a psiturk experiment deployed onto a cloud hosting service for “live” data collection may want to use a different database. Or, different server host, port, and threads settings may be desired. Other settings can enable or disable dashboard and task-runner features, which may only be desirable for certain deployments. Environment variables are ideal for situations like these, rather than committing them to a static configuration file.
However, most other settings are best stored where they can be shared with others,
for science replication purposes. Such settings should go in config.txt
.
Additionally, a user may set any available setting to a global preferred
value in a file called ~/.psiturkconfig
.
Finally, many – but not all – settings have psiturk-set defaults. Look in an
example config.txt file generated by the psiturk-setup-example
, and on
the settings page within these docs, for documentation
on the different settings and their defaults.
Note
In general, changes made to configuration settings require restarting the server process as it may change the behavior. Generally it is best to edit these files while psiturk is not running, and then restart the server.
Local configuration file¶
A sample default local configuration file can be viewed on github
here.
A copy of this file is placed in the example directory as part of running the
psiturk-setup-example
command. In order for changes to config.txt
to be
read by psiturk, this file must be placed in the root of the psiturk study directory.
See Settings for descriptions of the available configuration parameters.
The .psiturkconfig
global config file¶
Any configuration option can actually be placed in either the global or local
configuration file. For example, if you wanted to run different project from
different AWS accounts, you could add an [AWS access]
section to move the
local config.txt files and have different values in different folders. And
vice-versa – any setting could be placed in the .psiturkconfig
file in lieu
of in config.txt.
By default, .psiturkconfig
is searched for in the user’s home directory
( ~/.psiturkconfig
), but the search location can be customized by setting
the PSITURK_GLOBAL_CONFIG_LOCATION
environment variable. This env var
cannot be set via the .env
file – rather, it must be available in the shell
environment).
Important
Keep in mind that settings in the local config.txt file always override settings in the global .psiturkconfig file. In turn, environment variables always override all other config settings.