Frappe Manager on Windows + WSL 2

In this article we’ll cover:

1. Installing the prerequisites
2. Connecting Docker with WSL 2
3. Granting your user Docker permissions
4. Setting up a Python virtual environment
5. Installing and configuring Frappe Manager (fm)
6. Running your first site
7. Common pitfalls and quick fixes

Open a windows terminal and follow along.

---

1. Prerequisites – What You Need First

Component	Minimum version	How to obtain
Docker Desktop	4.30+ (latest stable)	https://www.docker.com/products/docker-desktop/
WSL 2 (Ubuntu)	22.04 LTS (or any 22.xx/23.xx)	wsl --install -d Ubuntu-22.04 (or follow Microsoft’s guide)
Python	3.10.x	sudo apt install python3.10 python3.10-venv python3-pip inside Ubuntu

Note for UK teams: Docker Desktop includes a Windows‑side license – verify that it complies with your organisation’s software‑licensing policy before installing.

---

2. Hook Docker into WSL 2

2.1 Verify WSL version

From PowerShell (or CMD) run:

wsl.exe -l -v

You should see something similar to:

NAME            STATE           VERSION
* Ubuntu-22.04  Running         2

If any distro shows Version 1, upgrade it:

wsl.exe --set-version Ubuntu-22.04 2

2.2 (Optional) Set a default distro

wsl.exe --set-default Ubuntu-22.04

2.3 Enable Docker‑WSL integration

1. Open Docker Desktop → Settings → Resources → WSL Integration.
2. Toggle the switch for your Ubuntu distro.
3. Click Apply & Restart.

2.4 Confirm the integration

Inside the Ubuntu shell (wsl), type:

docker version

Both Client and Server sections should appear without errors.

Reference: Docker’s official guide – https://docs.docker.com/desktop/features/wsl/

---

3. Grant Your Linux User Docker Permissions

Running Docker as root is insecure. Add your user to the docker group:

# Inside Ubuntu (WSL)
sudo usermod -aG docker $USER
newgrp docker   # applies the change immediately

Check the membership:

getent group docker
# Expected output: docker:x:1003:your_username

Further reading: https://www.geeksforgeeks.org/how-to-add-user-to-docker-group/

---

4. Prepare a Project Directory

mkdir ~/frappe-manager
cd ~/frappe-manager

Keeping the folder inside ~/ (your Linux home) avoids Windows‑path translation problems when Docker mounts volumes.

---

5. Create & Activate a Python Virtual Environment

python3.10 -m venv .venv      # creates a hidden .venv folder
source .venv/bin/activate     # Bash/Zsh – activates the venv

Upgrade pip and install Frappe Manager:

pip install --upgrade pip
pip install "frappe-manager"

Enable shell auto‑completion (optional but handy):

fm --install-completion
# Restart your terminal or run: source ~/.bashrc

---

6. Verify the Installation & Pull Docker Images

fm --version

• Current stable version (Nov 2025): 0.18.0 (or newer).
• If you see an older version, run:

fm self-update

Finally, pull the latest Docker images that fm depends on:

fm self update-images

---

7. Spin Up Your First Frappe Site

7.1 Create a site (local development)

fm create demo.localhost

Appending .localhost makes Docker’s internal DNS resolve the hostname automatically, so you can open https://demo.localhost in your browser without editing /etc/hosts.

7.2 Start the bench (the Docker containers)

fm bench start

You will see logs from MariaDB, Redis, Nginx‑proxy, and the Frappe web worker. When the logs settle, open the site:

https://demo.localhost

7.3 Open the code in VS Code (optional)

If you have VS Code installed on Windows with the Remote – WSL extension:

fm code

VS Code will open the bench folder directly inside WSL, giving you full IDE support.

---

8. Common Issues & Quick Fixes

Symptom	Likely cause	Quick fix
fm: command not found	Virtual environment not active	source .venv/bin/activate
Docker daemon not reachable	Docker not linked to the current WSL distro	Re‑enable WSL Integration in Docker Desktop and run docker version again
fm code opens an empty window	VS Code or Remote‑WSL extension missing	Install VS Code on Windows and add the Remote – WSL extension
Site disappears after creating a second bench	Default nginx‑proxy only forwards a single virtual host per port	Keep a single Frappe Manager instance per host, or expose each bench on a different port via custom compose files
“Permission denied” while pulling images	User not in docker group (or group change not applied)	Run newgrp docker or restart the WSL session
Need to share a site with a teammate on a different machine	Direct LAN access blocked by Windows firewall / Docker NAT	Use Tailscale (see next section) to create a secure mesh network

Making a Site Reachable via Tailscale (Semi‑Public)

1. Create the site with a full domain name

   fm create sales.mycompany.com
   

2. Add the FQDN to the host’s /etc/hosts

   sudo sh -c "echo '127.0.0.1 sales.mycompany.com' >> /etc/hosts"
   

3. Install & log in to Tailscale on both machines

   sudo apt install tailscale
   sudo tailscale up
   

4. Add the same FQDN to the client’s /etc/hosts, pointing at the host’s Tailscale IP (e.g., 100.101.102.103)

   sudo sh -c "echo '100.101.102.103 sales.mycompany.com' >> /etc/hosts"
   

5. https://sales.mycompany.com on the client – traffic is encrypted and routed over the Tailscale mesh.

GDPR note (UK): Tailscale traffic is end‑to‑end encrypted, but treat any personal data stored in the site according to the UK Data Protection Act 2018 and GDPR principles.

---

9. TL;DR – Cheat‑Sheet for Your Terminal

# Verify WSL version
wsl.exe -l -v

# (Optional) Set default distro
wsl.exe --set-default Ubuntu-22.04

# Add yourself to docker group
sudo usermod -aG docker $USER
newgrp docker

# Create project folder
mkdir ~/frappe-manager && cd ~/frappe-manager

# Python virtual environment
python3.10 -m venv .venv
source .venv/bin/activate

# Install fm
pip install --upgrade pip
pip install "frappe-manager"
fm --install-completion   # optional

# Verify / update
fm --version
fm self-update            # if version < 0.18.0
fm self update-images

# First site
fm create demo.localhost
fm bench start
fm code   # opens VS Code (if installed)

---

Where to Go From Here

Next step	Why it matters
Add the bench folder to Git	Keep custom apps version‑controlled
Store secrets in a vault (HashiCorp, Azure Key Vault, etc.)	Avoid plain‑text passwords on disk
Build a CI/CD pipeline (GitHub Actions, GitLab)	Run fm bench build in a Docker‑in‑Docker runner for automated testing
Explore Frappe apps	Start building your own ERP modules or integrate with existing SaaS services

---

Wrap‑Up

You now have a fully functional, Docker‑powered Frappe development environment running on Windows + WSL 2. The setup is repeatable, isolated, and ready for collaborative work (thanks to Tailscale).

If you have questions, spot an error, or want to share your experience, leave a comment below or reach out on the Dig1tal Slack channel.

Happy coding!