Setup Frappe on Mac

Create below directory

$cd /var/www;
$mkdir frappe_crm;
$cd frappe_crm;
$python3.9 -m venv willow
$source willow/bin/activate
$pip install --upgrade pip
$pip install frappe-bench

#yarn is dependency to initialize frappe-bench
brew install yarn

Check the Frappe-bench version installed

$bench --version
WARN: Command not being executed in bench directory

Let’s create our project folder which will contain our apps and sites. Run the following command:

bench init frappe-bench

This will create a directory named frappe-bench in your current working directory. It will do the following:

  • Create a python virtual environment under env directory.
  • Fetch and install the frappe app as a python package.
  • Install node modules of frappe.
  • Build static assets.

Directory Structure

├── Procfile
├── apps
│   └── frappe
├── config
│   ├── pids
│   ├── redis_cache.conf
│   ├── redis_queue.conf
│   └── redis_socketio.conf
├── env
│   ├── bin
│   ├── include
│   ├── lib
│   └── share
├── logs
│   ├── backup.log
│   └── bench.log
└── sites
    ├── apps.txt
    ├── assets
    └── common_site_config.json
  • env: Python virtual environment
  • config: Config files for Redis and Nginx
  • logs: Log files for every process (web, worker)
  • sites: Sites directory
  • assets: Static assets that served via Nginx in production
    • apps.txt: List of installed frappe apps
    • commonsiteconfig.json: Site config that is available in all sites
  • apps: Apps directory
  • frappe: The Frappe app directory
  • Procfile: List of processes that run in development

Create a new site

We have to run below command

bench new-site library.test

but there were few issues on existing mysql installations, so follow below steps before running above command

#if you need backup of ur existing databases take backup before this step
brew services stop mysql
brew cleanup
rm -fr /usr/local/var/mysql
#search for all old mysql files and remove them
brew install mariadb
brew postinstall mariadb
brew install --cask wkhtmltopdf
brew start mariadb
brew stop mariadb

Once mariadb is installed, add below lines to existing content of /usr/local/etc/my.cnf

character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

default-character-set = utf8mb4

Once done start mariadb again with below command

brew start mariadb

Now let’s Create a new site

We have to run below command

$bench new-site library.test
MySQL root password:

Installing frappe...
Updating DocTypes for frappe        : [========================================] 100%
Updating country info               : [========================================] 100%
Set Administrator password:
Re-enter Administrator password:
*** Scheduler is disabled ***
Current Site set to library.test

This command will create a new database, so you need to enter your MySQL root password. It will also ask to set the password for the Administrator user, just set a password that you won’t forget. This will be useful later.

Now, you will have a new folder named library.test in the sites directory.

The site dir structure will be as below

├── locks
├── logs
├── private
│   ├── backups
│   └── files
├── public
│   └── files
├── site_config.json
└── task-logs

8 directories, 1 file

As you can see, the private folder will contain any database backups and private files. Private files are user uploaded files that need authentication to be accessible.

The public folder will contain files that are accessible without authentication. This can contain website images that should be accessible without login.

The site_config.json file contains configuration that is specific to this site which should not be version controlled. This is similar to an environment variables file. If you look at the contents of the file, it contains the database configuration values for this site.

 "db_name": "_adxxxxxxxxxxx",
 "db_password": "pzxxxxxxxxx"
 "db_type": "mariadb"

Now, that we have created our first site, we can access it on http://localhost:8000 in our browser.

However, bench allows you to create multiple sites and access them separately in the browser on the same port. This is what we call multi-tenancy support in bench.

To achieve that, we must disable the serving of the default site. Go back to your terminal and delete the file sites/currentsite.txt from the frappe-bench directory.

rm sites/currentsite.txt

Now, you won’t be able to access your site on http://localhost:8000.

Frappe will identify which site to serve by matching the hostname of the request with the site name, so you should be able to access your site on http://library.test:8000 but this won’t work because we have to tell our operating system that library.test should point to localhost. To do that, you can add the following entry to your /etc/hosts file.

sudo vi /etc/hosts

#copy below line in the file and save it library.test

This will map library.test to localhost. Bench has a convenient command to do just that.

bench --site library.test add-to-hosts

This will ask for your root password and will add an entry to your /etc/hosts file.

Great, now you can access your site at http://library.test:8000. Congratulations for making it this far.

Install app on site

To install our Library Management app on our site, run the following command:

$ bench --site library.test install-app library_management

Installing library_management...

To confirm if the app was installed, run the following command:

$ bench --site library.test list-apps

You should see frappe and library_management as installed apps on your site.

When you create a new site, the frappe app is installed by default.

Login to desk

To create DocTypes in our app, we must log in to Desk. Go to http://library.test:8000 and it should show you a login page.

Enter Administrator as the user and password that you set while creating the site.

After successful login, you will see the setup wizard. This is a one-time setup wizard used to set up the site. Go ahead, select your country and complete the wizard.

comments powered by Disqus