A Complete Installation Guide for Orangescrum

A Complete Installation Guide for Orangescrum

(Update Nov 22, 2018: This piece has been updated to include the latest installation guide and the most current information on the original installation steps.)

Orangescrum is a simple project management and collaboration software which is available as open source and cloud edition. It has been ranked in the top 5 project management software in open source for three consecutive years.

With the advancement of Technology, data privacy has been a big concern for any organization. Be it is a startup or any megacorp, every organization have internal data which are not meant to be shared and should remain within office premises.

Thus, popularity Self-Hosted or On-premise software is on trend. Additionally, Self-hosted websites provide flexibility to customize the interface according to your own requirement.

We see consistent manifold growth in the number of Orangescrum community edition (Open Source) free downloads. We’re glad to know that from Freelancers to startups or Small Medium Businesses (SMBs) to large enterprises; all are opting for Orangescrum over other Project Management & Collaboration Software.

We have also seen that despite our best attempts few of our non-tech users still get stuck with installation issues.

Today I will take you through the right installation procedure or steps and how you can approach us to get quick support & guide from our consultants.

Things You Need Before Installing Orangescrum

Before you install any tool, it is important to be aware hardware and software requirement of the tool. Without this knowledge, any software will run to error.


  • RAM: minimum 2 GB
  • Processor: Core2duo or Higher
  • OS: Windows/Linux/Mac
  • Disk Space: 10 GB or Higher


  • Apache 2.2 or 2.4
  • MySql: 5.6 or 5.7
  • PHP: 5.6 or 7.x
  • wkhtmltopdf:- This extension is needed for export the data in form of PDF.
  • cURL (enabled)

I would suggest you to use at least 4BG RAM, otherwise you might face the slowness issue. The more RAM you use, the performance will be better.

The best recommend version for PHP is version 5.6 or 7.

Orangescrum open source edition can be hosted on localhost, IP or a domain through a server.

To complete the installation you need to complete the following installation steps irrespective of server or operating systems:

  • Base Code Upload
  • Database Configuration
  • Constants.php configuration
  • SMTP Configuration
  • Sub Domain Configuration
  • Email Notification Configuration
  • Cron Job setup
  • Node.js installation (if you purchased the Chat add-on)
  • Add-on Installer Installation
  • Add-on Installation


General Installation guide:

Now you have to create the environment for the installation.

  • Apache with ‘mod_rewrite’
  • Enable curl in php.ini
  • Enable MySQL extension in php.ini file by uncommenting the below line if it is commented. extension=php_pdo_mysql.dll
  • After that restart the Apache server
  • Change the ‘post_max_size’ and ‘upload_max_filesize’to 200Mb in php.ini
  • If STRICT mode is On, turn it Off.

On few shared hosting server, you can’t turn off the MySQL Strict Mode. So I would recommend you to check this with the service provider once before choosing the server.

If you can’t turn it off, then you may not able to sign up to create your account in Orangescrum.


  • Download the manual installation package (PHP 5.6 or PHP 7.x) from here.
  • Extract the archive. Upload folder (orangescrum-master or orangescrum-master-php7) to your working directory
  • Provide proper write permission (777 or 755) to ” app/tmp “, ” app/webroot ” and ” app/Config ” folders and their sub folders
  • Make sure that, there are three .htaccess files. One in the root directory, another in the “app” directory and the last one is in the “app/webroot” directory.
  • Make sure that, the .htaccess is working in your server
  • Create a new MySQL database named “orangescrum” (`utf8_unicode_ci` collation).
  • Get the database.sql file from the root directory and import that to your database.

Database Configuration

In the app folder, please go to the following folder & configure as below:


We have already updated the database name as “Orangescrum” which you can change at any point.

In order to change it, just create a database using any name and update that name as database in DATABASE_CONFIG section. And also you can set a password for your Mysql login which you will have to update in the same page as password. [Required]

SMTP and Constants.php configuration

  • Provide your valid “SMTP_UNAME” and “SMTP_PWORD”. For SMTP email sending you can use (Only one at a time) either Gmail or Sendgrid or Mandrill. By default we are assuming that you are using Gmail, so Gmail SMTP configuration section is uncommented. If you are using Sendgrid or Mandrill just comment out the Gmail section and uncomment the Sendgrid or Mandrill configuration section as per your requirement. [Required]
  • “FROM_EMAIL_NOTIFY” All the task created/updated notification email will be sent from this Email ID. [Required]
  • “SUPPORT_EMAIL” All other Emails and support related Emails will be sent from this Email ID. [Required]
  • You can also set up SMTP configuration by using PHP Mailer add-on.

Once you have provided all the details, please run the below URL:-



  1. http://localhost/orangescrum/cron/test_email/?to=emailId (if you are using localhost)
  2. (if you are using IP)
  3. http://myprojects.orangescrum.com/cron/test_email/?to=emailId (if you are using any valid domain)

For our demo site: http://demo.orangescrum.org/

The URL is http://demo.orangescrum.org/cron/test_email/?to=adm.demorangescrum@gmail.com

*Please make sure you are adding valid domain and email id in the URL.

If you are receiving below response, then your SMTP configuration is correct and your email notification will work.

SMTP Response

If you are got any other response, then there is some issue with SMTP configuration.

To resolve the issue, please follow the following steps:

  • Check your port is open or not
  • Use port 465, 587 for gmail
  • Correct your password if it shows authentication error
  • Disable two step verification (only for gmail)
  • Turn on less secure app in setting
  • Enable IMAP/POP in gmail setting

You can also visit here to understand the response and take the required steps.

Once you have applied all the steps mentioned above you’re all set to start with Orangescrum community as http://yoursiteurl.com/ from your browser.

You will be asked to provide your “Company Name”, “Email Address” and a “Password” to Login and start using Orangescrum.

Cron Job setup

This setup is important which will post your email reply in Orangescrum.

Follow this link for the Cron Job setup.  You can refer our helpdesk to get information to set up crons for Windows and Linux servers as well.

Watch a video of installation for Orangescrum on XAMPP

After following all the step, when you run the URL in browser, you may see an error like “4 Simple Steps to get started with Orangescrum”.

To solve this problem, please check or do the following:

  • Double check your database connection & credential
  • Set it back to ‘utf8’ instead of `utf8_unicode_ci` or vice versa
  • Check the Path of the Orangescrum Folder & make sure you have provided the same path in the Constants.php inside the app/Config folder
  • Check & make sure you have write permission (777 or 755) to “app/tmp” and “app/webroot” folders.

If you see your css or sign up page is breaking, then it is either an htaccess or file permission issue. Please check the htaccess whether it is properly working or not.

If you’re unable to create Company after submitting all details in the sign up page, then it’s a MySQL Strict mode issue. Please refer here to fix the issue.

Once you follow all these procedures, Orangescrum will work seamlessly.

To install it on various operating systems, follow the below links:

Automated Installation Guide for PHP 7

How to Install Orangescrum on Windows

How to Install Orangescrum on Mac

How to install Orangescrum on CentOS

How to install Orangescrum on Godaddy

How to Install Orangescrum on NGINX

Add-on Installer Installation:

  • Make sure to keep a backup of your existing “app” folder of your current working directory.
  • Extract the zip file(AddonInstaller-V1.0.zip) to your desktop.
  • Remove the existing “app” folder from your working directory then copy and paste the extracted “app” folder inside “AddonInstaller-V1.0” to your working directory.
  • If you are using local machine as storage (excluding Amazon S3), please replace the folder, named “files” inside the “app/webroot” folder from the back up to the current “app/webroot” folder.
  • Give write permission to “app/Config”, “app/tmp”, “app/Plugin” and “app/webroot” folders.
  • Import the “installer.sql” files from the extracted files to your current database. If you have already imported installer.sql before then no need to import it again. Only exception is if you are finding any new version of installer.sql then import to your current database.
  • Do necessary changes to “constants.php” and “database.php” inside “app/Config” folder again as you have done earlier. For Example SMTP email credentials in constants.php and database credentials in database.php.
  • Run your website once. Ex. 

http://localhost/orangescrum (if you are using localhost) (if you are using IP)

http://myprojects.orangescrum.com (if you are using any valid domain)

Note: if you are facing any issue or seeing any blank page after doing all the above steps, then just do the following once.

Replace “Configure::write(‘debug’,0);” with “Configure::write(‘debug’,2);” in the app/Config/core.php. Run the web url once and restore the debug value to 0 again. i.e Configure::write(‘debug’,0);

Add-on Installation:

  • Download the Add-on zip file.
  • Place the downloaded zip file(Ex. Timelog-V1.0.zip) in the “app/webroot” folder.
  • Log in to the application.
  • To install the add-on (Ex. Time log add-on) run below link once and follow the instructions. Ex. http://…./install/ganttchart (for GanttChart add-on)

Explore Orangescrum Add-ons

Video: How to install Orangescrum Add-ons

If you still face any issues, you can reach us at support@orangescrum.com, we’ll help & guide you on installation.