Composr Tutorial: Advanced configuration

Written by Chris Graham (ocProducts)
This tutorial will cover various advanced aspects of Composr configuration.


Configuration

Many advanced configuration options are presented and described in the main Admin Zone configuration module. As these are self explanatory, they will not be explained here in depth.

Advanced configuration options include (but are not limited to):
  • Enabling and disabling caching
  • Setting up details for an external SMTP server, if PHP can not itself send e-mails
  • Configuring details for various optional Composr features, such as the Point Store and galleries
  • Configuring details for logging
  • Configuring the Admin Zone todo-list block

Addons

Image

Installing an imported addon. Seeing warnings is normal, they just inform you what risks installing the addon may carry.

Installing an imported addon. Seeing warnings is normal, they just inform you what risks installing the addon may carry.

(Click to enlarge)

Image

Importing a non-bundled addon. We can import them direct from the https://compo.sr server.

Importing a non-bundled addon. We can import them direct from the https://compo.sr server.

(Click to enlarge)

Image

List of addons that are imported into the system (will be a mix of installed and non-installed).

List of addons that are imported into the system (will be a mix of installed and non-installed).

(Click to enlarge)

Composr is split into a series of addons.

All the "bundled" addons are installed when you install Composr but it is recommended that you should remove any that aren't needed once you are familiar with Composr. This is so as to make sure the non-required/unconfigured functionality doesn't accidentally get discovered by your visitors, and that any unnecessary complexity is removed. Less is more when it comes to good design, and if you ensure you have only the right set of features on your site then you can better tailor it for your visitors.

To manage addons go to Admin Zone > Structure > Addons. Any addons that are uninstalled will be archived so you can restore them later if you wish (although any data you created for the addons, such as entries, will be permanently lost).

There are also many non-bundled addons that you can install. Some of these are official and some of these are third-party. An addon may be non-bundled if any of the following hold true:
  • It is not considered mainstream enough
  • It ties into a third-party service that is not officially endorsed
  • It has been written by a third-party, and not checked to ocProducts standards
  • It is known to not fully conform to ocProducts standards but still is considered useful for some audiences
In reality the developers make pragmatic decisions. For example, as PayPal is so mainstream and the PayPal driver has low overhead, PayPal support is bundled with Composr – but as Facebook support is a much more expansive thing, Facebook support is in a non-bundled addon.

Non-bundled addons are installed via the "Import non-bundled addon(s)" link at the bottom of the Addons screen. The process goes as follows:
  1. Head to Admin Zone > Structure > Addons
  2. Scroll to the bottom
  3. Click the "Import non-bundled addon(s)" link
  4. Browse to the addon file
  5. Click the "Import non-bundled addon(s)" button
  6. (The addon is now imported, but not installed)
  7. Review the warnings and click Proceed (to be honest unless you are a programmer doing a code-review the warnings will likely not mean much to you, but they are there for those capable of analysing it all)
  8. (The addon is now both imported and installed)

Permissions

Composr has a rich, multi-layered, permission system. In creation of this system we have tried to strike a balance to keep all of these factors high:
  • power
  • ease-of-use
  • quickness of configuration

Composr has two main types of permission:
  1. privileges
  2. access permissions (for defining what may be viewed)

Composr uses a "best of" permission system, meaning that a member has the best possible access that the combination of all usergroups that they are in could give them. The one exception to this is when permissions are overridden for a page/catalogue/category the user will be limited by the override even if only a subset of their usergroup set is overridden at that level.

Setting permissions is described in detail in the Access Control and Privileges tutorial.

Privileges

Image

Privileges are set like this

Privileges are set like this

(Click to enlarge)

Privileges allow the assignment of permissions to usergroups via check-boxes. Privileges have a very specific meaning, rather than perform a higher level role of deciding whether something may be viewed.
Broadly, privileges are used to grant things like 'whether a member can access the site when it is closed', as well as to define sweeping permissions for content classes.
Sweeping permissions are there so that instead of making you specify who can control (edit/delete/etc) each/every content-item/type-of-content/category-contents individually, you can specify them by impact-class.
The 'impact' scheme is used to classify content according to its impact to the website and prominence. The following privileges may be set for usergroups for each of adding, editing and deleting content:
  • low impact content (things most people will probably not notice, like forum posts, Wiki+ posts, calendar events)
  • medium impact content (things most people are likely to notice, like downloads, banners, gallery images and videos, author profiles, catalogue entries, inactive polls, forum topics)
  • high impact content (things on the front page, like active poll, Comcode pages, news, quizzes)
  • (for editing/deleting only) only their own low impact content
  • (for editing/deleting only) only their own medium impact content
  • (for editing/deleting only) only their own high impact content

You can optionally override privilege settings in almost all the places where you may set access permissions. This provides a far greater degree of control but is completely optional, because if you do not choose to do any overriding then the global privileges will be used. You have the power of fine-grained control, and the simplicity of only having to do fine-grained control when you need to set a special case.

Using the Permissions Tree Editor you may configure access and privileges for almost any aspect of the system, as well as make batch changes with great efficiency.

For a good real-world example of how to set up privileges, see the 'Setting bypass-validation access' section of the organising discussion forums tutorial.

Access permissions

Composr access permissions do not work via an 'inheritance' system as such. Think of the above levels as barriers, not inheritance points. You need to get past each barrier to access a resource.

Access permissions are also configured by check-boxes. Composr supports a layered system of access permissions, where to access an entry, you need permissions to certain things 'above' the entry:
  1. Zone access permissions
  2. Page access permissions
  3. Catalogue access permissions (catalogues only)
  4. Category access permissions (where forums and galleries count as categories in this context)
To configure access permissions, you may edit the resource the permissions are for, or use the Permissions Tree Editor. For example, to edit zone access permissions, you need to edit the appropriate zone, or browse to the zone in the Permissions Tree Editor.

Installation Options

Image

Your Installation Options

Your Installation Options

(Click to enlarge)

To change an option set during installation, you generally use the external "Installation Options editor".

The Installation Options editor is completely separated from the main software, so that if your site ever breaks due to a misconfiguration in the <kbd>_config.php</kbd> configuration file (perhaps if you moved servers, and your database settings are no longer valid), you can fix it without having to hand-edit the file. As a result of the separation, the Configuration editor cannot empty caches automatically when you change an option, so after using it you should use the cleanup tools to empty the caches.

That said, Composr is actually pretty smart about caches. Often you'll find it has automatically realise when your caches need emptying. If you do need to empty caches manually, the cleanup tools can be accessed from Admin Zone > Tools > Website cleanup tools.

The Installation Options editor may be accessed by the http://yourbaseurl/config_editor.php script.
It can also be accessed from:
Admin Zone > Setup > Configuration > Installation Options.

To operate the script, you will need the master password that you specified at installation. If you have forgotten it, you will need to edit _config.php by hand.

Note

If you change servers you will also need to set file permissions. Please read the advanced installation tutorial for details on this. If you upload new themes, you will need to set permissions on the templates_cached/<lang> and *_custom directories after uploading.

You may use the config editor to:
  • Change the default site language
  • Change the database driver
  • Change the forum driver
  • Change the e-mail domain
  • Change the base-URL
  • Change forum and site database details
  • Change cookie details
  • Force 'URL Schemes' to be disabled, if you enabled it, but it failed to function correctly, locking you out of Composr

Advanced page structure changes

You may delete, and move pages using the Sitemap editor.

If you are moving a page from one zone to another, any page-links to that page (for example, in the menus or via page tags) will become invalid, unless they were specified as being in the zone named _SEARCH (which is used to create a link by dynamically searching all zones for the named page). You may wish to temporarily set up a redirection from the page as named in its original zone, to the page as named in the new zone. Details of this are given in the Tools for subsites and subcommunities tutorial. Setting up a redirection is also advisable if the page being moved is already well-indexed on search engines.

It is recommended that you never move default Composr pages because it complicates the upgrade process. Instead it is advisable to use the redirects feature instead (Admin Zone > Structure > Redirects).

.htaccess

Image

Finding how to change your settings

Finding how to change your settings

(Click to enlarge)

You can try and get PHP and the web server to use an optimal configuration, via a special file named .htaccess. If you want the 'URL Scheme' option to be enabled, this step is necessary.
Note that the file may already exist, potentially for either of two reasons:
  1. It was already there from before Composr was installed.
  2. Composr's quick installer automatically created an optimal file for you.

To try this, use FTP (or an equivalent tool) to rename the included recommended.htaccess to .htaccess (or if the file already existed, manually copy & paste in the extra lines). Our recommended options will tighten up your security where possible, and make sure Composr has certain PHP and Apache features turned on.
There are three caveats here:
  1. it will only work on an Apache (basically, Linux) server. Windows IIS servers are either managed from the IIS Administrative Tools, or from a webhosting control panel. For IIS the default web.config file achieves similar results for you and should work out-of-the-box.
  2. CGI server configurations can not use .htaccess files to configure PHP settings. On CGI servers (and note this works on IIS CGI servers), you need to create special php.ini files. For more information, see our FAQ ("How do I set PHP settings on a CGI server?"). This said, you can probably still set the non-PHP settings in your .htaccess (see below).
  3. some webhosts do not allow .htaccess files to be used to change any options, resulting in an error message. To test for this try plain.htaccess instead of recommended.htaccess:
    • If this succeeds, you are running CGI and you can't set PHP options from your .htaccess, so read (2) above. Keep your .htaccess file though, it's still worth having even without the PHP options.
    • If this fails too you will need to rename the file back and consult your webhost.

OpenSSL encryption (advanced)

If you wish to have encrypted Conversr custom profile fields, the PHP OpenSSL extension must be installed and configured. Further to this, a public/private key pair must be generated for the site, and uploaded to the server.

To generate the public/private key pair, you will need access to a computer running OpenSSL; either a local one, or your server via SSH. At a shell, execute the following commands to generate the public/private key pair:

Code

openssl genrsa -aes256 -out private.pem 2048
openssl rsa -in private.pem -out public.pem -outform PEM -pubout

The first command will generate a private key with a passphrase supplied when openssl requests it. The passphrase must be long, secure, and kept private, as it's the only way to access the private key (and thus the encrypted data). The second command will generate a public key from the private key, and will require the same passphrase to be entered again.

Once the key pair has been generated, they should be uploaded to your server, somewhere where they cannot be accessed from the Internet (so not in your htdocs directory). They should have their permissions set such that they can be read by your web server process, but nobody else.

The final step is to configure Composr to use the key pair to encrypt data. In the "Privacy options" section of your Composr configuration, set the "Encryption key" option to be the path and filename of the public key file (public.pem), and the "Decryption key" option to be the path and filename of the private key file (private.pem). If these options are not visible, it's because your server does not have the OpenSSL PHP extension installed or configured correctly.

See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.