Composr Tutorial: Installation

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.

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:
  • Linux:
    • Softaculous
    • APS (maintenance status)
    • Installatron (maintenance status)
  • Windows:
    • Bitnami
• 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

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.

File upload demonstration

(Click to enlarge)

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

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

• Webhosting for Composr (including Composr minimum requirements)
• File permissions
• Installation on Linux
• Installation on a Windows desktop
• Installation on a Windows server
• Basic configuration and getting started
• The user-focused help page within Composr (linked from the menus)
• Uninstalling Composr from a server
• Installation on Google App Engine

Feedback

Have a suggestion? Report an issue on the tracker.