Sparkdock is an automated macOS development environment provisioner built with Ansible. It provides a consistent, reproducible setup for development workstations with containerized workflows and modern tooling.
GUI Applications:
- Docker Desktop, Google Chrome, Visual Studio Code
- iTerm2, Ghostty terminal, Slack, Zoom
- Maccy clipboard manager, MonitorControl
Development Tools:
- Languages: Node.js 20, PHP 8.2, Go, Python 3
- Version Control: Git with credential manager, GitHub CLI, GitLab CLI
- Cloud/Container: AWS CLI, Kubernetes CLI (kubectl), k9s, Docker credential helper
- Container Development: Kind, Kubectx, Skaffold, Stern
System Utilities:
- Shell Enhancement: Atuin (shell history), fzf (fuzzy finder), thefuck (command correction)
- Terminal Tools: tmux, tmate, watch, jq, jless
- System Info: fastfetch, mactop
- Fonts: Nerd Fonts (Droid Sans Mono, Inconsolata, Fira Code)
Integrated SparkFabrik HTTP Proxy providing:
- Automatic DNS resolution for
.locdomains - Local SSL certificates via mkcert
- Containerized reverse proxy with Traefik
- Monitoring dashboards (Grafana + Prometheus)
SparkJust (sjust) - Custom task runner with commands for:
- Docker management (start/stop containers, cleanup)
- HTTP proxy control
- System updates and maintenance
- Package management
bash <(curl -fsSL https://raw.githubusercontent.com/sparkfabrik/sparkdock/master/bin/install.macos)Operating System:
- macOS Sonoma (14.x) or Sequoia (15.x)
- Apple Silicon (M1/M2/M3) and Intel Macs supported
Hardware Requirements:
- At least 8GB RAM recommended (16GB for heavy development workloads)
- Minimum 10GB free disk space (20GB+ recommended for full development environment)
- Stable internet connection for package downloads
User Requirements:
- Administrator privileges (required for system-level configurations)
- Command line familiarity (basic terminal usage)
Network Requirements:
- Access to GitHub, Homebrew, and Docker Hub repositories
The installation process:
- System Prerequisites: Xcode Command Line Tools, Homebrew
- Base Tools: Git, curl, Python 3, Ansible
- Sparkdock Repository: Cloned to
/opt/sparkdock - Applications & Tools: All packages from the configuration
- HTTP Proxy System: Configured and ready to use
- Task Runner: sjust command available system-wide
- Update Service: Automatic update checking via launchd
Run the provisioner to configure your system:
sparkdockIf you have an existing Sparkdock installation and want to update to the new HTTP proxy system without running the full provisioner:
cd /opt/sparkdock
git switch master
git fetch && git reset --hard origin/master
make install-sjust
sjust http-proxy-install-updateThis workflow:
- Updates your Sparkdock repository to the latest version
- Installs the
sjusttask runner - Runs a targeted Ansible update to install the new HTTP proxy system
View and run available development tasks:
sjust # Show available commands
sjust --list # List all tasks
sjust docker-ps # Show running containers
sjust system-upgrade # Update system packages
sjust system-gcloud-reconfigure # Configure Google Cloud SDK and install gke-gcloud-auth-pluginSparkdock automatically installs and configures Google Cloud SDK during provisioning, including the gke-gcloud-auth-plugin component required for GKE authentication.
To manually reconfigure Google Cloud SDK:
sjust system-gcloud-reconfigureThis command will:
- Install Google Cloud SDK via Homebrew (if not present)
- Install the
gke-gcloud-auth-plugincomponent - Configure shell completion in your
.zshrc - Verify the installation
After configuration, you can verify the plugin is working:
gke-gcloud-auth-plugin --versionManage the local development proxy:
spark-http-proxy start # Start proxy services
spark-http-proxy stop # Stop proxy services
spark-http-proxy status # Check service statusSparkdock includes a native macOS menu bar application that provides quick access to system status and common tasks:
Features:
- Real-time system status with colored indicators
- Quick access to development tools and dashboards
- Battery-efficient event-driven updates
- Automatically starts at login via LaunchAgent
Control the menu bar app:
sjust menubar # Launch the menu bar app manuallyThe app is automatically installed as a LaunchAgent (com.sparkfabrik.sparkdock.menubar.plist) and starts at login. It shows update availability and provides one-click access to system updates and development tools.
/opt/sparkdock/
├── ansible/ # Ansible playbooks and inventory
├── bin/ # Main executables and utilities
├── sjust/ # SparkJust task runner
├── config/ # Configuration files and packages
└── http-proxy/ # HTTP proxy system (cloned)
- Custom Tasks: Add to
~/.config/sjust/100-custom.just - Package Lists: Modify
/opt/sparkdock/config/packages/all-packages.yml - System Settings: Edit Ansible playbooks in
/opt/sparkdock/ansible/
For detailed troubleshooting information, see our troubleshooting guide or visit the company playbook.
- Permission Errors: Ensure administrator privileges
- Docker Desktop Network Problems: Use
sjust docker-desktop-*commands for UDP and host networking issues - Update Failures: System automatically rolls back failed updates
- Lock File Issues: Remove
/tmp/sparkdock.lockif installation appears stuck - DNS Resolution: Use
sjust system-clear-dns-cacheto clear DNS cache - HTTP Proxy Issues: Use
sjust http-proxy-install-updateto restart proxy services
Contributions welcome! Areas of interest:
- Support for additional operating systems
- New development tools and configurations
- Bug fixes and improvements
- Shell Scripts: Use
set -euo pipefailand pass shellcheck - Ansible: Idempotent tasks with proper error handling
- Just Tasks: Well-documented and focused
Licensed under the GNU General Public License v3.0 - see LICENSE for details.
Maintained by SparkFabrik's development team.
Send PRs, open issues, and embrace containerized development!