Frappe Frameworkbash

How to Set Up a New Site with DNS Multitenancy in Frappe Framework

DNS based Multitenancy (New Site)

A complete guide to adding a new site to your Frappe/ERPNext instance using DNS-based multitenancy, from enabling the configuration to deploying ERPNext.

DNS-based multitenancy is a powerful feature of the Frappe Framework that allows you to host multiple, independent sites on a single server instance. Each site is accessed via its own domain name (e.g., `client-a.com`, `client-b.com`), while sharing the same underlying Frappe and ERPNext installation. This is the standard and most efficient way to manage multiple production sites.

This guide provides the complete sequence of `bench` commands required to enable DNS multitenancy, create a new site, configure the web server (Nginx), and install applications like ERPNext onto the new site.

bash
Official Frappe Bench Wiki
# Switch ON DNS Multitenant
bench config dns_multitenant on

# Create New Site (e.g., demo.yourcompany.com)
bench new-site demo.yourcompany.com

# Re-generate nginx config to include the new site
bench setup nginx

# Reload nginx to apply changes
sudo service nginx reload

# New site has only Frappe, Install ERPNext on the new site if required
bench --site demo.yourcompany.com install-app erpnext

# If the site was accidentally set up, use this to reinstall (Warning: Deletes data)
bench --site demo.yourcompany.com --force reinstall

# Enable the scheduler for background jobs on the new site
bench --site demo.yourcompany.com enable-scheduler

# For removing a site from multitenancy
bench drop-site demo.yourcompany.com

Understanding This Code

What It Does

This series of commands configures a Frappe Bench instance for DNS-based multitenancy and adds a new, production-ready site that is accessible via its domain name.

When To Use

Use these commands when you need to host multiple, separate Frappe or ERPNext instances on a single server, with each site accessible through a unique domain or subdomain.

Prerequisites

  • •A working Frappe Bench installation on a server.
  • •DNS records for your new site domain pointing to the server's IP address.
  • •Root or sudo access to the server for managing Nginx.

Key Concepts

Important ideas to understand in this code

DNS Multitenancy

This configuration in `common_site_config.json` tells the Frappe request handler to identify which site to serve based on the hostname in the incoming HTTP request. This is essential for production hosting of multiple sites.

Learn more

Bench CLI

The `bench` command-line interface is the primary tool for managing a Frappe installation. It handles everything from creating sites and installing apps to managing server processes and running updates.

Learn more

Nginx Configuration

Frappe Bench automatically generates Nginx configuration files for each site. The `bench setup nginx` command creates the necessary server blocks to proxy requests to the correct Frappe process.

Learn more

Step-by-Step Tutorial

Follow along to understand how this code works

1

Enable DNS Multitenancy

This is the first and most crucial step. This command modifies the `common_site_config.json` file in your bench directory, adding the setting `"dns_multitenant": true`. This tells the bench to look at the domain name of a request to determine which site's database and assets to use.

bash
bench config dns_multitenant on
Next Step
2

Create the New Site

This command creates a new folder in the `sites` directory with the same name as your domain. It also creates a new database and a configuration file for the site. It is critical that the site name here exactly matches the domain you will use to access it.

bash
bench new-site your.domain.com
Next Step
3

Update and Reload Web Server

After creating the site, you need to update the Nginx configuration. `bench setup nginx` generates the required config file for your new site. `sudo service nginx reload` applies these new changes without dropping existing connections.

bash
bench setup nginx
sudo service nginx reload
Next Step
4

Install Applications

A new site only contains the Frappe framework by default. To add functionality like ERPNext, you must explicitly install the app on the specific site using the `--site` flag.

bash
bench --site your.domain.com install-app erpnext
Next Step
5

Enable Background Jobs

The scheduler handles critical background tasks like sending emails, processing auto-repeating documents, and running scheduled reports. It must be enabled for each site to ensure full functionality.

bash
bench --site your.domain.com enable-scheduler

Common Issues & Solutions

Troubleshoot problems you might encounter