Export Frappe Settings from Development to Production

Migrating setting data like HR Settings, Payroll Settings, or any other configurations in Frappe from your local development server to the production server is a common requirement. Settings are crucial because they define how your HRMS or ERP modules behave in production.

This guide covers two simple methods to export any Frappe "Single" DocType setting and import it safely to your production environment.

📌 What is a Single DocType Setting?

In Frappe, configuration documents like HR Settings, Payroll Settings, or Leave Settings are designed as Single DocTypes. This means:

• They have only one record.
• They control application behavior.
• You can't create multiple records under SINGLE DocTypes.

Hence, migrating these requires exporting the single record data properly.

🚀 Method 1: Export and Import Using export-json

✅ Step 1: Export the Setting from Development

Navigate to your bench folder and run:

bench --site your-site-name export-json "HR Settings" ./custom_hr_settings.json

Replace HR Settings with any settings DocType you want to export (e.g., Payroll Settings).

This command will create a file named custom_hr_settings.json in your current directory.

✅ Explanation of the syntax:

bench export-json [DOCTYPE] [OUTPUT FILE PATH]

• HR Settings → the DocType you want to export
• ./custom_custom_hr_settings.json → the file path where the JSON will be saved

✅ Step 2: Transfer the JSON File to Production

Either manually transfer the json file to production server or, Use SCP, rsync, or any file transfer method:

scp custom_hr_settings.json user@production-server:/path/to/your/bench/folder/

✅ Step 3: Import the Setting into Production

SSH into your production server, navigate to the bench folder, and run:

bench --site your-production-site import-doc "HR Settings" ./custom_hr_settings.json

✅ Your production HR Settings will be updated instantly.

🔨 Method 2: Use Fixtures for Version-Controlled Migration

If the setting is something you might need to deploy regularly, you can add it to your fixtures.

✅ Step 1: Define the Fixture in hooks.py

fixtures = [
    {"dt": "HR Settings"}
]

✅ Step 2: Export the Fixture

bench export-fixtures

This will generate HR Settings.json inside your app's fixtures/ folder.

✅ Step 3: Deploy and Migrate

Push the fixture to production and run:

bench migrate

✅ This method is ideal for apps that are version-controlled and have continuous deployment.

⚠️ Common Mistakes to Avoid

• Forgetting to specify the site name with --site during export/import.
• Not committing fixture changes to your repository.
• Failing to run bench migrate after deploying fixtures.