[title sub="Written by Chris Graham"]Composr Tutorial: Basic configuration and getting started[/title]

Once Composr is installed, there is some basic configuration to do before your website is ready to open.

During basic configuration, you will be familiarising yourself with Composr for the first time. Please be patient: there is a lot to Composr, but once you have a mental image of how things work, you will find it a very powerful and malleable system.

[contents]decimal,lower-alpha[/contents]

[title="2"]Immediately after installing[/title]

[surround]
[media width="150" description="Reaching the Admin Zone from the main website" float="right"]data_custom/images/docs/tut_configuration/reaching_adminzone.png[/media]
When the installer finishes, you have a choice to either:
[list="a"]
[*] view your website
[*] run the Admin Zone's Setup Wizard (recommended)
[/list]

In either case you will be required to log in. Log in using an administration username. If you installed using Conversr (Composr's own forum system), the username and password will have been specified during installation (with the username being 'admin' by default).

If you choose to view your website, you are presented with a screen saying that the site is closed, with a login link. Once logged in, there is a link to the Admin Zone in your 'login block' (alternatively, you can always access your 'Admin Zone' directly by appending [tt]/adminzone[/tt] to your website's URL).
You will see that the Admin Zone keeps reminding you to run the Setup Wizard, so do so when you are ready.
[/surround]

[title="2"]The Setup Wizard[/title]

[surround]
[media width="150" description="The Setup Wizard" float="right"]data_custom/images/docs/tut_configuration/setupwizard.png[/media]
The [concept]Setup Wizard[/concept] will help you configure the name of your website and other key details in a few easy guided steps.

If you run the Setup Wizard, you may wonder later what it actually did, especially if you want to undo it.
The Setup Wizard can perform the following behind-the-scenes functions:
 - Generating a "Theme Wizard" [b]theme[/b]. You can access the Theme Wizard from Admin Zone > Style > Themes, Theme Wizard link (under Add Theme).
 - Generating a "Logo Generator" [b]logo[/b]. You can access the Logo Generator separately, from Admin Zone > Style > Logo Wizard.
 - Setting site [b]options[/b]. You can access these from Admin Zone > Setup > Configuration.
 - [b]Removing predefined content[/b]. Predefined content can be removed (e.g. default banners). Once this is removed you'd need to put it back manually, by adding it as you would any other content.
 - Placing [b]blocks[/b]. Blocks are dynamic features embedded directly into your pages/design (other software may use the term 'widgets'). You can place/change blocks via the Zone Editor at Admin Zone > Structure > Block/panel layout (Zone Editor).
 - [b]Copying rules[/b]. You can edit the rules page manually from Admin Zone > Content > Pages (Comcode pages).
[/surround]

[box="Important -- the Setup Wizard is usually a one-off process"]
[media float="right" thumb="0" framed="0"]data_custom/images/docs/dont.png[/media]
A very common mistake is to think of the Setup Wizard as a core part of Composr that you re-run whenever you want to make certain changes. This is not the case: it is a tool to help you get started, and not the main method for configuring Composr. Anything in the Setup Wizard is configurable elsewhere within Composr. Anything you see pre-set in there does not necessarily represent the current configuration of your site, just the default outcome of running the wizard.

For these reasons, we actually give out a warning if you re-run the Setup Wizard.
[/box]

[title="3"]Security level[/title]
On step 3 of the Setup Wizard, one of the options available is [b]Security level[/b]. Depending on the selection, a number of security configuration options will be set. You can always change these under Admin Zone > Setup > Configuration at any time.

Generally, we recommend the following security level depending on your use case:
 - [b]Minimum[/b] should only ever be used for very basic websites which will not utilise social features or public registrations (e.g. informational only sites).
 - [b]Low[/b] should only be used for websites using very basic social features and will not be handling much personal information. And any personal information handled will not involve children nor will be personally identifiable.
 - [b]Medium[/b] is recommended for most websites who do not utilise eCommerce functionality or handle highly-sensitive personal information.
 - [b]High[/b] is recommended for websites using eCommerce or will handle very sensitive personal information (e.g. sensitive custom profile fields or sites geared towards children).
 - [b]Ultra high[/b] is recommended for websites handling extremely sensitive data or functions (e.g. banks, government departments, cyber-security sites).

{|
! Config option
! Minimum
! Low
! Medium
! High
! Ultra High
|-
| Content Security Policy
| Off
| Off
| On
| On
| On
|-
| Session expiry time
| 1 day
| 3 hours
| 1 hour
| 30 minutes
| 15 minutes
|-
| Password reset process
| Reset link e-mailed
| Temporary password e-mailed
| Temporary password e-mailed
| Vague reset e-mail sent
| Vague reset e-mail sent
|-
| Password expiry days
| Never
| Never
| Never
| 1 year (365 days)
| 1 quarter (90 days)
|-
| Minimum password length
| None
| 4 characters
| 8 characters
| 12 characters
| 16 characters
|-
| [abbr="Password strength is determined by length, variation in letters, numbers, symbols, upper case and lower case, not using dictionary words, not using repeating characters, and not using text that is also present in usernames and e-mail addresses."]Minimum password strength[/abbr]
| None
| 2/10
| 5/10
| 8/10
| 10/10
|-
| [abbr="Whether we just give a general login error message instead of disclosing the specific error"]Login error secrecy[/abbr]
| Off
| Off
| Off
| On
| On
|-
| IP-strictness for sessions
| Off
| Off
| On
| On
| On
|-
| [abbr="How much computational power is required to hash / verify passwords; the cost number selected depends on the indicated amount of computational time calculated (Note that the ratchet for the maintenance password is always what yields 0.25 seconds computational time; it ignores this setting)"]Cryptographic ratchet[/abbr]
| 0.025 seconds computation
| 0.05 seconds computation
| 0.1 seconds computation
| 0.25 seconds computation
| 1 second computation
|-
| One guess per CAPTCHA
| No
| No
| Yes
| Yes
| Yes
|-
| CAPTCHA Noise
| Off
| Off
| On
| On
| On
|-
| [abbr="Audio CAPTCHA is easier to solve by bots but may be necessary to have enabled if you serve members with visual impairments."]Audio CAPTCHA[/abbr]
| On
| On
| On
| On
| Off
|-
| Brute force threshold
| 30 failed logins
| 15 failed logins
| 10 failed logins
| 5 failed logins
| 3 failed logins
|-
| [abbr="These can leak content titles"]URL Monikers[/abbr]
| On
| On
| On
| On
| Off
|-
| [abbr="It is best to have this enabled regardless of security level, or at least to remove the maintenance password from _config.php, when you are not using maintenance scripts."].htaccess restrictions on maintenance scripts[/abbr]
| No
| No
| No
| Yes
| Yes
|-
| [abbr="Require e-mail verification when a member tries to log in from a new IP address"]Enquire on new IP addresses[/abbr]
| No
| No
| Administrators
| Administrators and Moderators
| Administrators and Moderators
|}

[title="2"]Notifications[/title]

Chances are that you'll want e-mailing whenever things happen on your site. You can do this through your personal notification settings. Go to your profile, choose the Edit tab, and choose the Notifications sub-tab.

In particular you'll probably want to know about content needing validation, various kinds of messaging activity (e.g. support ticket posting), and eCommerce activity.

This is described in more detail in the [page="_SEARCH:tut_notifications"]Notifications[/page] tutorial.

[title="2"]Editing configuration[/title]

[surround]
[media width="150" description="The list of configuration sections" float="left"]data_custom/images/docs/tut_configuration/configuration.png[/media]
[media width="150" description="The most important area of the configuration are the General options in Site options" float="right"]data_custom/images/docs/tut_configuration/configuration_actual.png[/media]
You'll want to configure your configuration, at Admin Zone > Setup > Configuration.

When you visit the full configuration page to fine tune your configuration, you will see that configuration options are split into a number of sections and subsections.

The most important options are in 'Site options', choose that and scroll down your browser window until you find the subsection entitled, 'General'. Once done, scroll to the bottom of the page and click the 'Save' button.

There are many more options in the main configuration, and the actual options available depend on which addons are installed.

Repeat for all other sections you may want to edit.

We don't list all the options in the documentation because they are often either obvious/self-describing, or too specialist to mention -- so it's a good idea to browse through to see what interests you.
[/surround]

[title="2"]Editing default Comcode pages[/title]

There are a number of default pages on your site. Standalone editable pages within Composr are called "Comcode pages".

For details on how Comcode pages work and what the default ones are, see the [page="_SEARCH:tut_comcode_pages"]Adding standalone pages of content (via Comcode)[/page] tutorial.

[title="2"]Default banners[/title]

If you are not running a community site, you will almost certainly want to delete the default banners. Three banners are added into the system by default, to give websites a 'leg up' and a working view of the banner rotation: but they may not be appropriate. If you ran the Setup Wizard then you have already been given a choice to remove these banners automatically.

[title="2"]Editing logo theme images[/title]

[surround]
[media width="150" description="Editing a logo theme image" float="right"]data_custom/images/docs/tut_configuration/logo_2.png[/media]
[media width="150" description="Choosing theme images to edit" float="right"]data_custom/images/docs/tut_configuration/logo_1.png[/media]
You will want to change your logo to give your site an individual identity. You may either do this manually, or by using the Logo Wizard; the rest of this section will assume that you are doing it manually.

When you change images, styling, or low-level HTML structure (defined in templates), you are editing the theme of the site. Therefore to do it, you should go to Admin Zone > Style > Themes.
When you choose to manage images in the default theme, you will be warned against editing the default theme; for this simple task, the warning is irrelevant, and we therefore recommend you click 'ok'. If you are feeling adventurous, you could add a new theme, and continue sculpting your theme as you go.

Choose [tt]logo/-logo[/tt] (the logo for the Welcome Zone, and the logo for any zone that does not have its own) from the drop-down list presented. After clicking the button you will see the current image; all you need to do is create your own replacement on your computer (as a [tt].jpeg[/tt]/[tt].jpg[/tt], [tt].gif[/tt] or [tt].png[/tt] file) and choose to browse for it to upload. You do not need to erase the current URL, as your upload will replace it, and you definitely should leave the 'Name' field unchanged.

Your choice of image file formats:
 - Use either [tt].png[/tt], [tt].jpg[/tt], or [tt].gif[/tt] files:
  - [tt].jpg[/tt] is usually the best choice for a logo, because the file size can be very low. Be aware though that the JPEG format is a 'lossy' format, i.e. the higher the compression, the lower the quality of the image. JPEG does not support transparency.
  - [tt].png[/tt] never loses quality, and also supports transparency -- but the sizes are a bit larger.
  - [tt].gif[/tt] is only really a good idea if you need animation, which is unlikely for a logo. Soon will be able to do animation with [tt].png[/tt] via [url="APNG"]https://caniuse.com/#feat=apng[/url].
 - Do not ever try and use [tt].bmp[/tt] files with Composr, as they do not have proper compression, and are designed for Windows only.
[/surround]

[title="2"]Editing menus[/title]

[surround]
[media width="150" description="The menu editor" float="right"]data_custom/images/docs/tut_configuration/menu_editor.png[/media]
[media width="150" description="The default menu" float="right"]data_custom/images/docs/tut_configuration/menu_edit_link.png[/media]
You may wish to remove some of the links from the default menus on your installation. To do this, log in as an administrator and click the 'Edit menu' link.

The menu editor is covered in the [page="_SEARCH:tut_menus"]Customising what's on the menus[/page] tutorial.
[/surround]

[title="2"]The system scheduler[/title]

In order for aspects of Composr that support scheduling to work it is necessary to set up a system level scheduling task to run the [tt]data/cron_bridge.php[/tt] file at least every 10 minutes (but ideally every minute). By doing this, you tie in Composr's system scheduler with the server's scheduler.

Examples of scheduling scripts:
 - Sending out calendar event notifications
 - Sending out regular notification digest e-mails
 - Sending out birthday notifications
 - Running automated backups
 - Sending automated welcome e-mails to new members
 - Sending catalogue view reports and handling classified ad expirations
 - Sending out reminders for registration confirmation mails that were not ever actioned by the joining member
 - Sending out automatic newsletters
 - Sending newsletters (dripping out e-mails over a period of time, to stop resource spiking)
 - Processing tasks that are in the queue (if the task queue is enabled)
 - Running purges, such as logs, personal data (privacy), and cache
 - Running the Health Check
 - Processing statistics
 - Updating the sitemap

The [tt]data/cron_bridge.php[/tt] file can either be run by passing the PHP file through the PHP interpreter (common), or by calling the URL (see "Help -- my webhost does not support Cron!"). More details are in the following sections. Don't call up the URL by hand then never finish configuring it, because if you do then Composr will start assuming the system scheduler is working from then on which can make testing it a bit harder (once it is called once it is marked 'working' by the system -- applicable features will become available, and the todo item will be removed from the checklist on the front page of the Admin Zone).

[title="3"]Specific advice for Linux[/title]

[media width="150" description="Setting up Cron in the cPanel webhosting control panel (different control panels vary in their UI)" float="right"]data_custom/images/docs/tut_configuration/cron.png[/media]
On Linux, the system level scheduler is 'Cron', and the process of adding a task is known as 'setting up a Cronjob'. Many webhosting control panels allow you to do this.

The following command might work for a Composr installation in the [tt]/home/examplesite/htdocs[/tt] directory:
[code="Bash"]
php -C -q -c /home/examplesite/htdocs/.user.ini /home/examplesite/htdocs/data/cron_bridge.php
[/code]
The above command is just an example. Your real path will obviously be different, but also the PHP program may have a different name. Composr may be able to detect the correct command to use for you. Try opening up [tt]http://yourbaseurl/data/cron_bridge.php?query_mode=1[/tt]. The script should output the Cron command for you to use.

A good test is to try running the command you end up choosing manually in a command prompt, to check it is correct.

You should schedule Composr's [tt]cron_bridge.php[/tt] script to be loaded at least every 10 minutes. The manual Cron configuration (if you do it this way) will look like this:
[code="Bash"]
*/10 * * * * <command>
[/code]

[title="4"]Sandboxed Cron[/title]

Some webhosts only allow you to execute Cron commands directly under your home directory. This means you cannot call up the PHP command directory like above.
A workaround is to make a [tt]data/cron_bridge.sh[/tt] file (with execute permissions) containing:
[code="Bash"]
#!/bin/sh
php cron_bridge.php
[/code]
and tell Cron to execute [tt]/home/examplesite/htdocs/data/cron_bridge.sh[/tt].

[title="3"]Specific advice for Windows[/title]

On Windows the following command might work for a Composr installation in the [tt]c:\sites\examplesite\www[/tt] directory where PHP is in [tt]c:\php[/tt]:
[code="BAT"]
c:\php\php.exe c:\sites\examplesite\www\data\cron_bridge.php
[/code]
On Windows, either the webhosting control panel will provide a similar scheduler to Cron, or you can use the Windows 'Scheduled Tasks' feature as described below (assuming you have access).

The following is a step by step process for scheduling the running of [tt]cron_bridge.php[/tt] every 5 minutes:
1) Open up 'Task scheduler' (in your taskbar's 'Search' section, search for 'Task Scheduler')
2) Click 'Create Basic Task' off to the right of the window
3) Give the task a name and a description, then click 'Next'
4) Click 'Daily' for recurrence, then click 'Next'
5) Set the time and to re-occur every 1 Day, leave the start day and time to now, then click 'Next'
6) For the action, Click 'Start a Program', then click 'Next'
7) Under program/script add the location of [tt]php.exe[/tt] on your system: something like [tt]"C:\php\php.exe"[/tt] -- also include the double Quote Marks ([tt]""[/tt]) surrounding the file location because this is a command, and non-quoted spaces will result in an error
8) Under 'Add arguments' add the location to the [tt]cron_bridge.php[/tt] file which for the example above would be [tt]"c:\sites\examplesite\www\data\cron_bridge.php"[/tt] (note how the PHP command is split across two parameters -- step 7 having the [tt]php.exe[/tt] path and step 8 having the PHP file path) -- again surround in quote marks.
9) Click 'Next'
10) Tick (check) "Open the properties dialog for this task when I finish", then click 'Finish'
11) Under 'General', Change "Run only when user is logged on" to "Run whether user is logged on or not"
12) Tick (check) "Hidden"
13) Click 'Change User or Group'
14) Set to [tt]IIS_IUSRS[/tt] (or whatever the user your webserver is configured to use, if you customised that)
15) Click 'OK'
16) Click the 'Triggers' tab
17) Double click the 'Daily' trigger from the list
18) Tick (check) 'repeat task every' box and change the "1 Hour" to "5 Minutes"
19) Change 'for a duration of' to 'Indefinitely'
20) If you want to terminate hung PHP processes, tick (check) 'Stop task if it runs for longer than', and set to 1 hour
19) Click 'OK'
20) Click 'OK'
This should have now added a schedule within Windows scheduler to run the [tt]cron_bridge.php[/tt] file every 5 minutes. 
This step by step was created using Windows 11, the process may change slightly in other versions of Windows.

[title="3"]Help -- my webhost does not support Cron![/title]

In the event your hosting platform does not allow you access to Cron, there are a number of options available to you. One easy option is to have scheduled tasks run in the background when visitors access your site. To do this, you need to go to the Admin Zone > Setup > Configuration > Performance options, and tick (check) "Web requests run scheduled tasks".

There are a couple caveats to using web requests:
 - This will only work if your server supports PHP's register shutdown function. Most servers do.
 - This is not a reliable way to ensure scheduled tasks run on time. It depends on someone making a page request to your website to trigger making the tasks run in the background.

Alternatively, you can use an external service to call the [tt]data/cron_bridge.php[/tt] script by URL:
 - EasyCron provide direct instructions for Composr, and free and paid plans: https://www.easycron.com/cron-job-tutorials/how-to-set-up-cron-job-for-composr
 - Other free options are https://www.setcronjob.com/ (up to every 5 minutes but the schedule needs to be re-set every week) and https://www.onlinecronjobs.com/ (up to 5 jobs twice a day).

Simply sign up and  add the URL i.e. [tt]http://yourbaseurl/data/cron_bridge.php[/tt] to the scheduler and set how often you want it to run.

[title="3"]Parameters[/title]

There are a number of parameters you can pass to [tt]cron_bridge.php[/tt], either as URL parameters, or command line parameters.

 - [tt]limit_hooks[/tt] -- Pass the name of PHP files in [tt]sources[_custom]/hooks/systems/cron[/tt] to limit to just those scheduler items; useful if you want to force certain items to run more regularly; if you pass just a single item name then normal wait times for processing that item will be ignored
 - [tt]include_msn[/tt] -- When Composr has multi-site-network sub-sites, whether to run the system scheduler on all those sub-sites
 - Debugging:
  - [tt]verbose[/tt] -- Whether to put out extra output (not recommended when tied into Cron, as it will likely e-mail you every time it runs -- for that enable Cron logging instead from Admin Zone > Audit > Error Log)
  - [tt]query_mode[/tt] -- Whether to just spit out a Cron configuration command instead of running the scheduler
  - [tt]force[/tt] -- Whether to ignore scheduler item locking (for developers only); can be useful for testing and also clearing out stale locks
 - Loop configuration:
  - [tt]loop[/tt] -- Whether to not exit and just keep looping, for maximum processing speed (shared webhosts may not like this)
  - [tt]loop_wait_seconds[/tt] -- The number of seconds to wait between each loop cycles, to avoid constantly querying the database (default 3 seconds)
  - [tt]loop_max_seconds[/tt] -- The number of seconds before finishing the loop, in case memory usage keeps creeping up (default 3595 seconds, which is 5 seconds less than an hour, intended to align with the next Cron call)

For example, to call the system scheduler but only to execute tasks, with verbose info...
Via URL:
[tt]http://yourbaseurl/data_custom/cron_bridge.php?limit_hooks=tasks&verbose=1[/tt]
Via command line:
php cron_bridge.php --limit_hook=tasks --verbose

[title="3"]System scheduler interface[/title]
[surround]
[media width="150" description="The system scheduler hooks interface" float="right"]data_custom/images/docs/tut_configuration/scheduler_hooks.png[/media]
A system scheduler management interface is provided at Admin Zone > Audit > Low-level logging > system scheduler hooks. There, you can get an overview of every system schedule script:
 - Number of operations / items queued
 - Time between each run
 - Last run
 - Amount of time the script took to execute
 - Errors encountered
 - Whether it is enabled
 - Whether it is locked (this either means it is running now or it suffered a critical error; in the latter case the hook will not run again for 24 hours unless manually run)
 - Action buttons to enable/disable scripts or to execute scripts on-demand individually

This page also allows you to enable or disable specific scheduler hooks and to force-run a hook on-the-fly with verbose output.
[/surround]

[title="3"]Errors and Locking[/title]
The system scheduler supports basic locking. Each hook is 'locked' when execution begins, and then 'unlocked' when execution is finished [b]and[/b] no errors were encountered.

If a hook encounters an error, it will stay locked, which means it will not run again for 24 hours. The hook will remain locked so long as it continues resulting in an error. Once it runs without any errors, it will be unlocked. You can force-run a locked hook to clear its lock (e.g. after updating Composr).

Additionally, when a hook encounters an error, it will be logged to your main error log. And if you have [page="_SEARCH:tut_telemetry"]telemetry[/page] enabled, it will be relayed to the core developers automatically for review. Because the hook locks itself on error and will not run again for 24 hours, this should prevent your main error log from quickly filling up from a broken hook.

[title="4"]Background tasks locking[/title]
The background tasks hook behaves differently. If a background task fails, it will be individually locked rather than locking the entire tasks hook. The locked task must be manually run (without error) to clear its lock. Or, you can delete it from the database if you do not want to run it.

[title="2"]Closed site, and opening[/title]

[surround]
[media width="150" description="Your site is initially closed" float="right"]data_custom/images/docs/tut_configuration/closed.png[/media]
Once you feel your site is ready for the general public, you will want to 'open the doors' so to speak. You can do this from:
Admin Zone > Setup > Configuration > Site options > Closed site.

It's not advertised in the interface, but it is possible for a user to join a closed Conversr-powered site if they have been given the URL to the [tt]join[/tt] module (they can't see any panels in this event). Once they have joined they can't log in though unless they have subsequently been put in a usergroup with 'Access closed site' permission. The reasoning here is that the staff may give out the join URL and ask someone to use it, and then give special access because they want them to be able to get in early. If you do not like this behaviour, you can alter the join-module's permissions so that the Guest usergroup cannot access it.
[/surround]

[concepts
 1_key=".htaccess"                         1_value="A file used by the Apache web server to set configuration options that apply to the directory (and sub-directories thereof-) that the file is contained in"
 2_key="Main Admin Zone Configuration"     2_value="The 'Configuration' module of the Admin Zone"
 3_key="Installation Options"              3_value="The Installation Options for low-level settings such as database settings, available from config_editor.php"
 4_key="System scheduler"                  4_value="Composr's scheduler system, tying Cron to Composr's scheduler scripts so that they may be launched"
 5_key="Setup Wizard"                      5_value="A quick-start wizard for setting up common settings and profiles on a new Composr site"
]Concepts[/concepts]

[title="2"]See also[/title]

 - [page="_SEARCH:tut_install"]Installation[/page]
 - [page="_SEARCH:tut_security"]Security[/page]
 - [page="_SEARCH:tut_themes"]Themeing your site[/page]
 - [page="_SEARCH:tut_staff_advice"]Advice for choosing and managing staff[/page]
 - [page="_SEARCH:tut_legal"]Legal and social responsibilities[/page]
 - [page="_SEARCH:tut_comcode"]Comcode and the attachment system[/page]
 - [page="_SEARCH:tut_comcode_pages"]Adding standalone pages of content (via Comcode)[/page]
 - [page="_SEARCH:tut_menus"]Customising what's on the menus[/page]
 - [page="_SEARCH:tut_adv_configuration"]Advanced configuration[/page]
 - [page="_SEARCH:tut_notifications"]Notifications[/page]

{$SET,tutorial_tags,setupwizard,help_page,core_configuration,Configuration,Installation,novice}{$SET,tutorial_add_date,Aug 2008}{$SET,tutorial_summary,Once Composr is installed, there is some basic configuration to do before your website is ready to open. We discuss it here.}[block]main_tutorial_rating[/block]
