Geo Extension

Enhancing the Address Experience in Frappe

---

Overview

Geo Extension is a lightweight Frappe app that enhances the frappe Geo module by improving how users encode and manage address information.
It extends the Address Doctype to make primary address keys (like State, City, and County) filterable and interactive — turning tedious address input into a smooth, guided process.

With country-specific manifests and hierarchical data levels, users can select from real administrative divisions instead of typing free-form text, drastically reducing data entry errors.

---

Motivation

Encoding addresses in ERPNext or any Frappe app can be repetitive and error-prone — especially for data-heavy workflows like customer registration, delivery setup, or supplier profiling.
Geo Extension simplifies this process by making address encoding filtered, intuitive, and contextual.

This project was also a personal challenge: to build something useful and shareable with the Frappe Community, demonstrating how modular extensions can improve user experience within the framework.

---

Key Features

🔍 Smart Address Fields

• Auto-adapting fields (State/City/County) based on country
• Turns free-text fields into searchable dropdowns
• Uses real administrative divisions encoded and validated by the community

⚙️ Zero-Friction Setup

• Country configurations via simple JSON manifests
• Works with existing Frappe Address doctype
• Automatic fallback to standard fields if no country data

---

Supported Countries

• 🇮🇳 India
• 🇵🇭 Philippines

Want to add your country? See the Contribute section below.

---

Production Setup

Managed Hosting

You can try Frappe Cloud — a simple, open-source, and developer-friendly platform to host Frappe apps with peace of mind.

It handles installation, setup, upgrades, monitoring, maintenance, and support of your deployments. It’s a fully featured developer platform for managing multiple Frappe instances.

---

Self-Hosting

Follow these steps to set up Geo Extension in production:

Step 1: Download the easy install script

wget https://frappe.io/easy-install.py

Step 2: Run the deployment command

python3 ./easy-install.py deploy \
    --project=geo_extension_prod_setup \
    --email=your_email.example.com \
    --image=ghcr.io/sudopotito/geo_extension\
    --version=stable \
    --app=geo_extension \
    --sitename subdomain.domain.tld

Replace the following parameters with your own:

• your_email.example.com: Your email address
• subdomain.domain.tld: Your target domain

The script will spin up a production-ready instance of Geo Extension with all configurations.

---

Development Setup

Using Docker

You’ll need Docker, docker-compose, and git installed.
Refer to Docker’s documentation if needed.

Step 1: Prepare the folder and download setup files

mkdir geo_extension
cd geo_extension

# Download the docker-compose file
wget -O docker-compose.yml https://raw.githubusercontent.com/sudopotito/geo_extension/develop/docker/docker-compose.yml

# Download the setup script
wget -O init.sh https://raw.githubusercontent.com/sudopotito/geo_extension/develop/docker/init.sh

Step 2: Run and daemonize the container

docker compose up -d

Step 3: Access your site

Visit: http://geo_extension.localhost:8000

Default credentials:

Username: Administrator
Password: admin

---

Bare Metal

1. Install bench and set up a frappe-bench directory
   → Installation Steps
2. Start the server

   bench start

3. Create a new site

   bench new-site geo_extension.localhost

4. Map to localhost

   bench --site geo_extension.localhost add-to-hosts

5. Download the app

   bench get-app https://github.com/sudopotito/geo_extension

6. Install the app

   bench --site geo_extension.localhost install-app geo_extension

7. Open the app in your browser
   → http://geo_extension.localhost:8000

---

Contribute

We welcome contributions from the community!
Whether you’re adding support for a new country or fixing something small — your help makes Geo Extension better for everyone.

Adding a New Country

If you want to contribute support for a new country, follow this guide:
👉 How to Add a New Country

Even if your country already exists, you can still contribute updates, corrections, or extended datasets via a Pull Request (PR).

General Fixes or Improvements

For general bug fixes, optimizations, or documentation updates —
you can directly open a PR. All contributions are reviewed and appreciated!

Your contribution helps make address encoding smoother and more reliable across the Frappe ecosystem.

---

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).