From 913583afcb04354c0a5b80e994fa61b2feba6d40 Mon Sep 17 00:00:00 2001
From: Rophy Tsai <rophy@users.noreply.github.com>
Date: Sun, 11 Jan 2026 22:34:30 +0000
Subject: [PATCH] build: add dev container for local development

Add IDE compatible dev container setup for
easier local development and testing.

Files added:
- .devcontainer/Dockerfile: Build environment based on upstream
  docker-images/build-ubuntu24, with mariadb-client added for testing
- .devcontainer/docker-compose.yaml: Dev container + MariaDB service
- .devcontainer/devcontainer.json: IDE configuration

Usage with IDE: https://containers.dev/

Usage with docker compose:
  docker compose -f .devcontainer/docker-compose.yaml up -d
  docker compose -f .devcontainer/docker-compose.yaml exec dev make

The MariaDB service is available at hostname "mariadb" for testing.
---
 .devcontainer/Dockerfile          | 58 +++++++++++++++++++++++++++++++
 .devcontainer/devcontainer.json   | 15 ++++++++
 .devcontainer/docker-compose.yaml | 18 ++++++++++
 CONTRIBUTING.md                   | 28 +++++++++++++--
 4 files changed, 117 insertions(+), 2 deletions(-)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/devcontainer.json
 create mode 100644 .devcontainer/docker-compose.yaml

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000000..7af1e6b5b8
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,58 @@
+# Development container for ProxySQL
+# Based on: https://github.com/ProxySQL/docker-images/blob/main/build-images/build-ubuntu24/Dockerfile
+
+FROM ubuntu:24.04
+LABEL authors="Miro Stauder <miro@sysown.com>"
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt update && \
+	apt full-upgrade -y
+
+# gcc & build tools
+RUN apt install -y \
+	make cmake automake bison flex \
+	git wget \
+	gcc g++ \
+	libtool \
+	gdb gdbserver \
+	equivs \
+	python3 \
+	zstd \
+	pkg-config \
+	sudo
+
+# proxysql build dependencies
+RUN apt install -y \
+	libssl-dev gnutls-dev libgnutls28-dev \
+	libmysqlclient-dev \
+	libunwind8 libunwind-dev \
+	uuid-dev \
+	libncurses-dev \
+	libicu-dev \
+	libevent-dev \
+	libtirpc-dev
+
+# debug images need valgrind
+RUN apt install -y \
+	valgrind
+
+# mysql client for testing
+RUN apt install -y \
+	mariadb-client
+
+# clean apt cache
+RUN apt clean && \
+	rm -rf /var/cache/apt/* && \
+	rm -rf /var/lib/apt/lists/*
+
+# fetch needed include
+RUN wget -q -O /usr/include/mysql/hash.h https://raw.githubusercontent.com/mysql/mysql-server/5.7/include/hash.h
+
+# configure git safe dir
+RUN git config --global --add safe.directory '*'
+
+ENV CC=gcc
+ENV CXX=g++
+
+RUN ${CXX} --version
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000000..7573a40527
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,15 @@
+{
+  "name": "ProxySQL Development",
+  "dockerComposeFile": "docker-compose.yaml",
+  "service": "dev",
+  "workspaceFolder": "/proxysql",
+  "shutdownAction": "stopCompose",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-vscode.cpptools",
+        "ms-vscode.cmake-tools"
+      ]
+    }
+  }
+}
diff --git a/.devcontainer/docker-compose.yaml b/.devcontainer/docker-compose.yaml
new file mode 100644
index 0000000000..3c2741ff96
--- /dev/null
+++ b/.devcontainer/docker-compose.yaml
@@ -0,0 +1,18 @@
+services:
+  dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - ..:/proxysql:cached
+    working_dir: /proxysql
+    init: true
+    command: sleep infinity
+
+  mariadb:
+    image: mariadb:11.4
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: testdb
+    ports:
+      - "3306:3306"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 88744e7e92..e2a6eb897b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,7 +16,31 @@ Reference issues: When fixing bugs or implementing requested features, mention t
 
 ## Development Setup
 
-ProxySQL provides Docker build images for development. The required packages for building are listed in the Dockerfiles at: https://github.com/ProxySQL/docker-images/tree/main/build-images
+### Using Dev Container (Recommended)
+
+The easiest way to set up a development environment is using the included [dev container](https://containers.dev/):
+
+**With a compatible IDE:**
+
+Many IDEs support dev containers natively or via extensions. Simply open the repository and follow your IDE's prompts to reopen in the container.
+
+**With Docker Compose:**
+```bash
+# Start the dev container and MariaDB
+docker compose -f .devcontainer/docker-compose.yaml up -d
+
+# Go into dev container shell
+docker compose -f .devcontainer/docker-compose.yaml exec dev bash
+
+# Build ProxySQL
+make
+```
+
+The MariaDB service is available at hostname `mariadb` for testing.
+
+### Manual Setup
+
+If you prefer to set up your environment manually, the required packages for building are listed in the Dockerfiles at: https://github.com/ProxySQL/docker-images/tree/main/build-images
 
 For example, to see packages needed for Ubuntu 24.04, check: https://github.com/ProxySQL/docker-images/blob/main/build-images/build-ubuntu24/Dockerfile
 
@@ -100,4 +124,4 @@ By contributing to ProxySQL, you agree that your contributions will be licensed
 
 ---
 
-Thank you for helping make ProxySQL better!
\ No newline at end of file
+Thank you for helping make ProxySQL better!