Skip to main content

How to Create a Site in Frappe Framework (Version 15)

Introduction — Understanding Frappe Sites

In the Frappe Framework, a Site represents an independent environment that holds all your app data, configurations, users, and database connections. Each site operates as a separate entity with its own database and configuration files but can share a common codebase under a single Bench instance.

Creating a site is the first step before installing ERPNext or any other custom Frappe app. In this guide, you’ll learn how to create a new site using the bench new-site command in Frappe Framework v15, configure your database, and set administrator credentials — all based on the latest version 15 architecture.

Prerequisites for Creating a Site in Frappe v15

Before creating a site, ensure your environment is properly configured.

System Requirements

  • Python: 3.10 or laterNode.js: 18.x or later
  • Redis: 6.x or later
  • MariaDB: 10.6 or later
  • Yarn: package manager
  • Bench CLI: Installed globally

If not installed, refer to the Frappe Bench installation guide before proceeding.

Ensure You Have:

  • Bench installed globally (pip install frappe-bench)
  • A Frappe environment initialized (e.g., /frappe-bench)
  • Database credentials ready
  • Required ports open (default: 8000)

Step-by-Step Guide to Create a New Site

1. Navigate to Your Bench Directory

Open your terminal and navigate to the Frappe Bench directory where you want to create your new site.

cd frappe-bench

Each site you create will reside under this directory inside the /sites folder.

2. Run the bench new-site Command

Use the following command to create a new site:

bench new-site site-name.localhost

Replace site-name.localhost with your preferred site name (for example, erp.goerpnext.localhost).

3. Configure Database Settings

During site creation, you’ll be prompted for MySQL/MariaDB root password. This is required for Frappe to create a new database for the site.

You will also need to:

  • Set an Administrator password
  • Choose the database host (default: localhost)
  • Confirm if you want to install sample data (optional)

Once complete, Bench automatically:

  • Creates a new database (e.g., _site-name_)
  • Adds the database user credentials
  • Updates the site_config.json file
  • Installs default apps (like Frappe Framework core)

4. Setting the Administrator Password

When prompted, you must set the Administrator password.
This will be your login credential for accessing the Desk UI at

http://site-name.localhost:8000.

You can also reset this later using:

bench --site site-name.localhost set-admin-password newpassword

5. Verify Site Creation

Once the command completes, verify your new site exists by listing the sites directory:

ls sites/

You should see your newly created site folder, e.g., site-name.localhost.

To confirm it’s working, add the site to your hosts file (Linux/Mac):

sudo nano /etc/hosts

Add this line at the end:

127.0.0.1 site-name.localhost

Now start the server:

bench start

Visit http://site-name.localhost:8000 in your browser — you’ll see the Frappe login screen.

Understanding site_config.json

Each site has a configuration file located at:

/sites/site-name.localhost/site_config.json

Example:

{
"db_name": "site_name_localhost",
"db_password": "securepassword123",
"db_type": "mariadb",
"db_host": "localhost",
"db_port": 3306,
"developer_mode": 1
}

You can manually edit this file to adjust site-level configurations such as:

  • Database credentials
  • Developer mode
  • Installed apps
  • Email or Redis settings

 

Installing Apps on the Site

Once your site is created, you can install apps (like ERPNext) on it:

bench --site site-name.localhost install-app erpnext

To verify installed apps:

bench --site site-name.localhost list-apps

Common Issues & Troubleshooting

Access Denied for User ‘root’@‘localhost

Cause: Incorrect MariaDB root credentials.

Solution: Log into MariaDB manually:

mysql -u root -p

Check if the frappe database user exists:

SELECT user, host FROM mysql.user;

If missing, create it manually:

CREATE USER 'frappe'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON *.* TO 'frappe'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Port Already in Use

Cause: Another process (often an existing Bench process) is running on port 8000.

Solution: Stop other instances using:

sudo lsof -i :8000
sudo kill -9 <PID>

Then restart:

bench start

Could not connect to Redis

Ensure Redis is running:

sudo systemctl start redis
sudo systemctl enable redis

Best Practices for Multi-Site Management

Frappe allows hosting multiple sites on the same Bench instance.
To manage multiple sites efficiently:

  • Use bench use sitename to switch between sites
  • Use a common apps folder to share installed apps
  • Keep Procfile and redis.conf configurations standardized
  • For production, use NGINX configuration to map domains to sites
  • Use supervisor or systemd for process management

Example of multiple sites under /sites:

/sites/
├── common_site_config.json
├── site1.localhost/
├── site2.localhost/

Cross-References and Related Topics

FAQs:

What is a Frappe Site?

A Frappe site is an independent environment that contains all the data, configurations, and user accounts for an application built on the Frappe Framework.

How do I create a new site in Frappe?

Use the command:

bench new-site site-name.localhost

and follow the prompts for database and administrator setup.

Where is site configuration stored?

Each site’s configuration is stored in:

/sites/site-name.localhost/site_config.json

Can I create multiple sites in one Bench?

Yes. You can create multiple sites under a single Bench directory and manage them using bench use sitename.

Click to rate this post!
[Total: 1 Average: 5]

© 2025 | goERPNext | All rights reserved