Composr Tutorial: Installation

Written by Allen Ellis
Before you begin using Composr, you will need to install it. Installing Composr is easy with our installation utility, which will be explained in detail in this tutorial – or various third-party systems can install Composr for you automatically.

Table of contents

  1. Composr Tutorial: Installation
    1. Your options (preface)
    2. Prerequisites
    3. Deciding: Quick or manual install
    4. Preparing files
      1. Using SFTP/FTP
    5. Installation
    6. Advice for webhosters
    7. See also

Your options (preface)

Before we dive into instructions, we should lay out the different options you have for installation.

Your options are:
  • Use a supported integration. You can install with just a few clicks (and skip this tutorial) if your webhost/server has a supported integration such as:
  • Use the quick installer. This tutorial covers this case.
  • Use the manual installer. You are unlikely to need to use the manual installer. If you do, the File permissions tutorial provides supplementary information to the installation fundamentals described in this tutorial.
  • Get a professional developer to install for you.

We don't cover anything about choosing webhosting or configuring servers in this tutorial. If you need this material then see the links under "See also".

To some degree the instructions assume you are running under a webhosting control panel (or just 'control panel'), rather than installing onto a server/VPS/PaaS you are managing directly. That said, if you are managing a server directly the process isn't that different, you just create the database and deploy the files differently (using standard techniques you already would know), and we have included a few references to that in this tutorial. Specific techniques are covered in other tutorials, see the links under "See also".

Apart from the above caveat, this tutorial should be valid for Windows, Linux, and Mac.

Prerequisites

Before you install Composr:
  1. Ensure that your webhost covers our minimum requirements.
  2. Make yourself familiar with the control panel your webhost has provided. Common ones include Plesk (maintenance status) and cPanel (maintenance status). Your webhost may not name the control panel, but they will have provided you to the details to log in to it. You will typically use the control panel to set many things up, including: databases, subdomains, SFTP/FTP accounts, e-mail accounts. As mentioned in the previous section, if you don't have a control panel you will need to configure things by hand.
  3. You also need the following information from your webhost:
    • SFTP/FTP hostname
    • SFTP/FTP username
    • SFTP/FTP password
    Usually SFTP/FTP details are instead e-mailed to you when you sign up for webhosting. Sometimes you need to set themselves up yourself in the control panel, particularly if you are installing to a subdomain.
  4. You need to set up a database †, and note down these details:
    • MySQL hostname
    • MySQL username
    • MySQL password
    • MySQL database name
    Typically you can set the database up yourself in the control panel. It can be a bit fiddly, so here are instructions for cPanel and Plesk. You typically need to create the MySQL user first, then the database, then provide access for the user to the database. The hostname is usually either just 'localhost', or something specific that the control panel will tell you. If you don't have a control panel you'll need to do this by hand via the MySQL console. Be careful that often you don't get the exact username and database name you specify: often prefixes are added for you, and you'll be shown this if you look carefully. Composr will need to know the full names when you install. Make the MySQL password random and unique, as it will be stored in plain-text in your on-disk configuration.

† Composr does not need its own database (i.e. it can share one), but if you are able to create a new one it is often preferable for reasons of tidiness. The database user needs full read/write/administer access over the database Composr will be installed in. Sometimes you set this access by ticking (checking) to have all permissions on your user. Sometimes you do it by setting the 'User role' to something such as 'dba' (e.g. h-sphere on Windows).
Specifically for MySQL the low-level permissions needed are:
  • Read: SELECT
  • Write: INSERT, UPDATE, DELETE
  • Administer: CREATE, DROP, ALTER, INDEX
Similar products require the same information.

If you would like to use a 3rd party forum system for your website, we require that you install that before installing Composr. We recommend you use the inbuilt forum though (Conversr).

Deciding: Quick or manual install

At some point you'll need to decide which method you'd like to use to install Composr. You have two options, the quick installer, or the manual installer.

We highly recommend choosing the quick installer. This is a simple process, where you upload two files to your web server, then launch our installation utility from there. It works on most servers.

The second option is the manual installer. This option requires you to manually upload all of Composr's files using something like FTP and apply permissions to them – the typical method for most CMSs. This method takes much longer – as there is a pause for "handshaking" as you upload each file. We maintain this version in case the quick installer fails on your webhost (e.g. if the webhost does not support PHP-accessible FTP or suEXEC in the way the quick installer needs).

Preparing files

Image

Example of "Download Now" link

Example of "Download Now" link

(Click to enlarge)

To install Composr, you must first download it from our website. It is generally best to choose the latest version, and, as stated above, we also recommend choosing the "quick method".

Download Composr from our website. Save it to a location where you'll be able to find it.

After it downloads, you'll need to extract the files. The exact methods for doing this will vary based on which ZIP utility you use.

Using SFTP/FTP

An alternative to uploading via SFTP/FTP is using the File Manager within the control panel. However it is worth trying to get it working using SFTP/FTP, as it is a valuable basic tool.

If you don't have a control panel then you may also not have SFTP/FTP, depending on the server configuration. You may have to use something like scp, or Windows Remote Desktop, to get the files onto your server.

Image

File upload demonstration

File upload demonstration

(Click to enlarge)

Image

Internet Explorer FTP login

Internet Explorer FTP login

(Click to enlarge)

The next step is to upload the files to your web server. To do this you'll need an SFTP/FTP client (such as FileZilla, or use the one that comes with Windows). The exact steps to upload the files depend slightly depending on which SFTP/FTP client you choose.

If you'd like to use the one bundled with Windows, open a new Internet Explorer window, and in the address bar, type ftp://[email protected], replacing username with your username and servername with the servername given to you by your webhost. You should be presented with a login screen (if not, you can access it by choosing File > Login As), where you can enter the username and password given to you by your webhost (image). Then you'll need to navigate to your webroot (possibly in a folder called www or httpdocs). If you can't find your webroot, e-mail your webhost for help.

At this point you need to decide whether you want your website to reside in your root folder or not. If you choose to place it in your root folder (which is the recommended option), people will be able to access your site by going to http://yourbaseurl (unless you don't own your own domain name). If you choose to place it in a subfolder (for example, "subfolder"), people will access your Composr installation by going to http://yourbaseurl.

When you successfully connect, find your webroot, and navigate into a subfolder if you chose to. You need to upload the files that were inside the ZIP package you downloaded. If you chose the quick installer, these files are called 'install.php', the other is called 'data.cms'. If you chose the manual installer, there will be many more.

You now need to put these files in the desired folder. This can usually be done by dragging and dropping the files from your computer to your webhost in your SFTP/FTP client (image).

Installation

Image

The Composr installation screen

The Composr installation screen

(Click to enlarge)

After you upload these files, you've completed the hardest part of the installation. The next step is to open your web browser and go to http://yourbaseurl/install.php (substitute http://yourbaseurl/ as appropriate for your domain and install path). You should be greeted with a welcome screen, asking you which language you would like to use.

On step two, you are shown a licence agreement. You must agree to the licence agreement before you can install Composr. You also have the opportunity to sign up for our newsletter, which will notify you by e-mail of any updates to our software. Composr will never sell or rent your e-mail address to a third party. You can read our privacy policy for more information.

On step three, you are presented with a choice to choose which forum system you would like to use for your website. We strongly recommend that you use Composr's own forum (Conversr), which if chosen will be installed at the same time as Composr. If you're using a third-party forum software, then you will need to already have it installed. Select the name of the software on the left, and then choose the appropriate version from the right-hand column.

Image

Step 4: primary configuration

Step 4: primary configuration

(Click to enlarge)

On step 4 is where the core configuration settings are input. Fill out each of the configuration options to the best of your knowledge.

Most of the settings will have been auto-detected for you. You will definitely need to fill in the following fields manually though:
  • Maintenance password
  • Administration account password
  • Database details

There are no constraints on the kind of password to use, but it is a good idea to choose a very strong / random password for each (which you do not use anywhere else) and store them in a password manager or write them down.

All of the database fields should be filled out with the information you recorded earlier in this tutorial. When you finish, click the "Install Composr" link at the bottom of the screen.

Hopefully, at this point you'll receive this success message. If you receive any errors, return to the previous page and correct them. Click the "Proceed" button to continue through the installation. There will be a few more similar screens until you finish the installation.

The installer will proceed through additional steps as follows:
  • Step 5:
    • Extract files (Quick installer only)
    • Upload files (FTP only)
    • Delete previous installation if it exists
    • Save configuration file _config.php
    • Install the core parts of the Composr system
  • Step 6:
    • Install Conversr (this is usually installed even if you won't be using it as some components of Conversr are necessary for Composr to work)
  • Step 7:
    • Install critical modules: admin_version (contains a lot of core database tables), admin_addons (so we can install addons), admin_permissions (so addons can install permissions)
  • Step 8:
    • Install addons, modules, and blocks.
    • This step can take a few minutes. To help prevent server time-outs, the installer will try stopping after about every 10 seconds and refreshing.
    • Note that the installer will only install addons which have an addon_registry hook, and modules / blocks which belong to any of those addons. If you have any addons, modules, or blocks you are developing which are not in / do not have an addon_registry hook, they will not be installed automatically by the installer. This is because the installer needs to know the dependency structure of the addons, modules, and blocks it installs for a stable installation. You can manually install the rest of your in-development addons, modules, and blocks later.
  • Step 9:
    • Internal maintenance; success screen.
  • Step 10 (internal only):
    • Triggered when you make your selection of what you want to do next.
    • This performs additional final maintenance like installing some custom fields or configuration options.

Image

Final screen

Final screen

(Click to enlarge)

Image

Step 5: success message

Step 5: success message

(Click to enlarge)

After you finish the installation, you are presented with one final screen, congratulating you on your successful installation, and giving you two choices – you can either jump right to your new homepage, or go to the Setup Wizard. If you have never used Composr before, we suggest that you run the Setup Wizard, as it will guide you through the basic settings of your website and familiarise you with the way Composr works.

As a final step you will have to delete the install.php and data.cms files you uploaded earlier, using SFTP/FTP (or the control panel's File Manager). This is important for security reasons and Composr will make you do this.

If you got an error message about having to delete the files just refresh the page once you have deleted them, and it will take you to where you intended to be.

The Setup Wizard ("Configure my Composr first") will guide you through some basic setup for your site, to give you a leg-up. It is not required, but most users will want to run it to set some basic things such as Site Name, colours, and what addons are to be kept installed.


Advice for webhosters

Note that Composr administrators have full control over their website code. They may execute their own custom PHP code trivially.

Therefore if you control the hosting and provide someone with a Composr staff username you should ensure that your hosting is either:
  1. locked down to only that site
  2. that you provide a non-administrator staff account
  3. that you trust any administrator with full control over the hosting


See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.