Bench CLIbash

How to Rename a Frappe or ERPNext Site using Bench CLI

Change Site Name

Learn the step-by-step process to safely change your Frappe or ERPNext site name (e.g., from site1.local) using essential Bench CLI commands like \`bench setup nginx\`.

When managing a Frappe or ERPNext instance, a common administrative task is renaming a site. This is often necessary when moving from a development environment with a default name like `site1.local` to a production environment with a custom domain. The process involves more than just renaming a folder; it requires updating web server configurations and internal Frappe settings to ensure the site remains accessible and functional.

This guide provides a comprehensive set of shell commands to perform this operation safely using the Bench Command Line Interface (CLI). Following these steps carefully will prevent common issues like '502 Bad Gateway' errors or scheduler failures.

bash
Original ERPNext Forum Discussion
1# Step 1: Rename the site's folder manually
2# Replace 'oldname.local' and 'newname.com' with your actual site names.
3mv /home/ubuntu/frappe-bench/sites/oldname.local /home/ubuntu/frappe-bench/sites/newname.com
4

5# Step 2: Navigate back to the main bench directory
6cd /home/ubuntu/frappe-bench/
7

8# Step 3: Regenerate Nginx configuration for the new site name
9bench setup nginx
10

11# Step 4: Reload Nginx to apply the new configuration
12sudo service nginx reload
13# On systems using systemd, you might use:
14# sudo systemctl restart nginx
15

16# Step 5: Update the 'currentsite.txt' to point to the new site
17# Open the file /home/ubuntu/frappe-bench/sites/currentsite.txt
18# And change the content from 'oldname.local' to 'newname.com'
19

20# Step 6: Re-enable the scheduler for the new site
21bench --site newname.com enable-scheduler

Understanding This Code

What It Does

This series of commands renames a Frappe site's directory, regenerates the necessary Nginx web server configuration, updates the current site pointer, and restarts the scheduler to reflect the new site name.

When To Use

Use this procedure when you need to change the domain name of an existing Frappe or ERPNext site, for example, when moving from a default development name like \`site1.local\` to a custom production domain.

Prerequisites

  • •Shell access (SSH) to the server hosting the Frappe instance.
  • •Sudo or root privileges for restarting services like Nginx.
  • •The Frappe Bench CLI must be installed and accessible in your server's PATH.

Key Concepts

Important ideas to understand in this code

Bench CLI

The Bench Command Line Interface is the primary tool for creating, managing, and updating Frappe and ERPNext sites. Commands like `bench setup nginx` and `bench --site` are essential for system administration.

Learn more

Site Naming & Resolution

Frappe Framework uses a multi-tenant architecture where each site is represented by a folder inside the `/sites` directory. The folder name must match the domain name you intend to use for that site.

Learn more

currentsite.txt

This file, located in the `/sites` directory, tells Bench which site to use by default if the `--site` flag is not specified in a command. It must be updated manually after renaming a site.

Learn more

Step-by-Step Tutorial

Follow along to understand how this code works

1

Rename the Site Directory

The first step is to rename the actual directory containing your site's data. Use the standard Linux `mv` command. Make sure you are in the parent directory of `frappe-bench` or provide the full paths.

bash
mv /home/ubuntu/frappe-bench/sites/site1.local /home/ubuntu/frappe-bench/sites/demo.finbyz.in
Next Step
2

Regenerate Nginx Configuration

Navigate to your `frappe-bench` directory. The `bench setup nginx` command will detect the change in the `/sites` directory and generate a new Nginx server block configuration for your new domain name.

bash
cd /home/ubuntu/frappe-bench/
bench setup nginx
Next Step
3

Apply the New Web Server Configuration

For Nginx to recognize the new configuration, you must reload its service. This command applies the changes without dropping existing connections.

bash
sudo service nginx reload
Next Step
4

Update the Default Site Pointer

Edit the `sites/currentsite.txt` file and replace the old site name with the new one. This ensures that bench commands run without the `--site` flag target the correct, renamed site.

bash
# Open sites/currentsite.txt with a text editor (like nano or vim)
# Change 'site1.local' to 'demo.finbyz.in' and save the file.
Next Step
5

Re-enable the Scheduler

The scheduler (which handles background jobs, emails, etc.) is tied to the site name. You must enable it for the new site name to ensure background processes continue to run correctly.

bash
bench --site demo.finbyz.in enable-scheduler

Common Issues & Solutions

Troubleshoot problems you might encounter