Mambo CMS Installation Manual
The information in this publication is furnished for informational use only, and should not be construed as a commitment by the Mambo Project. The Mambo Project reserves the right to update or modify the contents. The Mambo Project assumes no responsibility or liability for any errors or inaccuracies that may appear in this publication.
Released under the Free Document License.
Before doing anything else make sure your web server meets the following minimum requirements needed to install the Mambo CMS:
- PHP 4.2.x or above – http://www.php.net
- MySQL 3.23.x or above – http://www.mysql.com
- Apache 1.13.19 or above – http://www.apache.org
Mambo can be used with most major browsers including Internet Explorer (version 5.5+) Netscape, and Mozilla Firefox. These browsers take great advantage of Mambo's administrative interface.
In order for Mambo Open Source CMS to work properly, you will need to set up a MySQL Database prior to beginning the installation process. When installing it for the first time, Mambo will ask for the following information:
- The name of your database
- The name of the host, this is usually called “localhost” if you are installing on a PC or a local server. However, if you are using shared hosting, check with your hosting provider to be sure this is the case.
- The username and password of your MySQL database
You should ask your web server provider if you are not sure about how to go about installing a MySQL database, and what the above details relate to, before beginning the installation!
NOTE: Please check to see if your server provider has set your hosting account to Safe Mode. You will be unable to install Mambo with the Mambo installer if your server is set to safe mode. If this is the case, you will have to manually install Mambo. More information regarding the installation process can be found later on in this guide.
Getting the Files
Your first order of business is to get all the required files. The main distribution files for Mambo can be downloaded from here.
The file will be a compressed archive so you will need a utility program – either locally on your host server – that can “unzip” the archive.
Unzip the distribution file into a directory under your web server root. If you are using the Apache web server, this is typically c:/apache/htdocs on Windows and /usr/local/apache/htdocs on a POSIX system but it may vary. We are assuming you have a working web server and that you know where to put files to display on the web server.
What you do to install Mambo on a remote host is largely a function of what facilities your hosts provide and how skilled you are with server access. However, a simple and typical procedure may involve:
- Unzip the Mambo distribution to a local directory on your PC
- FTP the files to host server placing them either directly under or in a directory under the web server root. There are many free programs available for this, such as FileZilla.
Step-by-step information regarding the installation process will be discussed in the next sections.
Browser Installation (The Easy Way)
When installing Mambo for the first time, verify the system requirements previously stated above!
Assuming you have a working Apache web server, with PHP and a MySQL Database, you are on your way to installing Mambo.
When you have finished uploading the files and folders, go to your homepage (http://www.yoursite.com or http://yoursite.com/mambofolder). You should see a pre-installation check page generated by Mambo.
If you don't see the check page please verify the following:
- Was everything uploaded to your web site?
- Did you remove (and back up) your old web site?
- Do you really have an Apache / MySQL / PHP Web server?
- Do you have a configuration.php file in your mambo directory?
If everything checks out okay, and you still don't see the check page, try http://www.yourpage.com/installation/index.php. This is the direct address for the check page. If it doesn't show up, or you see a lot of errors and techno mumbo-jumbo, you probably don't have an Apache / MySQL / PHP Web server.
The pre-installation check page has three parts:
- The first checks that your system is able to run Mambo
- The second part are some PHP settings
- The third part checks several file and directory permissions
If everything checks out okay click the “Next button”. If there are some items highlighted in red, please ask your web service provider to correct them. If it is not possible to correct them yourself, you can still click “Next”, and see what happens.
The next page displays the license for Mambo.
If you agree with the terms, click the checkbox next to “I Accept the GPL License” and click the “Next” button. You will not be able to proceed unless you agree to the license terms.
After agreeing to the GNU General Public License, you will be taken to a new page that configures the MySQL database.
Enter the configuration of your MySQL Database. The hostname of your database is usually localhost. This means the database server is running on the same computer as your web server. On occasions where localhost is not a usable database server, you will need to contact your administrator.
You are given the option to delete the existing tables in the nominated database and also to back up the tables. You may also install some sample data. If this is your first installation we recommend you check this option.
When you have entered your database information properly, click the “Next” button. You will be asked to confirm the database operation. Click OK if you are satisfied that you can proceed. The database will be populated between this and the next step. Any errors that occurred during the initialization of the database will be displayed on the next page.
This step is pretty straightforward as it only consists of a page where you have to enter the name of your website. Enter a name for your site and click the “Next” button. Please note that special characters are usable in this information area.
The final step is a page used to confirm the installation directory, the URL to the Mambo site, your email address and the administrator password.
The email address is for your Super Administrator email. This user account is automatically created for you. The password you enter will be used for your “admin” account. The username for the Super Administrator is “admin”. You may change the randomly generated password if you desire.
The permission settings will be used while installing Mambo itself by the Mambo addon-installers and by the media manager. If you are unsure what flags will be set, keep the default settings for the moment. You can still change these flags later in the site global configuration.
Click the “Next” icon. The final page confirms the status of the installation and the Super Administrator login name and password.
Do not forget your Super Administrator login name and password as it is not possible to enter the admin section without this. If you lose this information, you must the restart the entire setup procedure.
For security reasons you are reminded to delete the installation folder, and then refresh the page. Until this is done, Mambo will not work.
There are two buttons that will take you to either the Mambo Site or the Site Administrator. If this is your first installation click the “View Site” button. You should see your new Mambo site. Take a moment to explore some menu options. When you are ready, click the “Administrator” link in the Main Menu. Enter the user name and password as described earlier.
If this is not your first time then you will know what to do next.
Your set up has now been completed, and you are ready to MAMBO!
Manual Installation (The Less Easy Way)
NOTE: This is the approach you need to take when APACHE SAFE MODE is on.
First, you must have the base environment for Mambo as described in the System Requirements section. We have thoroughly tested Mambo on Linux, Free BSD, Mac OS X, and Windows. These are recommended platforms, but anything else that can run the 3 pieces of software listed below should do it.
You MUST ensure that PHP has been compiled with support for MySQL, zlib and XML in order to successfully run Mambo.
First of all, download the Mamb.zip archive as stated at the beggining. You can run Mambo as a full site e.g. http://www.mysite.com, or you can run it in a subdirectory of another site e.g. http://www.mysite.com/mambo/.
You just have to edit the configuration.php file to tell Mambo which part of your site it is in. In this example, it will run in a directory of a web site:
Make a directory for the web site files, example:
- UNIX – /usr/local/www/public_html/mambo
- Windows – c:/apache/htdocs/mambo
Mambo is packaged in .zip format. Uncompress this distribution file into the directory you have created above using WinRar, for example:
unzip -xvfz latest_mambo_version.tar.gz -C /usr/local/www/public_html/mambo/
NOTE: Make sure you have a trailing slash and replace latest_mambo_version with the version you have downloaded.
To make the configuration file editable:
- Open FTP and go to your site root
- CHMOD configuration.php to 777
Additional Notes on CHMOD [Permissions]
For additional security, return configuration.php to CHMOD 644 after making changes.
More information on CHMOD and permissions can be found at http://catcode.com/teachmod.
Creating MySQL Database
Now you have to create a database for Mambo in MySQL. You can choose any name you want, but just remember to edit the configuration.php file with the name you choose. Use the mysqladmin command, for example:
mysqladmin -uroot -ppassword create mambo_database_name
NOTE: Replace ‘root' and ‘password' with the username and password that is used for your MySQL database.
You may also use phpmyadmin (a PHP-based, MySQL Administration tool), instead of the command line tools, as this makes dropping the database in quick and easy. Edit the file sql/mambo.sql and uncomment the very last 6 lines of the file starting at:
INSERT INTO `mos_users` VALUES (62, 'Administrator'
Import the SQL into your newly created database, from the sql/mambo.sql text file, for example:
mysql -uroot -ppassword mambo_database_name < sql/mambo.sql
NOTE: Replace ‘root' and ‘password' with the username and password that is used for your My SQL database.
If you wish to load the sample data provided with the distribution, then run the above command and replace sql/mambo.sql with sql/sample_data.sql. If you require the help support for the Administration section, use sql/help.sql. Copy the file configuration.php-dist to configuration.php in the root of your Mambo directory, for example:
UNIX - /usr/local/www/mywebspace/mambo
Then, update this file with the correct database name, password, host and directory info.
NOTE: Nearly 80% of installation problems are due to an incorrect absolute path. Ensure that you know what the absolute path is.
Here is an example of a configuration.php file:
File System Permissions
On POSIX based systems (like Unix, Linux, etc), you will need to change the permissions. There are two methods to do this, of which the first is recommended:
Telnet, or secure shell, to your server. Enter the following system command:
> ps -ef | grep apache
You may have to change the name of the process, depending on your system (for example, the process name could be httpd). You may receive output like the following:
root 7508 1 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7511 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7512 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7513 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7514 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7515 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7521 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7522 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
nobody 7523 7508 0 08:58 ? 00:00:00 /usr/local/apache/bin/httpd
This tells you that the user “nobody” is running the web server process. Change to the Mambo directory. Enter the following system command (substitute the user name appropriate for your system):
> chown -R nobody .
WARNING: Make sure the user you use to ftp or Administer the site is in the file system group, and that all files have the permission set to 775. If you don't, you may not be able to edit files on the file system remotely.
The second method, is to change the permissions of the images, media, uploadfiles and administrator/backups directories to 707, this should be done recursively:
chmod -R 707 images chmod -R 707 media chmod -R 707 uploadfiles chmod -R 707 components chmod -R 707 languages chmod -R 707 modules chmod -R 707 templates chmod -R 707 administrator/backups chmod -R 707 administrator/components chmod 744 configuration.php
Logging into the administration site
Go to http://www.yoursite.com/administrator and use “admin” as the username and the password. You can also login from the front end as an editor using “editor” as username and password.
Admin email address
When you login into the Administration section of Mambo for the first time, remember to change the email address of the Administrator to your own. This way you will receive all emails automatically sent by the system. Mambo will prompt you to delete your Installation folder and then refresh the page. This is for security reasons so that a malicious user cannot change your installation. Until this is done, Mambo will not work.
You are now looking at two menu items, Admin, or Frontend button. You will want to click your admin button, and go straight to the Administration panel, to set up the various configuration features of Mambo.
Your set up has now been completed, and you are ready to MAMBO!