7 Frappe Docker Development Setup (with MSSQL ODBC)

Because spending 20 minutes setting up once is better than spending 2 hours wondering why the container hates you.

Note

Step-by-step guide to set up a Frappe development environment using Docker with MSSQL ODBC driver integration.

Prerequisites

Before you begin, make sure you have the following installed:

Docker Desktop
Visual Studio Code
Docker extension for VS Code (recommended)
Dev Containers extension for VS Code
Git

Official Resources

Frappe Docker: https://github.com/frappe/frappe_docker

Docker Desktop: https://www.docker.com/products/docker-desktop/

VS Code: https://code.visualstudio.com/

Docker Extension: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

Dev Containers Extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

Step 1: Clone the Repository

Navigate to the folder where you want to keep the source code.

git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker/
cp -R devcontainer-example .devcontainer
cp -R development/vscode-example development/.vscode
touch .devcontainer/Dockerfile.mssql-odbc

Step 2: Create the MSSQL ODBC Dockerfile

Create and open:

.devcontainer/Dockerfile.mssql-odbc

Paste the following content.

# Use the original frappe/bench image as base
FROM docker.io/frappe/bench:latest

# Switch to root to perform installations
USER root

# Install necessary dependencies
RUN apt-get update && apt-get install -y \
  curl \
  gnupg \
  apt-transport-https \
  lsb-release \
  wget

# Import Microsoft GPG key
RUN curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg || true

# Add Microsoft repository
RUN echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > /etc/apt/sources.list.d/mssql-release.list

# Install MSSQL ODBC Driver
RUN apt-get update && \
  ACCEPT_EULA=Y apt-get install -y msodbcsql17 mssql-tools unixodbc-dev && \
  apt-get clean && \
  rm -rf /var/lib/apt/lists/*

# Additional ODBC packages
RUN apt-get update && apt-get install -y \
  unixodbc \
  libodbc1 \
  odbcinst1debian2

# Switch back to frappe user
USER frappe

Step 3: Build the Custom Docker Image

You can build the image using either the terminal or VS Code.

Option 1 — Terminal

docker build -t frappe-mssql:latest -f .devcontainer/Dockerfile.mssql-odbc .

Option 2 — VS Code (Recommended)

If you're using VS Code with the Docker extension installed:

Open the Docker view.
Right-click .devcontainer/Dockerfile.mssql-odbc.
Select Build Image...
Choose the project root (frappe_docker) as the build context.
Enter the image name:

frappe-mssql:latest

Alternatively, press Ctrl + Shift + P and run Docker: Build Image.

Note: Make sure Docker Desktop is running before building the image.

☕ Grab a coffee while Docker builds the image. Depending on your internet speed, this may take a few minutes.

Step 4: Update Docker Compose

Open:

.devcontainer/docker-compose.yml

Expose MariaDB Port

Add the following under the mariadb service:

ports:
  - 3307:3306

Replace the Bench Image

Replace:

image: docker.io/frappe/bench:latest

with:

image: frappe-mssql:latest

Step 5: (Optional) Change Development Ports

If you want to use ports other than the defaults (8000–8005 or 9000–9005), update them in both:

.devcontainer/docker-compose.yml
.devcontainer/devcontainer.json

Remember: Changing it in only one file is a great way to confuse Future You.

Step 6: Open the Project in a Dev Container

Open the frappe_docker folder in VS Code.

Press Ctrl + Shift + P and choose:

Dev Containers: Open Folder in Container

Select the frappe_docker folder.

The first launch will take several minutes while Docker builds and starts the containers.

Step 7: Configure Apps

Open:

development/apps-example.json

Add the apps required for your project.

Step 8: Install Frappe

Inside the Dev Container Terminal, run:

cd development/
python3 installer.py --frappe-branch=version-15

The installer will automatically:

Create the Bench
Download required apps
Configure services
Create the site
Complete the development setup

⏳ Expected setup time: 15–20 minutes.

Now sit back, relax, and pretend you're reading the logs... we all know you're checking Slack or Reddit. 😄

🛠️ Version 14 Fix

If you're installing Version 14 and get:

Error: No such option: --mariadb-user-host-login-scope

Open:

development/installer.py

Comment out the line containing:

--mariadb-user-host-login-scope=%

Then rerun:

python3 installer.py --frappe-branch=version-14

✅ Quick Checklist

Docker Desktop installed
VS Code installed
Docker extension installed
Dev Containers extension installed
Cloned frappe_docker
Created Dockerfile.mssql-odbc
Built custom Docker image
Updated docker-compose.yml
(Optional) Changed development ports
Opened project inside Dev Container
Added required apps
Ran installer
Frappe development environment is ready 🎉

📚 Useful Links

Frappe Docker — https://github.com/frappe/frappe_docker
Frappe Framework Docs — https://frappeframework.com/docs
Docker Docs — https://docs.docker.com/
Docker Desktop — https://www.docker.com/products/docker-desktop/
Visual Studio Code — https://code.visualstudio.com/
Docker Extension — https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker
Dev Containers Extension — https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

Happy coding! If Docker decides to rebuild everything for absolutely no reason... well, that's just Docker keeping life interesting. 😄