How to Use SuiteCRM: The Beginner’s Guide (First Install, the Permissions Rule, First Lead, and the Cron Lesson)

CodexFuse Team · 2026-11-02T06:46:52.618Z · 14 min read min read

Learn how to use SuiteCRM, the free open-source CRM: install it on a LAMP stack, fix the permissions rule, add your first lead, build an opportunity pipeline, and wire up cron.

Learning how to use SuiteCRM is really learning two things at once: how to run a free, self-hosted CRM, and how to think about your business's customer data as something you own instead of rent. This guide walks the whole beginner arc in one place — the suitecrm install on a standard LAMP stack, the file-permissions rule that kills more installs than anything else, the admin login, your first lead and the conversion lesson, the opportunity pipeline, the cron lesson that makes workflows and email actually run, plus email integration and basic reporting.

If you are starting from the very bottom of the hosting side, a CRM is a great first reason to rent a server. Our what is VPS hosting guide explains the model before you spend anything — SuiteCRM lives happily on a small VPS, and that is where this tutorial assumes it will run.

What Is SuiteCRM, Exactly?

SuiteCRM is a free, open-source CRM platform for sales, marketing, and customer service — built around the classic modules every sales team knows: Leads, Contacts, Accounts, Opportunities, Quotes, Campaigns, and Cases. If you want the one-paragraph definition for the suitecrm tutorial for beginners crowd: it is the CRM you install on your own server, where the software costs nothing, user seats are unlimited, and your customer data never leaves infrastructure you control.

One lineage note, stated once: SuiteCRM was born in 2013 as a fork of the last open-source release of SugarCRM, after SugarCRM walked away from open source — and the project launched with a commitment to keep every line of code free and open source. The license is the GNU Affero General Public License v3 (AGPLv3), not the plain GPL: that distinction matters if you ever host it as a service, so read the license text before building a business on top of it.

SuiteCRM 7 vs 8: Which One Do You Install?

Install SuiteCRM 8 as a beginner. The 8.x line is the current generation — 8.10.2, a security maintenance release from July 31, 2026, is the newest at the time of writing — and the 7.x line survives only as long-term support (7.15 ESR, supported until December 2027).

The two eras differ in one visible way, stated once: SuiteCRM 7 uses the classic SuiteP theme, while SuiteCRM 8 rebuilt the interface from the ground up on Angular + Symfony (running the battle-tested 7.x backend underneath). They install and configure differently — the permissions commands and the cron command are not the same — so every section below gives both variants where it matters, and you should check the official 8.x installation guide for the current details.

What Do You Need Before You Install SuiteCRM?

You need a standard LAMP stack with the versions the 8.10 compatibility matrix lists: PHP 8.2, 8.3, or 8.4, Apache 2.4, and either MariaDB 10.6 to 11.8 or MySQL 8.0 or 8.4. Node and Angular show up in the docs too, but only for front-end development — they are not required for a production install.

If you have never run a LAMP stack yourself, our Docker beginner guide is the fastest primer on the container mindset that makes self-hosting repeatable — though the official path below is the direct web installer.

How Do You Install SuiteCRM?

You install SuiteCRM with the official pre-built package, not a source build. The 8.x docs are explicit about this: "Unless you want to setup a development environment, you should download the pre-built installable packages available for download on suitecrm.com." Download the zip, unzip it, copy the files to your web root, set permissions (next section), and run the web-based installer in your browser — it walks you through the database connection, the admin account creation, and presents you with the crontab command you must not lose.

Do the install over HTTPS with the database on the same private network, create the SuiteCRM database and a non-root database user first, and use strong credentials for the admin account — the installer is your one and only setup wizard, so give it real values.

What Is the Permissions Rule?

The permissions rule is this: SuiteCRM's web server user must own the files, and the cache, custom, modules, themes, data, upload directories plus config_override.php must be group-writable. The vendor docs call incorrect permissions "the #1 cause of installation failure and 'White Screen of Death' errors" — if your fresh install shows a blank white page, you almost certainly skipped this step.

The 7.x variant, verbatim from the vendor guide (run in the SuiteCRM directory, replacing www-data with your web server user if different):

sudo chown -R www-data:www-data .
sudo chmod -R 755 .
sudo chmod -R 775 cache custom modules themes data upload config_override.php

The 8.x variant uses the more precise Symfony-style set, also verbatim:

find . -type d -not -perm 2755 -exec chmod 2755 {} \;
find . -type f -not -perm 0644 -exec chmod 0644 {} \;
chown -R www-data:www-data .
chmod +x bin/console

How Do You Set Up the Cron Job?

You put the scheduler on a system crontab or nothing automated in SuiteCRM ever runs. Workflows, scheduled email, campaign sends, and the schedulers all depend on one cron entry — the suitecrm cron entry — and the installer shows it on the final screen, where the docs say to copy it immediately.

The 7.x entry, verbatim, added as the web server user (crontab -e -u www-data):

* * * * * cd /var/www/html; php -f cron.php > /dev/null 2>&1

The 8.x entry calls the Symfony console instead, every minute, as the web server user:

* * * * * [path/to/php] [path/to/suite/instance]/bin/console schedulers:run > /dev/null 2>&1

The cron lesson, stated once: SuiteCRM never warns you that cron is missing — workflows and schedulers just silently never fire. After installing, go to Admin, then Schedulers, and confirm jobs are actually executing before you build anything on top of them.

What Is the Fastest Path from Zero to First Lead?

The whole suitecrm leads workflow in seven steps: install, fix permissions, add the cron job, log in as the admin you created, create one lead, convert it, and check the contact it produced. Each step takes minutes except the install.

1. Install with the pre-built package and run the web installer to the final screen.
2. Apply the permissions rule (755 files, 775 on cache/custom/modules/themes/data/upload) so the app actually loads.
3. Copy the crontab command from the installer's final screen into a system crontab as the web server user.
4. Log in with the admin account you created during the install.
5. Open the Leads module and create your first lead — a real one, not "Testy McTest".
6. Open the lead's detail view, click the Convert Lead icon, and create the Contact and Account from it.
7. Check the contact record — the lead's history now lives there, and the lead is gone from the Leads list.

How Do You Work with Leads?

You work with leads as the raw, unqualified top of the funnel: every new inquiry starts as a Lead, and nothing else in the system treats it as a customer yet. Create leads manually, import them from CSV, or capture them through web-to-lead forms, then qualify each one by phone, email, or meeting.

The conversion lesson, stated once: leads do not convert "into" accounts. A lead converts into a Contact (the person), and at conversion time you have the option to create a new Account (the company) or attach the new contact to an existing account — plus the option to create an opportunity from the converted lead. In the detail view, lead records carry a special fifth action icon — the Convert Lead icon — which opens the create view for the contact, account, and opportunity. Once converted, the lead record itself disappears from the Leads list; its history follows the contact.

How Do You Build an Opportunity Pipeline?

You build the pipeline from Opportunities — the suitecrm opportunities module is where qualified leads become forecastable revenue SuiteCRM inherits the classic stage list from its SugarCRM lineage, and every stage and probability is editable through the dropdown editor — so treat the table below as the default starting point, not a law.

The beginner habit that matters: update the stage every time the deal moves, not at the end of the week. A pipeline whose stages are stale is a forecast built on fiction — SuiteCRM can only report what you record.

How Do SuiteCRM Workflows Work?

SuiteCRM workflows — historically the Advanced Open Workflow (AOW) module — let you build custom automation that fires on conditions in any module: create a record, modify a record, or send an email, all without writing code. A workflow has three moving parts: the target module and its conditions, the actions to run (create record, modify record, send email), and when it runs.

The "when" is the part beginners miss, and it is the cron lesson again: a workflow set to run On Save fires immediately when a record is saved, while one set to run On Scheduler queues itself into the scheduler system — which only processes due workflow tasks when the "Process Workflow Tasks" job runs, which only runs if your cron entry exists. An On-Scheduler workflow with no cron entry is a workflow that does nothing, forever.

Start with one honest automation: an On-Save workflow that emails the sales rep when a new lead is assigned to them. If you outgrow built-in workflows, our n8n beginner guide shows how to wire SuiteCRM into hundreds of outside apps — workflows automate inside SuiteCRM, n8n automates around it.

How Do You Connect Email to SuiteCRM?

You connect email in two places: outbound, so SuiteCRM can send (workflow notifications, campaign emails, one-click emails from records), and inbound, so it can read. In the admin panel's email settings you configure the outbound SMTP account and test it; in the inbound area you attach mailboxes that the schedulers monitor on your cron schedule — inbound email can auto-create records like cases or leads.

Do the boring verification first: send a test email from the admin panel and confirm it arrives before you build a campaign on top of the settings. Email that "should work" is the second most common silent failure after cron, and the fix is always the SMTP credentials.

How Do You Build Your First Report?

You build reports in the Reports module, which can query any SuiteCRM module — leads by source, opportunities by stage, cases by status — and present them as rows, charts, or both. Build your first report on Leads grouped by lead source: it answers the most basic marketing question ("where do inquiries actually come from?") and it teaches you the report builder's three steps — pick the module, pick the fields, pick the grouping.

Schedule the reports you will actually re-read. SuiteCRM's schedulers can run saved reports and email the results, which closes the loop: the same cron entry that powers workflows delivers your Monday-morning numbers without you opening the app. If you are already running a finance workflow in Actual Budget, our Actual Budget beginner guide covers the other half of the small-business toolkit — SuiteCRM tracks the customers, Actual Budget tracks the money.

SuiteCRM vs HubSpot: Which Is Right for You?

SuiteCRM vs HubSpot is really the open source crm question versus the proprietary cloud question, and the suitecrm self hosted model is the whole pitch: your customers live in your database, on your server, under your control. HubSpot is the polished, hosted platform most beginners know; SuiteCRM is the CRM you install, own, and run yourself. Neither is "better" in the abstract — they are answers to different constraints.

Choose SuiteCRM when data ownership, unlimited seats, and zero software cost outweigh the maintenance burden. Choose a hosted platform when you would rather pay than patch. A small business that already self-hosts its website is usually in the first camp — and this suitecrm 8 tutorial just gave them the whole setup.

What Are the 7 Mistakes Beginners Make with SuiteCRM?

Most SuiteCRM installs fail for boring, documented reasons. All seven of these are avoidable, and the first two account for the overwhelming majority of "it doesn't work" forum threads.

Sources

1. SuiteCRM 8.x installation guide (downloading & installing, permissions, cron) — docs.suitecrm.com
2. SuiteCRM 7.x installation guide (permissions, crontab, license step) — docs.suitecrm.com
3. SuiteCRM 8.x schedulers administration (bin/console schedulers:run) — docs.suitecrm.com
4. SuiteCRM 8.10.2 & 7.15.2 release announcement, July 2026 — docs.suitecrm.com
5. Supported versions (7.15 ESR to December 2027) — docs.suitecrm.com
6. SuiteCRM 8.10 compatibility matrix (PHP 8.2/8.3/8.4, MariaDB 10.6–11.8, MySQL 8.0/8.4), via aliteq.com — checked October 2026
7. "SuiteCRM: The First Four Years" (SugarCRM fork lineage, 2013) — suitecrm.com
8. SuiteCRM — Wikipedia (fork of SugarCRM Community Edition, AGPL license)
9. SuiteCRM Assistant user guide (Convert Lead icon) — store.suitecrm.com
10. SuiteCRM community forum (lead conversion model) — community.suitecrm.com
11. SuiteCRM community forum (opportunity sales stages) — community.suitecrm.com
12. Advanced Open Workflow manual (workflow actions) — btactic.com
13. "Making the Most Out of Workflows in SuiteCRM" (On Save vs On Scheduler) — rtdynamic.com
14. "SuiteCRM: Revolutionising Your Workplace with SuiteCRM 8" (Angular + Symfony UI) — suitecrm.com
15. SuiteCRM review (free software, unlimited users, editable dropdowns) — crm.org

Frequently Asked Questions

Is SuiteCRM free?

Yes. SuiteCRM is free, open-source software under the AGPLv3: no license fees, no per-user seat charges, no upgrade prompts. You can onboard as many users as you want. The costs that exist are the ones you choose — hosting, support, and any third-party paid add-ons from store.suitecrm.com — never the software itself.

What is SuiteCRM, and how does it compare to SugarCRM?

SuiteCRM is a fork of the last open-source release of SugarCRM, created in 2013 when SugarCRM moved away from open source, and developed ever since as an independent project. It keeps the classic CRM module structure SugarCRM users know — leads, contacts, accounts, opportunities — with a modernized 8.x interface built on Angular and Symfony.

Should I start with SuiteCRM 7 or SuiteCRM 8?

Start with SuiteCRM 8. Version 8.10.x is the current line (8.10.2 at the time of writing), and 7.15 is an ESR maintenance line supported only until December 2027. The two are different install and UI eras — learn the current one unless you are maintaining an existing 7.x deployment.

Why do my workflows and emails not run in SuiteCRM?

Because the scheduler is not on a crontab. Workflows set to On Scheduler, email campaigns, and scheduled reports all wait on the "Process Workflow Tasks" job, which only runs when the cron entry exists: cron.php every minute on 7.x, or bin/console schedulers:run on 8.x, as the web server user. SuiteCRM never warns you that cron is missing — check Admin, then Schedulers, and confirm jobs are executing.

What is the Convert Lead icon in SuiteCRM?

On a lead record's detail view, lead records carry a special fifth action icon — the Convert Lead icon. Clicking it opens a create view where you build the associated Contact and Account from the lead (or attach the contact to an existing account), with the option to create an opportunity at the same time. Converting moves the lead out of the Leads list; its history follows the contact.