Sparkdock

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.

Features

Applications & Tools

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:

• Modern Shell Tools: eza (ls), fd (find), ripgrep (grep), bat (cat), zoxide (cd)
• 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)

HTTP Proxy System

Integrated SparkFabrik HTTP Proxy providing:

• Automatic DNS resolution for .loc domains
• Local SSL certificates via mkcert
• Containerized reverse proxy with Traefik
• Monitoring dashboards (Grafana + Prometheus)

Task Automation

SparkJust (sjust) - Custom task runner with commands for:

• Docker management (start/stop containers, cleanup)
• HTTP proxy control
• System updates and maintenance
• Package management

Installation

Quick Install

bash <(curl -fsSL https://raw.githubusercontent.com/sparkfabrik/sparkdock/master/bin/install.macos)

System Requirements

Operating System:

• macOS Sequoia (15.x) or macOS Tahoe (26.x)
• Apple Silicon only

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

What Gets Installed

The installation process:

1. System Prerequisites: Xcode Command Line Tools, Homebrew
2. Base Tools: Git, curl, Python 3, Ansible
3. Sparkdock Repository: Cloned to /opt/sparkdock
4. Applications & Tools: All packages from the configuration
5. HTTP Proxy System: Configured and ready to use
6. Task Runner: sjust command available system-wide
7. Update Service: Automatic update checking via launchd

Usage

Main Command

Run the provisioner to configure your system:

sparkdock

Upgrade Sparkdock

To update an existing Sparkdock installation, either re-run the full provisioner or use the dedicated SparkJust task:

sparkdock
# or
cd /opt/sparkdock
sjust sparkdock-upgrade

sjust sparkdock-upgrade refreshes the repository, ensures SparkJust is installed, and applies the latest configuration updates (including the HTTP proxy system).

SparkJust Task Runner

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-plugin

Google Cloud SDK Configuration

Sparkdock 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-reconfigure

This command will:

• Install Google Cloud SDK via Homebrew (if not present)
• Install the gke-gcloud-auth-plugin component
• Configure shell completion in your .zshrc
• Verify the installation

After configuration, you can verify the plugin is working:

gke-gcloud-auth-plugin --version

Sparkdock AI Assistant (Preview)

Sparkdock includes an experimental sparkdock-ai helper built with llm, OpenAI models, and gum. It lets you ask interactive questions about your local Sparkdock checkout (for example: “What packages are installed?” or “What aliases are defined?”).

Before launching it, export an OPENAI_API_KEY with the internal key material (ping Sparkdock internal support — e.g. #support-tech on Slack — if you need retrieval instructions). One approach is to define an export_openai_key helper in ${HOME}/.config/spark/shell.zsh that reads the secret from Google Cloud and exports it for your shell session.

Run it from the repository root or /opt/sparkdock:

bin/sparkdock-ai

On first launch, the script removes any legacy GitHub Copilot plugin, wipes stored llm keys, and verifies that OPENAI_API_KEY is present. Answers cite the relevant files so you can follow up directly in the repo.

The assistant calls the fast OpenAI gpt-4.1-nano model for contextual answers and gpt-5-nano for quick direct responses. During long-running calls the CLI shows a gum spin progress indicator, and it falls back to plain text messaging if gum is unavailable.

Pick “Help” in the menu at any time to read a quick overview of how the assistant works, including the classifier/direct-answer flow diagram.

Logs live at ~/.config/spark/sparkdock/ai.log. Set SPARKDOCK_AI_LOG_LEVEL=TRACE for verbose tracing or SPARKDOCK_AI_LOG_FILE to override the destination.

Shell Enhancements

Sparkdock provides a modern shell experience with oh-my-zsh, starship prompt, and a curated set of modern Unix tools with convenient aliases.

Setup:

sjust shell-omz-setup           # Install oh-my-zsh and zsh plugins
sjust shell-omz-update-plugins  # Update oh-my-zsh plugins
sjust shell-enable              # Add Sparkdock config to your ~/.zshrc

Discover Available Tools & Aliases:

Sparkdock includes modern replacements for traditional Unix tools (like eza, fd, ripgrep, bat, fzf, zoxide) along with helpful aliases and shell enhancements. To see what's available:

sjust shell-info         # View detected shell configuration and the exact zshrc snippet

Commands:

sjust shell-info         # Summarize current shell settings and Sparkdock defaults
sjust shell-disable      # Remove from ~/.zshrc

Defaults applied by sjust shell-enable:

• SPARKDOCK_ENABLE_STARSHIP=1 (Starship prompt ON)
• SPARKDOCK_ENABLE_FZF=1 (fzf fuzzy finder ON)
• SPARKDOCK_ENABLE_ATUIN=0 (Atuin history sync OFF)

Set these variables before sourcing Sparkdock if you prefer different defaults.

Customization:

Create ~/.config/spark/shell.zsh for personal customizations — Sparkdock sources it after its own defaults so it’s the safe place for aliases, exports, and tweaks.

HTTP Proxy

Manage the local development proxy:

spark-http-proxy start   # Start proxy services
spark-http-proxy stop    # Stop proxy services
spark-http-proxy status  # Check service status

Menu Bar App

Sparkdock 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 manually

The 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.

Configuration

Directory Structure

/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)

Customization

• 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/

Troubleshooting

For detailed troubleshooting information, see our troubleshooting guide or visit the company playbook.

If you are still blocked after trying the steps above:

• Reach out on Slack in #sparkdock-support with a short summary plus any relevant logs (for example ~/.config/spark/sparkdock/ai.log).
• Or open an issue on the Sparkdock repository so the team can track the fix.

Common Issues

• 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.lock if installation appears stuck
• DNS Resolution: Use sjust system-clear-dns-cache to clear DNS cache
• HTTP Proxy Issues: Use sjust http-proxy-install-update to restart proxy services

Development

Contributing

Contributions welcome! Areas of interest:

• Support for additional operating systems
• New development tools and configurations
• Bug fixes and improvements

Project Standards

• Shell Scripts: Use set -euo pipefail and pass shellcheck
• Ansible: Idempotent tasks with proper error handling
• Just Tasks: Well-documented and focused

License

Licensed under the GNU General Public License v3.0 - see LICENSE for details.

Maintainers

Maintained by SparkFabrik's development team.

Send PRs, open issues, and embrace containerized development!