Setup Script Improvements

Date: November 26, 2025
Category: Development
Status: Active

Overview

Enhancements to bin/setup for better Docker and Ruby gem management during development environment setup.

New Features

1. Docker Compose Management

The setup script now manages Docker services automatically:

# Take down existing cluster
docker compose down --remove-orphans

# Pull latest base images
docker compose pull --ignore-pull-failures

# Rebuild custom images (no cache)
docker compose build --pull --no-cache

# Clean up stale images
docker image prune -f
docker image prune -a -f --filter "until=168h"  # Images > 7 days
docker builder prune -f --filter "until=168h"   # Build cache > 7 days

# Start services
docker compose up -d

Why this helps:

Ensures fresh Docker images on setup
Cleans up disk space from old images
Prevents stale container issues

2. Ruby Gem Cleanup

Forces fresh native extension rebuilds when Homebrew updates libraries:

# Clean all installed gems (except bundler)
gem list --no-versions | grep -v '^bundler$' | while read gem_name; do
  gem uninstall "$gem_name" --all --ignore-dependencies --executables
done

# Clear gem cache
rm -rf "${GEM_HOME_DIR}/cache"/*
rm -rf "${GEM_HOME_DIR}/build_info"/*

# Reinstall
bundle install

Why this helps:

Homebrew updates can break native extensions
Gems like pg, nokogiri, puma link against system libraries
Fresh bundle install rebuilds extensions against current libraries

Commonly affected gems:

Gem	Links Against
`pg`	libpq (PostgreSQL)
`mysql2`	libmysqlclient
`nokogiri`	libxml2, libxslt
`ruby-vips`	libvips
`puma`	OpenSSL
`bcrypt`	OpenSSL
`ffi`	libffi

Script Location

bin/setup

Running the Setup

bin/setup

What the Script Does (in order)

✅ Ensure Homebrew dependencies (brew bundle)
✅ NEW: Docker Compose - reset, upgrade, rebuild
✅ Setup mkcert for local HTTPS
✅ Ensure oh-my-zsh installed
✅ Install/update mise
✅ Install tools from .mise.toml
✅ Configure Yarn via Corepack
✅ NEW: Clean installed gems
✅ Configure Bundler credentials
✅ Run bundle install
✅ Run yarn install
✅ Build webpack assets

Skipping Docker Management

If Docker or docker-compose.yml is not found, the script skips container management gracefully:

ℹ️  Docker not found or no docker-compose.yml, skipping container setup

Error Handling

All Docker commands use || true to prevent script failure:

Network issues don't break setup
Missing images are handled gracefully
Build failures are logged but don't stop setup

Manual Docker Commands

If you need to run Docker commands manually:

# Start services
docker compose up -d

# Rebuild specific service
docker compose build --no-cache pg

# View logs
docker compose logs -f pg

# Stop all services
docker compose down