crabgrass/config/crabgrass

= Crabgrass Configuration

There are three required configuration files:

* config/secrets.yml
* config/database.yml
* config/crabgrass.[production|development|test].yml

secrets.yml comes with useful defaults for test and development environment.
For production you need to set the SECRET_KEY_BASE environment variable.

Configuring database.yml is covered in INSTALL[link:files/doc/INSTALL.html] and PRODUCTION[link:files/doc/PRODUCTION.html].

Depending on what mode rails is run in, the appropriate <tt>crabgrass.*.yml</tt> file will be used. This page is about configuring the <tt>crabgrass.*.yml</tt> files.

= Global Options

=== Extensions

Crabgrass has extension folders in <tt>~/extensions/</tt>. You can control which plugins are loaded with the <tt>enabled_mods</tt> and <tt>enabled_pages</tt> options:

Enabled plugins stored in the <tt>~/extensions/mods/</tt> directory:

  enabled_mods:
    - super_admin

If <tt>enabled_mods</tt> is left blank, then no mods are loaded.

Enable plugins stored in the <tt>~/extensions/pages/</tt> directory:

  enabled_pages:
    - asset_tool
    - core_tools
    - rate_many_tool
    - task_list_tool
    - wiki_tool

If <tt>enabled_pages</tt> is left blank, then all tools are enabled.

=== Languages

If <tt>enabled_languages</tt> is left blank, then all available languages will be available. Otherwise, the options are limited to what is specified for <tt>enabled_languages</tt>. For a list of the possible language codes, see <tt>~/config/locales/*.yml</tt>.

  enabled_languages:
    - en
    - es
    - pt
    - ar

=== Email

The email configuration for crabgrass is a global setting and cannot be changed on a per-site basis. There are two delivery methods for email, sendmail or smtp.

If using sendmail, simply do this:

  email:
    delivery_method: :sendmail

If using smtp, things get more complicated:

  email:
    delivery_method: :smtp
    smtp_settings:
      domain: localhost
      address: smtp.gmail.com
      port: 587
      authentication: :plain
      user_name: xxxxxx@gmail.com
      password: xxxxxxx

For SMTP, to enable ssl connection the port must be 587 or 465. Some SMTP auth requires a domain, which does not have to be a real domain, but it must exist.

=== Miscellanous Global Options

paranoid_emails
  If true, then urls sent in emails will be obscured and will expire after 30 days.

ensure_page_owner
  If true, then every page must have an owner. If false, you are allowed to create
  pages without owners. The default is true.

default_page_access
  This option determines what page access level is shown by default when granting access
  and which access is used when adding access but none is specific. Valid values are 'admin',
  'edit', or 'view'. The default is 'admin'.

dev_email
  Email address where bug reports are sent.
  Example: dev_email: 'developer@domain.com'

text_editor
  Which text editor to use for editing wikis:

  Supported
    [greencloth_only]  only a plain text editor will be used
    [html_only]  only a html (wysiwyg) editor will be used

  Experimental
    [greencloth_preferred]  both editors will be available, but the default will be plain text
    [html_preferred]   both editors will be available, but the default will be html.

use_full_geonames_data
  If true, the full geonames data file (~800MB unzipped) will be downloaded and imported.

=== Sites

Crabgrass can host multiple social networks on one installation, each with their own domain. Each social network is called a 'site', and they are enabled and disabled using the <tt>crabgrass.*.yml</tt> file. The actual data for the site is stored in the database, and can be configured through the admin web interface.

Example sites configuration:

  sites:
    - name: blue
      admin_group: blueadmins
    - name: red
      admin_group: redadmins

This enables the sites named 'blue' and 'red' and assigns which group has administration access for each site.

Before you can enable a site, it must be created in the database:

  rake cg:site:create NAME=<name> RAILS_ENV=<env>

The <tt>name</tt> must match the "name:" part of the sites config in this file, and must be unique.

To destroy a site:

  rake cg:site:destroy NAME=<name> RAILS_ENV=<env>

Use caution when destroying a site. This will remove from the database all the site's users, groups, and pages.

If you want to disable a site without destroying it, simply remove the site's entry from the configuration file.

To see what sites are available:

  rake cg:site:list RAILS_ENV=<env>

=== Profiles

You can choose which fields can be filled out in a profile and which profile
tabs are active. If not present, these options default to allowing all.

Here is an example:

  profiles:
    - public
    - private
  profile_fields:
    - basic
    - notes
    - phone_numbers
    - email_addresses
    - locations
    - im_addresses
    - websites
    - cryptkeys


= Site Defaults

Sites are stored in the database. However, if they do not have a particular attributed configured (the value is NULL), then the attribute's value defaults to whatever is configured in <tt>crabgrass.*.yml</tt>.

The following attributes may be set globally in <tt>crabgrass.*.yml</tt>, or on a per-site basis (by using the database):

title:
  the title of the website.

email_sender:
  email address that outgoing emails are sent from. $current_host expands
  to be the domain of the current request. the defaul is: 'robot@$current_host'

email_sender_name:
  the name part of the "from" field. $user_name expands to the current user's
  display name, and $site_title expands to the title of the current site.
  the default is: '$site_title ($user_name)'

enforce_ssl:
  This setting only takes effect in production environments.
  Sets the force_ssl config setting of rails. It will:
  * only accept https connections.
  * set HSTS headers.
  * cookies will only work over tls/ssl.
  Note that we also use the secure headers gem which offers better
  protection for cookies while also working on onion domains:
  https://riseup.net/en/security/network-security/tor/onionservices-best-practices#onion-services-and-rails-4

show_exceptions:
  if true, exceptions are show to the user.

require_user_email:
  if true, user registration requires email address

default_language:
  language code of the default language to use

tracking:
  if true, we track user visits, logins and page views.

available_page_types:
  if set, limits what page types can be created.

chat:
  if false, chat is disabled

translation_group:
  the name of a group that is allowed access to edit translations.

limited:
  if set to true, then a user can only see people, groups, and pages from the
  current site. stuff from other sites will appear invisible. (note, currently,
  this is not actually stored in the database but must be globally configured).

signup_mode:
  determines how signup works. there are three options:
  (1) default --> anyone can sign up
  (2) closed  --> no one can sign up
  (3) invite_only --> you can sign up only if you were invited to join a group.

Unfrequently modified options:

  :pagination_size -- how many items to show before paginating
  :evil -- used for google analytic

= Examples

=== Example crabgrass.development.yml

  title: "Crabgrass Development"
  show_exceptions: true
  email:
    delivery_method: :sendmail
  sites:
    - name: site1
      admin_group: animals
    - name: site2
      admin_group: rainbow


=== Example crabgrass.production.yml


  title: "my crabgrass site"
  enforce_ssl: true
  show_exceptions: false
  tracking: true
  available_page_types:
    - WikiPage
    - DiscussionPage
  enabled_mods:
    - super_admin
  enabled_pages:
    - core_tools
    - wiki_tool
  enabled_languages:
    - en_US
    - es_ES
    - pt_BR
    - ar_EG
  email:
    delivery_method: :smtp
    smtp_settings:
      domain: localhost
      address: smtp.gmail.com
      port: 587
      authentication: :plain
      user_name: xxxxxx@gmail.com
      password: xxxxxxx
  sites:
    - name: blue
      admin_group: blueadmins
    - name: red
      admin_group: redadmins


=== All options

  ##
  ## GLOBAL OPTIONS
  ##

  ## enabled plugins stored in the mods/ directory

  enabled_mods:
    - super_admin

  ## enable plugins stored in the pages/ directory
  ## (to enable all tools, leave this empty)

  enabled_pages:
    - asset_tool
    - core_tools
    - event_tool
    - ranked_vote_tool
    - rate_many_tool
    - task_list_tool
    - wiki_tool
    - gallery_tool

  ## enable languages
  ## (to enable all languages, leave this empty)

  enabled_languages:
  - en_US
  - es_ES
  - pt_BR
  - ar_EG

  ## configure email

  email:
    delivery_method: :smtp
    smtp_settings:
      domain: localhost
      address: smtp.gmail.com
      port: 587
      authentication: :plain
      user_name: xxxxxx@gmail.com
      password: xxxxxxx

  ##
  ## SITE ENABLING (optional)
  ##

  sites:
    - name: blue
      admin_group: blueadmins
    - name: red
      admin_group: redadmins

  ##
  ## DEFAULT VALUES FOR SITES (optional)
  ##

  pagination_size: 30
  default_language: en_US
  enforce_ssl: false
  show_exceptions: false
  email_sender: "robot@$current_host"
  tracking: false

  # if left blank, all page types are enabled
  available_page_types:
    - WikiPage
    - AssetPage
    - EventPage
    - ExternalVideoPage
    - TaskListPage
    - AnnouncementPage
    - SurveyPage
    - DiscussionPage
    - RateManyPage
    - MessagePage
    - RankedVotePage
    - ArticlePage
    - Gallery
    - WikiPage

  # evil google analytics
  evil:
    google_analytics:
      site_id: UA-XXXXXX-X
      https: false
      enabled: false