diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 000000000..57a1e73c7
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,199 @@
+# Guake Docker Setup
+
+Since Guake is a Linux GTK application, Docker provides the cleanest way to test and run it on macOS.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- For GUI testing: XQuartz (macOS) or X11 server (Linux)
+
+## Quick Start
+
+### 1. Build the Docker Image
+```bash
+docker build -t guake:dev -f Dockerfile.dev .
+```
+
+### 2. Using Docker Compose (Recommended)
+```bash
+docker-compose -f docker-compose.dev.yml up
+
+# In another terminal, connect to the container:
+docker exec -it guake-dev /bin/bash
+```
+
+### 3. Manual Docker Run
+
+#### Linux Users:
+```bash
+docker run -it --rm \
+  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+  -e DISPLAY=$DISPLAY \
+  -v ${PWD}:/guake:rw \
+  guake:dev /bin/bash
+```
+
+#### macOS Users:
+
+First, install and start XQuartz:
+```bash
+brew install xquartz
+open -a XQuartz
+```
+
+Configure X11 to accept connections from Docker:
+```bash
+defaults write org.macosforge.xquartz.X11 nolisten_tcp -boolean false
+pkill -9 Xvfb; true
+```
+
+Then run Docker:
+```bash
+docker run -it --rm \
+  -e DISPLAY=host.docker.internal:0 \
+  -v ${PWD}:/guake:rw \
+  guake:dev /bin/bash
+```
+
+Or use socat tunnel:
+```bash
+# Terminal 1: Start socat
+brew install socat
+socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CONNECT:/tmp/.X11-unix/0 &
+
+# Terminal 2: Run Docker
+docker run -it --rm \
+  -e DISPLAY=host.docker.internal:0 \
+  -v ${PWD}:/guake:rw \
+  guake:dev /bin/bash
+```
+
+## Inside the Container
+
+### Setup (if not already done)
+```bash
+cd /guake
+make dev
+sudo make install-schemas
+```
+
+### Run Tests
+```bash
+make test
+make test-coverage
+```
+
+### Check Code Quality
+```bash
+make style
+make check
+```
+
+### Run Guake GUI
+```bash
+guake &
+```
+
+### Build Distribution
+```bash
+make build
+```
+
+### Access Python Shell
+```bash
+pipenv shell
+python3 -c "import guake; print(guake.__version__)"
+```
+
+## Image Details
+
+The `Dockerfile.dev` includes:
+
+- **Base:** Ubuntu 22.04 LTS
+- **GTK:** GTK 3.0 with VTE terminal widget
+- **Tools:** Python 3, pipenv, git, build essentials
+- **Locale:** Full locale support
+- **D-Bus:** For system communication
+- **Development:** All headers and dev libraries
+
+## Common Issues
+
+### "Cannot connect to X server"
+- **Linux:** Make sure `/tmp/.X11-unix` exists and is accessible
+- **macOS:** Ensure XQuartz is running and X11 forwarding is configured
+
+### "No module named 'gi' (GObject introspection)"
+The Dockerfile includes all necessary GObject introspection bindings. If still missing:
+```bash
+apt-get update && apt-get install -y python3-gi gir1.2-gtk-3.0 gir1.2-vte-2.91
+```
+
+### "dbus-launch cannot be run setuid"
+This is normal in Docker. DBus operations should still work. Run:
+```bash
+export DBUS_SYSTEM_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket
+```
+
+### "Permission denied" errors
+The container runs as root by default. For safer operation, modify the Dockerfile to create a non-root user.
+
+## Customization
+
+### Use Different Python Version
+```bash
+docker build -t guake:py39 --build-arg PYTHON_VERSION=3.9 -f Dockerfile.dev .
+```
+
+### Add More Tools to Container
+Edit `Dockerfile.dev` and add to the `apt-get install` command.
+
+### Persistent Container
+```bash
+docker run -d --name guake-dev \
+  -e DISPLAY=$DISPLAY \
+  -v ${PWD}:/guake:rw \
+  guake:dev sleep infinity
+
+# Connect whenever needed:
+docker exec -it guake-dev /bin/bash
+```
+
+## Integration with macOS Development
+
+### Mount Local Code
+```bash
+docker run -it --rm \
+  -v ~/Documents/GitHub/guake:/guake:rw \
+  guake:dev /bin/bash
+```
+
+### Use IDE on macOS, Test in Docker
+1. Edit code in VS Code/PyCharm on macOS
+2. Run tests in Docker:
+```bash
+docker exec -it guake-dev make test
+```
+
+### Access Built Packages from macOS
+```bash
+docker run -it --rm \
+  -v ${PWD}/dist:/guake/dist \
+  guake:dev bash -c "make build && ls -la dist/"
+```
+
+## Performance Notes
+
+- First build: ~5 minutes (downloads and installs dependencies)
+- Subsequent runs: < 1 second (cached layers)
+- Image size: ~1.5 GB
+- Container size: ~500 MB when running
+
+## Resources
+
+- Docker documentation: https://docs.docker.com/
+- XQuartz (macOS): https://www.xquartz.org/
+- GTK3 documentation: https://developer.gnome.org/gtk3/
+
+---
+
+For general development setup, see [SETUP_DEV.md](SETUP_DEV.md)
diff --git a/Dockerfile.dev b/Dockerfile.dev
new file mode 100644
index 000000000..11e4118bb
--- /dev/null
+++ b/Dockerfile.dev
@@ -0,0 +1,73 @@
+FROM ubuntu:22.04
+
+LABEL maintainer="guake"
+LABEL description="Guake Terminal Development Container"
+
+# Prevent interactive prompts during installation
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    # Build tools
+    build-essential \
+    python3-dev \
+    python3-pip \
+    git \
+    # GTK and UI libraries
+    libgtk-3-0 \
+    libgtk-3-dev \
+    libvte-2.91-0 \
+    libvte-2.91-dev \
+    libkeybinder-3.0-0 \
+    libkeybinder-3-dev \
+    # Gettext for translations
+    gettext \
+    # D-Bus for communication
+    dbus \
+    # X11 and display
+    libx11-dev \
+    x11-apps \
+    x11-utils \
+    # Additional utilities
+    curl \
+    wget \
+    vim \
+    less \
+    # Required for GObject introspection
+    gir1.2-gtk-3.0 \
+    gir1.2-vte-2.91 \
+    gir1.2-glib-2.0 \
+    libglib2.0-dev \
+    # GLib schemas
+    dconf-gsettings-backend \
+    gsettings-desktop-schemas \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+RUN pip install --upgrade pip setuptools wheel && \
+    pip install pipenv
+
+# Create app directory
+WORKDIR /guake
+
+# Copy project files
+COPY . .
+
+# Setup development environment
+RUN make dev && \
+    make prepare-install && \
+    make install-schemas
+
+# Create X11 socket directory
+RUN mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix
+
+# Set up entrypoint
+RUN chmod +x /guake/scripts/run-local.sh
+
+ENV PATH="/root/.local/bin:${PATH}"
+
+# Default command - enter shell
+CMD ["/bin/bash"]
+
+# To run Guake, use: guake &
diff --git a/QUICKSTART.md b/QUICKSTART.md
new file mode 100644
index 000000000..80e399767
--- /dev/null
+++ b/QUICKSTART.md
@@ -0,0 +1,165 @@
+# Guake Quick Start Guide
+
+## 🚀 One-Command Setup
+
+### Option 1: Automated Setup (Recommended)
+```bash
+cd ~/Documents/GitHub/guake
+./scripts/setup-dev.sh
+```
+
+### Option 2: Manual Setup
+```bash
+cd ~/Documents/GitHub/guake
+
+# Install dependencies
+pip install pipenv
+make dev
+
+# Install schemas (required even for local dev)
+sudo make install-schemas
+
+# Done! Now you can run tests or build
+```
+
+## 📦 Running & Testing
+
+### Run Tests
+```bash
+make test
+```
+
+### Run in Development Mode (requires X11/Linux)
+```bash
+make run
+```
+
+### Build Distribution Packages
+```bash
+make build
+```
+
+### Code Quality Checks
+```bash
+make style      # All style checks (black, flake8, pylint)
+make black      # Auto-format code
+```
+
+## 🐳 Docker Setup (Easiest for GUI Testing)
+
+### Build Docker Image
+```bash
+docker build -t guake:dev -f Dockerfile.dev .
+```
+
+### Run with Docker Compose
+```bash
+docker-compose -f docker-compose.dev.yml up
+```
+
+### Or Run Manually
+```bash
+# Linux with X11
+docker run -it --rm \
+  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+  -e DISPLAY=$DISPLAY \
+  guake:dev /bin/bash
+
+# Inside container:
+guake &
+```
+
+## 📋 Common Tasks
+
+### Install in editable mode
+```bash
+pip install -e .
+```
+
+### Run specific tests
+```bash
+make test  # Run all tests
+pytest guake/tests/test_boxes.py  # Run specific test file
+```
+
+### Format code
+```bash
+make black
+```
+
+### Check for errors (no formatting)
+```bash
+make black-check
+make flake8
+make pylint
+```
+
+### Clean everything
+```bash
+make clean
+```
+
+### Uninstall from system
+```bash
+sudo make uninstall
+```
+
+## 🔧 Troubleshooting
+
+### Pipenv lock issues
+```bash
+make clean
+make dev PYTHON_INTERPRETER=python3
+```
+
+### "Permission denied" on schema installation
+```bash
+# Make sure you use sudo
+sudo make install-schemas
+```
+
+### Docker can't find display
+```bash
+# First, make sure X11 socket exists:
+ls /tmp/.X11-unix/
+
+# Then run docker with DISPLAY variable
+docker run -e DISPLAY=$DISPLAY guake:dev
+```
+
+## 📚 More Information
+
+- Full setup guide: [SETUP_DEV.md](SETUP_DEV.md)
+- Contributing guidelines: [docs/source/contributing/](docs/source/contributing/)
+- Issue tracker: https://github.com/guake/guake/issues
+
+## 🎯 Project Layout
+
+```
+guake/
+├── guake/              # Main source code
+│   ├── __init__.py
+│   ├── callbacks.py
+│   ├── boxes.py
+│   └── ...
+├── guake/data/         # UI definitions, images, schemas
+├── po/                 # Translations
+├── scripts/            # Helper scripts
+├── tests/              # Test suite
+├── Makefile            # Build commands
+├── setup.py            # Package setup
+└── Dockerfile.dev      # Docker image definition
+```
+
+## ✅ Quick Health Check
+
+```bash
+# Verify setup is working:
+python3 -c "import guake; print('✓ Guake imports successfully')"
+make test  # Should pass
+make style # Should have no errors
+```
+
+---
+
+**Next**: Run `./scripts/setup-dev.sh` to get started!
diff --git a/SETUP_DEV.md b/SETUP_DEV.md
new file mode 100644
index 000000000..74d8e7aa6
--- /dev/null
+++ b/SETUP_DEV.md
@@ -0,0 +1,161 @@
+# Guake Development Setup Guide
+
+## Quick Start
+
+### 1. Development Environment (macOS)
+
+While Guake runs on Linux with GTK/VTE, you can set up the development environment on macOS for contribution and testing:
+
+```bash
+cd ~/Documents/GitHub/guake
+
+# Install Python dependencies
+pip install pipenv
+make dev
+
+# Prepare for local execution
+sudo make install-schemas
+
+# Run tests
+make test
+
+# Build distribution
+make build
+```
+
+### 2. Docker Setup (Recommended for Testing/Running)
+
+Build and run Guake in a Linux container:
+
+```bash
+# Build the Docker image
+docker build -t guake:dev -f Dockerfile.dev .
+
+# Run Guake in container with X11 forwarding (Linux/Mac with XQuartz)
+docker run -it --rm \
+  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+  -e DISPLAY=$DISPLAY \
+  guake:dev
+
+# Or use Docker Compose for easier setup
+docker-compose -f docker-compose.dev.yml up
+```
+
+## Installation Details
+
+### macOS Development
+
+**Prerequisites:**
+- Python 3.6+
+- pipenv
+- For system-wide installation: sudo
+
+**Steps:**
+
+1. **Install dependencies via pipenv:**
+   ```bash
+   make dev
+   ```
+   This handles all Python dependencies automatically.
+
+2. **Install GTK schemas (required even for local dev):**
+   ```bash
+   sudo make install-schemas
+   ```
+
+3. **Run without installation (dev mode):**
+   ```bash
+   make run
+   ```
+
+4. **Or install system-wide:**
+   ```bash
+   make dev && make && sudo make install
+   ```
+
+### Available Make Targets
+
+| Target | Purpose |
+|--------|---------|
+| `make dev` | Setup complete dev environment |
+| `make run` | Run Guake in development mode |
+| `make test` | Run test suite |
+| `make build` | Build distribution packages |
+| `make style` | Run code style checks (black, flake8) |
+| `make clean` | Clean all generated files |
+| `make install` | Install system-wide (requires sudo) |
+| `make uninstall` | Remove system installation |
+
+### Docker Setup
+
+Guake in Docker provides a clean Linux environment for testing.
+
+**Quick start:**
+```bash
+docker build -t guake:dev -f Dockerfile.dev .
+docker run -it --rm guake:dev /bin/bash
+guake &  # Run in background
+```
+
+## Development Workflow
+
+1. **Code changes:**
+   ```bash
+   # Edit files in ~/Documents/GitHub/guake/guake/
+   ```
+
+2. **Test changes:**
+   ```bash
+   make test          # Run unit tests
+   make style         # Check code style
+   make run           # Test GUI (requires X11 forwarding)
+   ```
+
+3. **Build distributions:**
+   ```bash
+   make build         # Creates wheel and sdist
+   ```
+
+## Troubleshooting
+
+### Pipenv issues
+```bash
+# Clear and reinstall
+make clean
+make dev PYTHON_INTERPRETER=python3
+```
+
+### Schema compilation errors
+```bash
+# Reinstall schemas
+sudo make uninstall-schemas
+sudo make install-schemas
+```
+
+### Docker display issues (macOS)
+```bash
+# Install XQuartz first, then run with socat tunnel
+brew install socat
+socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CONNECT:/tmp/.X11-unix/0 &
+docker run -e DISPLAY=host.docker.internal:0 guake:dev
+```
+
+## Project Structure
+
+```
+guake/
+├── guake/              # Main source code
+├── po/                 # Translations
+├── docs/               # Documentation
+├── scripts/            # Helper scripts
+├── Makefile            # Build automation
+├── setup.py            # Python package setup
+├── Dockerfile.dev      # Development container
+└── docker-compose.dev.yml  # Docker Compose config
+```
+
+## Resources
+
+- **Documentation:** `docs/source/contributing/dev_env.rst`
+- **GitHub:** https://github.com/guake/guake
+- **Issue Tracker:** https://github.com/guake/guake/issues
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 000000000..3621932f8
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,33 @@
+version: '3.8'
+
+services:
+  guake:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    image: guake:dev
+    container_name: guake-dev
+
+    # Enable interactive terminal
+    stdin_open: true
+    tty: true
+
+    # Mount X11 socket for display (Linux)
+    volumes:
+      - /tmp/.X11-unix:/tmp/.X11-unix:rw
+      - ${PWD}:/guake:rw
+      - /etc/localtime:/etc/localtime:ro
+
+    # Set display for X11 forwarding
+    environment:
+      - DISPLAY=${DISPLAY}
+      - PYTHONUNBUFFERED=1
+
+    # Allow running GUI applications
+    network_mode: "host"
+
+    # Keep container running
+    command: /bin/bash
+
+    # Run as root for now (can be restricted later)
+    # user: guake
diff --git a/scripts/setup-dev.sh b/scripts/setup-dev.sh
new file mode 100755
index 000000000..7f0c751e5
--- /dev/null
+++ b/scripts/setup-dev.sh
@@ -0,0 +1,97 @@
+#!/bin/bash
+set -e
+
+# Guake Development Setup Script
+# This script automates the setup of the development environment
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+echo "================================================"
+echo "Guake Development Environment Setup"
+echo "================================================"
+echo ""
+
+# Detect OS
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    OS="macos"
+    echo "Detected macOS"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    OS="linux"
+    echo "Detected Linux"
+else
+    echo "Unsupported OS: $OSTYPE"
+    exit 1
+fi
+
+# Check Python
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 not found. Please install Python 3.6+"
+    exit 1
+fi
+echo "✓ Python 3 found: $(python3 --version)"
+
+# Check pipenv
+if ! command -v pipenv &> /dev/null; then
+    echo "⚠️  pipenv not found. Installing..."
+    pip3 install pipenv
+fi
+echo "✓ pipenv found: $(pipenv --version)"
+
+# Change to project directory
+cd "$PROJECT_ROOT"
+
+# Setup development environment
+echo ""
+echo "Installing dependencies..."
+make dev
+
+echo ""
+echo "Preparing installation..."
+make prepare-install
+
+# Handle schema installation
+echo ""
+echo "Installing GTK schemas..."
+if [[ "$OS" == "macos" ]]; then
+    # macOS might need sudo
+    if sudo -n true 2>/dev/null; then
+        sudo make install-schemas
+    else
+        echo "⚠️  Schema installation requires sudo"
+        echo "Run: sudo make install-schemas"
+    fi
+else
+    # Linux
+    if [ "$EUID" -eq 0 ]; then
+        make install-schemas
+    else
+        echo "⚠️  Schema installation requires sudo"
+        echo "Run: sudo make install-schemas"
+    fi
+fi
+
+echo ""
+echo "================================================"
+echo "✓ Development setup complete!"
+echo "================================================"
+echo ""
+echo "Next steps:"
+echo ""
+echo "1. Run tests:"
+echo "   make test"
+echo ""
+echo "2. Check code style:"
+echo "   make style"
+echo ""
+echo "3. Build distribution:"
+echo "   make build"
+echo ""
+echo "4. Run locally (Linux/X11 required):"
+echo "   make run"
+echo ""
+echo "5. Docker setup (recommended for testing):"
+echo "   docker build -t guake:dev -f Dockerfile.dev ."
+echo "   docker-compose -f docker-compose.dev.yml up"
+echo ""
+echo "For more details, see SETUP_DEV.md"