Configuring PYBOSSA

The PYBOSSA settings_local.py.tmpl file has all the available configuration options for your server. This section, explains each of them and how you should/could use them in your server.

Debug mode

The DEBUG mode is disabled by default in the configuration file, as this should be only used when you are running the server for development purposes. You should not enable this option, unless you need to do some debugging in the PYBOSSA server

Note

For further details about the DEBUG mode in the PYBOSSA server, please, check the official documentation.

Debug Toolbar

PYBOSSA includes a flag to enable a debug toolbar that can give your more insights about the performance of PYBOSSA. We strongly recommend to keep the toolbar disabled in production environments, as it will slow down considerably all the execution of the code. However, if you are testing the server, feel free to enable it adding the following variable to the settings file:

ENABLE_DEBUG_TOOLBAR = True

Host and Port

The HOST and PORT config variables can be used to force the server to listen in specific addresses of your server, as well as at a given port. Usually, you will only need to uncomment the HOST variable in order to listen in all the net interfaces.

Securing the server

PYBOSSA uses the Flask Sessions feature that signs the cookies cryptographically for storing information. This improves the security of the server, as the user could look at the contents of the cookie but not modify it, unless they know the SECRET and SECRET_KEY.

Therefore, it is very important that you create a new SECRET and SECRET_KEY keys for your server and keep them private. Please, check the Flask Sessions documentation for instructions about how to create good secret keys.

Database username and password

PYBOSSA uses the SQLAlchemy SQL toolkit to access the DB. In the settings file, you only need to modify the name of the user, password and database name so it fits your needs in the field `SQLALCHEMY_DATABASE_URI`_:

'postgresql://username:userpassword@localhost/databasename'

Load balance SQL Queries

If you have a master/slave PostgreSQL setup, you can instruct PYBOSSA to use the slave node for load balancing queries between the master and slave node.

For enabling this mode, all you have to do is adding to the settings_local.py config file the following:

SQLALCHEMY_BINDS = {
    'slave': 'postgresql://user:password@server/pybossadb'
}

It’s dangerous, so better sign this

PYBOSSA uses the It’s dangerous Python library that allows you to send some data to untrusted environments, but signing it. Basically, it uses a key that the server only knows and uses it for signing the data.

This library is used to send the recovery password e-mails to your PYBOSSA users, sending a link with a signed key that will be verified in the server. Thus, it is very important you create a secure and private key for the it’s dangerous module in your configuration file, just modify the ITSDANGEROUSKEY.

CORS configuration

By default PYBOSSA has the api endpoints configured with Access-Control-Allow-Origin: *. However, you can change it to whatever you want via the config file. Take a look into the official documentation for Flask-CORS for all the available options.

Modifying the Brand name

You can configure your project with a different name, instead of the default one: PYBOSSA. You only need to change the string BRAND to the name of your organization or project.

Multiple languages

By default PYBOSSA only speaks English, however the default theme comes with a few translations (Spanish, French, Italian, Japanese, Greek and German).

You can enable those translations (mostly user interface strings and actions) by doing the following: creating a symlink to the translations folders:

$ cd pybossa && ln -s themes/default/translations

This will use the default translations of PYBOSSA for your server. We recommend to use these translations with the default theme. If you use your own theme, the best thing is to do your own translation, (see Translating PYBOSSA), as you might want to name things differently on the templates.

You can disable/enable different languages in your config file settings_local.py. For example, to remove French you can add this configuration to the settings file:

LOCALES = [('en', 'English'), ('es', u'Español'),
           ('it', 'Italiano'), ('ja', u'日本語')]

Also, you can always specify a different default locale using the following snippet in the same settings file

DEFAULT_LOCALE = 'es'

Note

PYBOSSA tries to first match the user preferred language from their browser. This will work for anonymous users, while registered ones can specify the language they want using their user preferences.

Note

As an alternative way to allow anonymous users to force a different language, PYBOSSA looks for a cookie named language where it expects the key of any of the supported langes in the LOCALES list. You can use JavaScript to set it up.

Creating your own theme

PYBOSSA supports themes. By default, it provides its own theme that you can use or if you prefer, copy it and create your own. The default theme for PYBOSSA is available in the repository pybossa-default-theme.

In order to create your theme, all you have to do is to fork the default theme to your own account, and then start modifying it. A theme has a very simple structure:

  • info.json: this file includes some information about the author, license and name.
  • static: this folder has all the CSS, JavaScript, images, etc. In other words, the static content.
  • templates: this folder has the templates for PYBOSSA.

Therefore, if you want to change the look and feel (i.e. colors of the top bar) all you have to do is to modify the styles.css file of the static folder. Or if you prefer, create your own.

However, if you want to modify the structure, let’s say you want to change the order of the elements of the navigation bar: the first element should be the About link, then you will have to modify the files included in the templates folder.

As you can see, you will be able to give a full personality to your own PYBOSSA server without problems.

Note

You can specify a different amount of projects per page if you want. Change the default value in your settings_local.py file of APPS_PER_PAGE to the number that you want. By default it gives you access to 20.

Using SASS and minifying JavaScript

PYBOSSA supports SASS thanks to Flask-Assets. If you want to compile SASS or SCSS just add to your theme static folder a new one named: sass. Then, you can request the compiled version from the templates like this:

{% assets filters="libsass", output="css/gen/yourcss.min.css",
          "sass/yourcss.scss"%}
    <link rel="stylesheet" type="text/css" href="{{ ASSET_URL }}">
{% endassets %}

The same can be done for Javascript using the filter minjs:

{% assets filters="jsmin", output="gen/packed.js",
          "common/jquery.js", "site/base.js", "site/widgets.js" %}
    <script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}

Results page

PYBOSSA allows you to present a results page for your server. Add a file named _results.html to the home directory in the templates folder and you’ll be able to show results about your project from one place:

Adding your Contact Information

By default, PYBOSSA provides an e-mail and a Twitter handle to contact the PYBOSSA infrastructure. If you want, you can change it to your own e-mail and Twitter account. You can do it, modifying the following variables in the settings_local.py file:

  • CONTACT_EMAIL = 'your@email.com
  • CONTACT_TWITTER = ‘yourtwitterhandle’

Terms of Use

You can change and modify the TERMSOFUSE for your server, by overriding the provided URL that we use by default. You can also modify the license used for the data, just change the DATAUSE_ link to the open license that you want to use.

Enabling Twitter, Facebook and Google authentication

PYBOSSA supports third party authentication services like Twitter, Facebook and Google.

Twitter

If you want to enable Twitter, you will need to create an application in Twitter and copy and paste the Consumer key and secret into the next variables: TWITTER_CONSUMER_KEY and TWITTER_CONSUMER_SECRET and uncomment them.

Note

This will also enable the Twitter task importer.

Facebook

If you want to enable Facebook, you will need to create an application in Facebook and copy and paste the app ID/API Key and secret into the next variables: FACEBOOK_APP_ID and FACEBOOK_APP_SECRET and uncomment them.

Google

If you want to enable Google, you will need to create an application in Google and copy and paste the Client ID and secret into the next variables: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET and uncomment them.

Receiving e-mails with errors

If you want to receive an e-mail when an error occurs in the PYBOSSA server (webhooks, background jobs, etc.), uncomment the ADMINS config variable and add a list of e-mails.

Background jobs error notifications

You can change the default behavior for receiving emails regarding failed background jobs. The two config variables are the following:

  • FAILED_JOBS_MAILS = 7 (days)
  • FAILED_JOBS_RETRIES = 3 (times)

FAILED_JOBS_MAILS instructs the system to send you a reminder after 7 days, if you have not solved the issue with the background job.

FAILED_JOBS_RETRIES instructs the system to retry the job N times. By default is 3.

Enabling Logging

PYBOSSA can log errors to a file or to a Sentry server. If none of the above configurations are used, you will get the errors in the log file of the web server that you are using (i.e. in nginx the errors will be in /var/log/nginx/error.log*).

Mail Setup

PYBOSSA needs a mail server in order to validate new accounts, send e-mails for recovering passwords, etc. , so it is very important you configure a server. Please, check the section Mail setup in the config file for configuring it.

Global Announcements for the users

Sometimes you will need to send a message to all your users while they are browsing the server. For example, an scheduled shutdown for installing new hardware.

PYBOSSA provides a general solution for these announcements via the settings_local.py.tmpl configuration file. The announcement feature allows you to send messages to the following type of users:

  • Authenticated users, basically all the registered users in the server.
  • Admin users, all the users that are admins/root in the server.
  • Project owners, all the users that have created one or more projects in the server.

Therefore, let’s say that you want to warn all your admins that a new configuration will be deployed in your system. In this case, all you have to do is to modify the ANNOUNCEMENT variable to display the message for the given type of users:

ANNOUNCEMENT = {'root': 'Your secret message'}

There is an example of the ANNOUNCEMENT variable in the settings_local.py.tmpl file, so you can easily adapt it for your own server. Basically, the announcement variable has a key and an associated message. The supported keys are:

  • admin: for admin users
  • user: for all the registered users (even admins)
  • owner: for all registered users that have one or more projects

Note

You can use a mix of messages at the same time without problems, so for example you can display a message for Admins and Owners at the same time.

Cache

By default PYBOSSA uses Redis to cache a lot of data in order to serve it as fast as possible. PYBOSSA comes with a default set of timeouts for different views that you can change or modify to your own taste. All you have to do is modify the following variables in your settings file:

# Project cache
APP_TIMEOUT = 15 * 60
REGISTERED_USERS_TIMEOUT = 15 * 60
ANON_USERS_TIMEOUT = 5 * 60 * 60
STATS_FRONTPAGE_TIMEOUT = 12 * 60 * 60
STATS_APP_TIMEOUT = 12 * 60 * 60
STATS_DRAFT_TIMEOUT = 24 * 60 * 60
N_APPS_PER_CATEGORY_TIMEOUT = 60 * 60
BROWSE_TASKS_TIMEOUT = 3 * 60 * 60
# Category cache
CATEGORY_TIMEOUT = 24 * 60 * 60
# User cache
USER_TIMEOUT = 15 * 60
USER_TOP_TIMEOUT = 24 * 60 * 60
USER_TOTAL_TIMEOUT = 24 * 60 * 60

Note

Every value is in seconds, so bear in mind to multiply it by 60 in order to have minutes in the configuration values.

Disabling the Cache

If you want to disable the cache, you only have to export the following env variable:

PYBOSSA_REDIS_CACHE_DISABLED='1'

Rate limit for the API

By default PYBOSSA limits the usage of the API with the following values:

LIMIT = 300
PER = 15 * 60

Those values mean that when a user sends a request to an API endpoint, a window of 15 minutes is open, and during those 15 minutes the number of allowed requests to the same endpoint is 300. By adding these values to your settings_local.py file, you can adapt it to your own needs.

Note

Please, be sure about what you are doing by modifying these values. This is the recommended configuration, so do not modify it unless you are sure.

Configuring upload method

PYBOSSA by default allows you to upload avatars for users, icons for projects, etc. using the local file system of your server. While this is nice for small setups, when you need to add more nodes to serve the same content, this feature could become a problem. For this reason, PYBOSSA also supports cloud solutions to save the files and serve them from there properly.

The local uploader is configured by default. We recommend to have a separate folder for the assets, outside the pybossa folder. In any case, for enabling this method use the following the config settings:

UPLOAD_METHOD = 'local'
UPLOAD_FOLDER = '/absolute/path/to/your/folder/to/store/assets/'

PYBOSSA comes with support for Rackspace CloudFiles service, allowing you to grow horizontally the services. Suportting cloud based system is as simple as having an account in Rackspace, and setting up the following config variables:

UPLOAD_METHOD = 'rackspace'
RACKSPACE_USERNAME = 'username'
RACKSPACE_API_KEY = 'api_key'
RACKSPACE_REGION = 'region'

Once the server is started, it will authenticate against Rackspace and since that moment, your PYBOSSA server will save files in the cloud.

Customizing the Layout and Front Page text

PYBOSSA allows you to override two items:

  • Front Page Text
  • Footer

If you want to override those items, you have to create a folder named custom and place it in the template dir. Then for overriding:

  • The Front Page Text: create a file named front_page_text.html and write there some HTML.
  • The Footer: create a file named _footer.html, and write some HTML.

Tracking the server with Google Analytics

PYBOSSA provides an easy way to integrate Google Analytics with your PYBOSSA server. In order to enable it you only have to create a file with the name: _ga.html in the pybossa/template folder with the Google Tracking code. PYBOSSA will be including your Google Analytics tracking code in every page since that moment.

The file _ga.html should contain something like this:

<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>

Adding web maps for project statistics

PYBOSSA creates for each project a statistics page, where the creators of the project and the volunteers can check the top 5 anonymous and authenticated users, an estimation of time about when all the tasks will be completed, etc.

One interesting feature of the statistics page is that it can generate a web map showing the location of the anonymous volunteers that have been participating in the project. By default the maps are disabled, because you will need to download the GeoLiteCity DAT file database that will be use for generating the maps.

GeoLite is a free geolocatication database from MaxMind that they release under a Creative Commons Attribution-ShareAlike 3.0 Uported License. You can download the required file: GeoLite City from this page. Once you have downloaded the file, all you have to do is to uncompress it and place it in the folder /dat of the pybossa root folder.

After copying the file, all you have to do to start creating the maps is to restart the server.

Using your own Terms of Use

PYBOSSA has a default Terms of Service page that you can customize it to fit your institutional needs. In the case that you do not want to use the default one, please, create a _tos.html file in the custom folder. You can re-use the template help/_tos.html and adapt it (it is located in the template/help folder.

Using your own Cookies Policy

PYBOSSA has a default cookies policy page, but you can customize it to fit your institutional needs. In the case that you do not want to use the default one, please, create a _cookies_policy.html file in the custom folder. You can re-use the template help/_cookies_policy.html and adapt it (it is located in the template/help folder.

Using your own Privacy Policy

PYBOSSA has a blank privacy policy page. We recommend you to add one, so your users know how you are using their data. To add it, just create a file named _privacy_policy.html file in the custom folder.

Exporting data to a CKAN server

CKAN is a powerful data management system that makes data accessible – by providing tools to streamline publishing, sharing, finding and using data. CKAN is aimed at data publishers (national and regional governments, companies and organizations) wanting to make their data open and available.

PYBOSSA can export project’s data to a CKAN server. In order to use this feature, you will need to add the following config variables to the settings_loca.py file:

As CKAN is open source, you can install your own CKAN server and configure it to host the data generated by your PYBOSSA projects quite easily, making it the data repository for your own projects. Another alternative is to use the the Data hub service that it is actually a free CKAN service for hosting your data.

Enforce Privacy mode

Some projects need sometimes a way to protect their contributors due to the nature of the project. In this cases, where privacy is really important, PYBOSSA allows you to lock all the public pages related to the users and statistics about the site and projects. Specifically, by enabling this mode only administrators will be able to see the following pages:

Anonymous and authenticated will see a warning message like this:

http://i.imgur.com/a1aqSCC.png

Additionally, the footer and front page top users will be removed with links to all these pages. If your project needs this type of protection you can enable it by changing the following config variable in your settings_local.py file from:

ENFORCE_PRIVACY = False

To:

ENFORCE_PRIVACY = True

Note

This feature is disabled by default.

Adding your own templates

PYBOSSA supports different types of templates that you can offer for every project. By default, PYBOSSA comes with the following templates:

  • Basic: the most basic template. It only has the basic structure to develop your project.
  • Image: this template is for image pattern recognition.
  • Sound: similar to the image template, but for sound clips hosted in SoundCloud.
  • Video: similar to the imaage template, but for video clips hostes in Vimeo.
  • Map: this template is for geocoding prorjects.
  • PDF: this template is for transcribing documents.

If you want to add your own template, or remove one, just create in the settings_local.py file a variable named PRESENTERS and add remove the ones you want:

PRESENTERS = ["basic", "image", "sound", "video", "map", "pdf", "yourtemplate"]

Yourtemplate should be a template that you have to save in the theme folder: /templates/projects/snippets/ with the same name. Check the other templates to use them as a base layer for your template.

After adding the template, the server will start offering this new template to your users.

In addition to the project templates themselves, you can add some test tasks for those projects so that the users can import them to their projects and start “playing” with them, or taking their format as a starting point to create their own. These tasks can be imported from Google Docs spreadsheets, and you can add them, remove them, or modify the URLs of the spreadsheets changing the value of the variable TEMPLATE_TASKS in settings_local.py:

TEMPLATE_TASKS = {
‘image’: “https://docs.google.com/spreadsheet/ccc?key=0AsNlt0WgPAHwdHFEN29mZUF0czJWMUhIejF6dWZXdkE&usp=sharing”, ‘sound’: “https://docs.google.com/spreadsheet/ccc?key=0AsNlt0WgPAHwdEczcWduOXRUb1JUc1VGMmJtc2xXaXc&usp=sharing”, ‘video’: “https://docs.google.com/spreadsheet/ccc?key=0AsNlt0WgPAHwdGZ2UGhxSTJjQl9YNVhfUVhGRUdoRWc&usp=sharing”, ‘map’: “https://docs.google.com/spreadsheet/ccc?key=0AsNlt0WgPAHwdGZnbjdwcnhKRVNlN1dGXy0tTnNWWXc&usp=sharing”, ‘pdf’: “https://docs.google.com/spreadsheet/ccc?key=0AsNlt0WgPAHwdEVVamc0R0hrcjlGdXRaUXlqRXlJMEE&usp=sharing“}

Setting an expiration time for project passwords

PYBOSSA allows the owner of a project to set a password so that only people (both anonymous or authenticated) that know it can contribute. By entering this password, the user will have access to the project for a time specified by:

PASSWD_COOKIE_TIMEOUT = 60 * 30

Which defaults to 30 minutes.

Validation of new user accounts

Whenever a new user wants to sign up, PYBOSSA allows you to add some extra security to the process by making the users have to validate a real email account.

However, if you don’t need this feature, it can be disabled (as it is by default) with this configuration parameter:

ACCOUNT_CONFIRMATION_DISABLED = True

Sending weekly email stats to project owners

Project owners that have the pro flag set to True can receive every week an update with the latest statistics about their projects in their email box.

By default this email is sent every Sunday. You can modify it in the settings file by changing it to another day:

WEEKLY_UPDATE_STATS = ‘Tuesday’

Newsletters with Mailchimp

PYBOSSA can show a subscription page to users when they create an account. By default is disabled, but if you want to enable it the system will show the page to registered users only once, to check if they want to be subscribed or not.

In order to support newsletters, you’ll have to create an account in Mailchimp and get an API_KEY as well as a LIST_ID to add the users. Once you’ve those two items you can enable the newsletter subscription as simple as this, add to your settings_local.py file the following values:

MAILCHIMP_API_KEY = "your-key"
MAILCHIMP_LIST_ID = "your-list-id"

Restart the server, and you will be done. Now in your Mailchimp account you will be able to create campaigns, and communicate with your registered and interested users.

Enabling the Flickr Task importer

PYBOSSA has several different types of built-in importers. Users can use them to import tasks for their projects directly from the Web interface. However, using the Flickr one requires an API key and shared secret from Flickr in order to communicate with the service.

Once you have an API key, you’ll have to add it to your settings_local.py file:

FLICKR_API_KEY = "your-key"
FLICKR_SHARED_SECRET = "your-secret"

For more information on how to get a Flickr API key and shared secret, please refer to here.

Enabling the Dropbox Task importer

PYBOSSA also offers the Dropbox importer, which allows to import directly all kind of files from a Dropbox account. In order to use it, you’ll need to register your PYBOSSA server as a Dropbox app, as explained here.

Don’t worry about the Javascript snippet part, we’ve already handled that for you. Instead, get the App key you will be given and add it to your settings_local.py:

DROPBOX_APP_KEY = 'your-key'

Enabling the Twitter Task importer

If you already have enabled the Twitter authentication, then the Twitter task importer will be enabled too. Otherwise, you will need to create an application in Twitter and copy and paste the Consumer key and secret into the next variables: TWITTER_CONSUMER_KEY and TWITTER_CONSUMER_SECRET and uncomment them.

Note

This will also enable PYBOSSA’s Twitter login.

Enabling the Youtube Task importer

The Youtube task importer needs a Youtube server key which you need to create in the Google API Console in YouTube Data API.

Once you have an API key, you’ll have to add it to your settings_local.py file:

YOUTUBE_API_SERVER_KEY = "your-key"

For more information on how to get a Youtube server key, please refer to here.

Enabling Server Sent Events

Since PYBOSSA v1.1.0, PYBOSSA supports Server Sent Events (SSE) in some views. This feature is really powerfull, however it brings some issues with it: it need to run PYBOSSA in asynchronous mode.

As this is not a necessity, by default PYBOSSA has this feature disabled. PYBOSSA uses SSE to notify users about specific actions (i.e. the result of a webhook in real time).

If you want to enable it, you will have to add to your settings_local.py:

SSE = True

Also, you will need to configure uwsgi and nginx to support SSE events. This is not trivial, as there are several different scenarios, libraries and options, so instead of recommending one solution, we invite you to read the uwsgi documentation about it, so you can take a decission based on your own infrastructure and preferences.

Latest news from PYBOSSA

Since version v1.2.1 PYBOSSA gets the latest news of its new releases, as well as anything related to what it’s produced by SciFabric regarding the crowdsourcing world. You can add more items if you want, by just adding to your settings_local.py file new ATOM URLs:

NEWS_URL = ['http:/http:///atomurl1', 'http://atomurl2', ...]

Enabling pro user features

Since version v1.2.2 PYBOSSA allows making available to all the users certain features that were before reserved to pro users.

Just locate them in the settings_local.py file. By default, they look like:

PRO_FEATURES = {
    'auditlog':              True,
    'webhooks':              True,
    'updated_exports':       True,
    'notify_blog_updates':   True,
    'project_weekly_report': True,
    'autoimporter':          True,
    'better_stats':          True
}

By choosing “True” on each of them, you are making that specific feature available only to pro users. On the other hand, selecting “False” makes them available to regular users as well.