Hip

Hip (Handy Infrastructure Provisioner) - A CLI dev-tool for streamlined Docker and Kubernetes workflows.

Forked from bibendi/dip and renamed for easier one-handed typing (한손으로 칠 수 있도록).

Hip is a CLI dev-tool that provides native-like interaction with a Dockerized application. It gives the feeling that you are working without using complex commands to run containers.

Original project by Evil Martians:

Presentations and examples

Local development with Docker containers
Dockerized Ruby on Rails application
Dockerized Node.js application: one, two
Dockerized Ruby gem
Dockerizing Ruby and Rails development
Reusable development containers with Docker Compose and Hip

📚 Configuration Examples

Check out our comprehensive examples covering various use cases:

Basic Setup - Perfect for beginners starting with Rails
Full-Stack Application - Rails + Node.js production setup
Kubernetes - K8s development environment with kubectl runner
Node.js - Node.js/Express projects with MongoDB
Provision Profiles - Advanced automation patterns
Module System - Modular configurations for large projects

See examples/README.md for detailed documentation and usage instructions.

Installation

⚠️ Important: gem install hip installs a different gem (hostname resolver). See INSTALL.md for correct installation methods.

Quick Install (Git):

# Using Bundler (recommended)
bundle add hip --git https://github.com/ScriptonBasestar/hip.git

# Or using specific_install
gem install specific_install
gem specific_install https://github.com/ScriptonBasestar/hip.git

Other installation methods:

GitHub Packages - See INSTALL.md
GitHub Releases - See INSTALL.md
Local build - See INSTALL.md

📖 See INSTALL.md for detailed installation guide.

Shell Completions

Hip provides intelligent tab completion for bash and zsh shells. Completions automatically discover all commands (static, dynamic, and subcommands) using hip manifest.

Installation:

# Bash - Add to ~/.bashrc
source /path/to/hip/completions/hip.bash

# Zsh - Add to ~/.zshrc (before compinit)
fpath=(/path/to/hip/completions $fpath)
autoload -Uz compinit && compinit

Features:

Complete all Hip commands and options
Discover dynamic commands from hip.yml
Context-aware completions
Cached for performance (60-minute TTL)

📖 See completions/README.md for detailed setup and troubleshooting.

Integration with shell

Hip can be injected into the current shell (ZSH or Bash).

eval "$(hip console)"

IMPORTANT: Beware of possible collisions with local tools. One particular example is supporting both local and Docker frontend build tools, such as Yarn. If you want some developer to run yarn locally and other to use Docker for that, you should either avoid adding the yarn command to the hip.yml or avoid using the shell integration for hybrid development.

After that we can type commands without hip prefix. For example:

<run-command> *any-args
compose *any-compose-arg
up <service>
ktl *any-kubectl-arg
provision

When we change the current directory, all shell aliases will be automatically removed. But when we enter back into a directory with a hip.yml file, then shell aliases will be renewed.

Also, in shell mode Hip is trying to determine manually passed environment variables. For example:

VERSION=20180515103400 rails db:migrate:down

You could add this eval at the end of your ~/.zshrc, or ~/.bashrc, or ~/.bash_profile. After that, it will be automatically applied when you open your preferred terminal.

Usage

hip --help
hip SUBCOMMAND --help

hip.yml

The configuration is loaded from hip.yml file. It may be located in a working directory, or it will be found in the nearest parent directory up to the file system root. If nearby places hip.override.yml file, it will be merged into the main config.

Also, in some cases, you may want to change the default config path by providing an environment variable HIP_FILE.

Below is an example of a real config. Config file reference will be written soon. Also, you can check out examples at the top.

# Required minimum hip version
version: '9.0.0'

# Load environment variables from .env files
# Supports multiple files, priority control, and variable interpolation
env_file:
  - .env.defaults    # Team defaults (committed)
  - .env             # Secrets (git-ignored)
  - .env.local       # Local overrides (git-ignored)

# Or simple form:
# env_file: .env

environment:
  COMPOSE_EXT: development
  STAGE: "staging"

compose:
  files:
    - docker/docker-compose.yml
    - docker/docker-compose.$COMPOSE_EXT.yml
    - docker/docker-compose.$HIP_OS.yml
  project_name: bear

kubectl:
  namespace: rocket-$STAGE

interaction:
  shell:
    description: Open the Bash shell in app's container
    service: app
    command: bash
    compose:
      run_options: [no-deps]

  bundle:
    description: Run Bundler commands
    service: app
    command: bundle

  rake:
    description: Run Rake commands
    service: app
    command: bundle exec rake

  rspec:
    description: Run Rspec commands
    service: app
    environment:
      RAILS_ENV: test
    command: bundle exec rspec

  rails:
    description: Run Rails commands
    service: app
    command: bundle exec rails
    subcommands:
      s:
        description: Run Rails server at http://localhost:3000
        service: web
        compose:
          run_options: [service-ports, use-aliases]

  stack:
    description: Run full stack (server, workers, etc.)
    runner: docker_compose
    compose:
      profiles: [web, workers]

  sidekiq:
    description: Run sidekiq in background
    service: worker
    compose:
      method: up
      run_options: [detach]

  psql:
    description: Run Postgres psql console
    service: app
    default_args: db_dev
    command: psql -h pg -U postgres

  k:
    description: Run commands in Kubernetes cluster
    pod: svc/rocket-app:app-container
    entrypoint: /env-entrypoint
    subcommands:
      bash:
        description: Get a shell to the running container
        command: /bin/bash
      rails:
        description: Run Rails commands
        command: bundle exec rails
      kafka-topics:
        description: Manage Kafka topics
        pod: svc/rocket-kafka
        command: kafka-topics.sh --zookeeper zookeeper:2181

  setup_key:
    description: Copy key
    service: app
    command: cp `pwd`/config/key.pem /root/keys/
    shell: false # you can disable shell interpolations on the host machine and send the command as is

  clean_cache:
    description: Delete cache files on the host machine
    command: rm -rf $(pwd)/tmp/cache/*

provision:
  - hip compose down --volumes
  - hip clean_cache
  - hip compose up -d pg redis
  - hip bash -c ./bin/setup

Predefined environment variables

$HIP_OS

Current OS architecture (e.g. linux, darwin, freebsd, and so on). Sometime it may be useful to have one common docker-compose.yml and OS-dependent Compose configs.

$HIP_WORK_DIR_REL_PATH

Relative path from the current directory to the nearest directory where a Hip config is found. It is useful when you need to mount a specific local directory to a container along with ability to change its working dir. For example:

- project_root
  |- hip.yml (1)
  |- docker-compose.yml (2)
  |- sub-project-dir
     |- your current directory is here <<<

# hip.yml (1)
environment:
  WORK_DIR: /app/${HIP_WORK_DIR_REL_PATH}

# docker-compose.yml (2)
services:
  app:
    working_dir: ${WORK_DIR:-/app}

cd sub-project-dir
hip run bash -c pwd

returned is /app/sub-project-dir.

$HIP_CURRENT_USER

Exposes the current user ID (UID). It is useful when you need to run a container with the same user as the host machine. For example:

# hip.yml (1)
environment:
  UID: ${HIP_CURRENT_USER}

# docker-compose.yml (2)
services:
  app:
    image: ruby
    user: ${UID:-1000}

The container will run using the same user ID as your host machine.

Modules

Modules are defined as array in modules section of hip.yml, modules are stored in .hip subdirectory of hip.yml directory.

The main purpose of modules is to improve maintainability for a group of projects. Imagine having multiple gems which are managed with hip, each of them has the same commands, so to change one command in hip you need to update all gems individualy.

With modules you can define a group of modules for hip.

For example having setup as this:

# ./hip.yml
modules:
 - sasts
 - rails

...

# ./.hip/sasts.yml
interaction:
  brakeman:
    description: Check brakeman sast
    command: docker run ...

# ./.hip/rails.yml
interaction:
  annotate:
    description: Run annotate command
    service: backend
    command: bundle exec annotate

Will be expanded to:

# resultant configuration
interaction:
  brakeman:
    description: Check brakeman sast
    command: docker run ...
  annotate:
    description: Run annotate command
    service: backend
    command: bundle exec annotate

Imagine .hip to be a submodule so it can be managed only in one place.

If you want to override module command, you can redefine it in hip.yml

# ./hip.yml
modules:
 - sasts

interaction:
  brakeman:
    description: Check brakeman sast
    command: docker run another-image ...

# ./.hip/sasts.yml
interaction:
  brakeman:
    description: Check brakeman sast
    command: docker run some-image ...

Will be expanded to:

# resultant configuration
interaction:
  brakeman:
    description: Check brakeman sast
    command: docker run another-image ...

Nested modules are not supported.

hip run

Run commands defined within the interaction section of hip.yml

A command will be executed by specified runner. Hip has three types of them:

docker compose runner — used when the service option is defined.
kubectl runner — used when the pod option is defined.
local runner — used when the previous ones are not defined.

hip run rails c
hip run rake db:migrate

Also, run argument can be omitted

hip rake db:migrate

Options

--explain, -e - Show execution plan without running the command:

hip run --explain rails c
hip rails c --explain          # Also works with shorthand syntax

Output example:

=== Command Execution Plan ===
Command: bundle exec rails console
Description: Run Rails console
Runner: DockerComposeRunner
Service: app
Compose Method: run
Shell Mode: true

--publish, -p - Publish container port(s) to host:

hip run -p 3000:3000 bundle exec rackup config.ru

Environment Variables

You can pass in custom environment variables into a container:

hip VERSION=12352452 rake db:rollback

You can also override docker compose command by passing HIP_COMPOSE_COMMAND if you wish. For example if you want to use mutagen-compose run HIP_COMPOSE_COMMAND=mutagen-compose hip run.

If you want to persist that change you can specify command in compose section of hip.yml :

compose:
  command: mutagen-compose

hip ls

List all available run commands.

hip ls

bash     # Open the Bash shell in app's container
rails    # Run Rails command
rails s  # Run Rails server at http://localhost:3000

Options

--format, -f - Output format (table, json, yaml):

hip ls --format json           # JSON output for scripts/tools
hip ls -f yaml                 # YAML output

--detailed, -d - Show detailed information (runner, service, command):

hip ls --detailed

shell    [DockerCompose]  service:app  /bin/bash
         # Open the Bash shell in app's container
pry      [DockerCompose]  service:app  ./bin/console
         # Open Pry console

JSON output example:

{
  "shell": {
    "description": "Open the Bash shell in app's container",
    "command": "/bin/bash",
    "runner": "DockerCompose",
    "shell": true,
    "service": "app",
    "compose_method": "run"
  }
}

hip up

Start Docker Compose services with smart defaults.

Default behavior (v9.1.2+):

Runs in detached mode (-d)
Waits for services to be healthy (--wait)

hip up          # Equivalent to: docker compose up -d --wait
hip up web      # Start specific service
hip up -f       # Run in foreground (disable defaults)

Custom defaults via hip.yml:

compose:
  up_options: ["--build", "-d"]  # Custom default options

hip provision

Run initialization commands from provision section of hip.yml.

Auto-Start Containers (v9.1.3+): hip provision now automatically starts containers if they're not running. You can run hip provision directly without running hip up first:

# Simple workflow - just run provision
hip provision   # Automatically starts containers if needed, then runs initialization

# Or traditional workflow (still works)
hip up -d       # Start containers manually
hip provision   # Run initialization scripts

Smart Container Detection (v9.1.0+): Hip automatically detects running containers and switches execution modes:

No containers running → Starts containers with docker compose up -d --wait, then runs provision
Container not running → docker compose run (creates new container)
Container already running → docker compose exec (uses existing container)
This ensures stateful operations (gem installation, database migrations) work correctly in provision workflows

Migration: If upgrading from earlier versions, see MIGRATION.md for updating your hip.yml.

hip compose

Run Docker Compose commands that are configured according to the application's hip.yml:

hip compose COMMAND [OPTIONS]

hip compose up -d redis

hip infra

Runs shared Docker Compose services that are used by the current application. Useful for microservices.

There are several official infrastructure services available:

# hip.yml
infra:
  foo:
    git: https://github.com/owner/foo.git
    ref: latest # default, optional
  bar:
    path: ~/path/to/bar

Repositories will be pulled to a ~/.hip/infra folder. For example, for the foo service it would be like this: ~/.hip/infra/foo/latest and clonned with the following command: git clone -b <ref> --single-branch <git> --depth 1.

Available CLI commands:

hip infra update pulls updates from sources
hip infra up starts all infra services
hip infra up -n kafka starts a specific infra service
hip infra down stops all infra services
hip infra down -n kafka stops a specific infra service

hip ktl

Run kubectl commands that are configured according to the application's hip.yml:

hip ktl COMMAND [OPTIONS]

STAGE=some hip ktl get pods

hip ssh

Runs ssh-agent container based on https://github.com/whilp/ssh-agent with your ~/.ssh/id_rsa. It creates a named volume ssh_data with ssh socket. An application's docker-compose.yml should contains environment variable SSH_AUTH_SOCK=/ssh/auth/sock and connects to external volume ssh_data.

hip ssh up

docker-compose.yml

services:
  web:
    environment:
      - SSH_AUTH_SOCK=/ssh/auth/sock
    volumes:
      - ssh-data:/ssh:ro

volumes:
  ssh-data:
    external:
      name: ssh_data

if you want to use non-root user you can specify UID like so:

hip ssh up -u 1000

This especially helpful if you have something like this in your docker-compose.yml:

services:
  web:
    user: "1000:1000"

hip validate

Validates your hip.yml configuration against the JSON schema. The schema validation helps ensure your configuration is correct and follows the expected format.

hip validate

The validator will check:

Required properties are present
Property types are correct
Values match expected patterns
No unknown properties are used

If validation fails, you'll get detailed error messages indicating what needs to be fixed.

You can skip validation by setting HIP_SKIP_VALIDATION environment variable.

Add # yaml-language-server: $schema=https://raw.githubusercontent.com/ScriptonBasestar/hip/refs/heads/master/schema.json to the top of your hip.yml to get schema validation in VSCode. Read more about YAML Language Server.

hip manifest

Outputs a complete command manifest with metadata about all available commands, subcommands, and runners. This is particularly useful for:

LLMs/AI tools - Discover and understand all Hip commands without parsing source code
Shell completion generators - Generate accurate completions for shells
Documentation tools - Build reference documentation automatically
CI/CD scripts - Validate configurations and available commands

hip manifest                   # JSON output (default)
hip manifest --format yaml     # YAML output
hip manifest -f json           # Short form

The manifest includes:

Static commands - Built-in CLI commands (version, ls, compose, run, etc.)
Subcommand groups - Hierarchical subcommands (ssh, infra, console, devcontainer, claude)
Dynamic commands - Commands defined in your hip.yml interaction section
Runners - Available runner types and their trigger conditions

JSON output example:

{
  "hip_version": "9.1.0",
  "schema_version": "1.0",
  "generated_at": "2025-11-25T17:15:25+09:00",
  "config_file": "/path/to/hip.yml",
  "static_commands": {
    "run": {
      "description": "Run configured command (run prefix may be omitted)",
      "type": "dynamic_router",
      "options": {
        "publish": "Publish container ports to host",
        "explain": "Show execution plan without running"
      }
    }
  },
  "dynamic_commands": {
    "shell": {
      "description": "Open the Bash shell in app's container",
      "command": "/bin/bash",
      "runner": "docker_compose",
      "service": "app"
    }
  },
  "runners": {
    "docker_compose": {
      "trigger": "service key present in command config",
      "description": "Executes commands in Docker Compose services"
    }
  }
}

hip devcontainer

Hip provides seamless integration with VSCode DevContainers, enabling bidirectional synchronization between hip.yml and .devcontainer/devcontainer.json.

Features

Bidirectional Sync: Keep hip.yml and devcontainer.json in sync
Feature Shortcuts: Use simple names like docker-in-docker instead of full feature URLs
Templates: Quick-start templates for Ruby, Node.js, Python, Go, and full-stack projects
CLI Commands: Manage devcontainer configuration from command line

Quick Start

# Generate devcontainer.json from hip.yml
hip devcontainer init

# Use a template
hip devcontainer init --template ruby

# Sync configurations
hip devcontainer sync

# Validate devcontainer.json
hip devcontainer validate

# Open shell in devcontainer
hip devcontainer bash

# Run postCreateCommand
hip devcontainer provision

# View devcontainer info
hip devcontainer info

# List available features
hip devcontainer features --list

Configuration Example

# hip.yml
devcontainer:
  enabled: true
  name: "My Rails App"
  service: app
  workspaceFolder: "/workspace"

  # Simple feature shortcuts
  features:
    docker-in-docker: {}
    github-cli:
      version: "latest"

  customizations:
    vscode:
      extensions:
        - rebornix.ruby
        - castwide.solargraph

  forwardPorts: [3000, 5432]
  postCreateCommand: "bundle install && rails db:setup"

See examples/devcontainer.yml for a complete example.

Available Templates

ruby - Ruby/Rails development
node - Node.js/JavaScript development
python - Python development
go - Go development
full-stack - Full-stack with multiple languages

Feature Shortcuts

Hip provides convenient shortcuts for common DevContainer features:

docker-in-docker → ghcr.io/devcontainers/features/docker-in-docker:2
github-cli → ghcr.io/devcontainers/features/github-cli:1
node → ghcr.io/devcontainers/features/node:1
python → ghcr.io/devcontainers/features/python:1
go → ghcr.io/devcontainers/features/go:1
kubectl → ghcr.io/devcontainers/features/kubectl-helm-minikube:1

Use hip devcontainer features --list to see all available shortcuts.

hip claude

Hip provides integration with Claude Code (claude.ai/code) to make Hip commands easily discoverable and usable within AI-assisted development workflows.

Features

Auto-generated Documentation: Creates Claude-readable guides from your hip.yml configuration
Project-Specific Commands: Generates .claude/ctx/hip-project-guide.md with available commands
Slash Commands: Adds /hip command for interactive help in Claude Code
Global Reference: Optional ~/.claude/ctx/HIP_QUICK_REFERENCE.md for Hip basics
Auto-provisioning: Automatically generates Claude files during hip provision (first run only)

Quick Start

# Generate Claude Code integration files for current project
hip claude:setup

# Also create global reference guide
hip claude:setup --global

What Gets Generated

After running hip claude:setup, you'll have:

.claude/ctx/hip-project-guide.md - Project-specific command reference

Lists all available Hip commands from hip.yml
Includes descriptions for each command
Shows configured services and environment variables
Auto-updated with hip claude:setup

.claude/commands/hip.md - Slash command for Claude Code

Type /hip in Claude Code for interactive help
Quick access to command documentation

~/.claude/ctx/HIP_QUICK_REFERENCE.md (optional with --global)

Hip basics and command syntax
Common patterns and examples
Available across all projects

Usage in Claude Code

Once set up, Claude Code can:

Discover commands: Ask "What Hip commands are available?"
Get help: Use /hip slash command
Understand context: Reads project-specific configuration
Suggest workflows: Recommends appropriate Hip commands for tasks

Example

# hip.yml
interaction:
  console:
    description: "Open Rails console"
    service: rails
    command: bin/rails console

  test:
    description: "Run test suite"
    service: rails
    command: bundle exec rspec

After hip claude:setup, Claude Code will know:

hip console opens Rails console
hip test runs the test suite
Both commands use the rails service

Auto-Generation

Claude files are automatically generated when you run hip provision for the first time in a project. To regenerate after changing hip.yml:

hip claude:setup

Note: .claude/ directory is automatically git-ignored as it contains auto-generated files.

📖 Documentation

Configuration Examples - Comprehensive examples for various use cases
Development Roadmap - Future plans and Ruby 3.2+ migration strategy
Schema Reference - Configuration schema for validation
Original Project - Evil Martians' original dip project

Changelog

See CHANGELOG.md for version history.

Original project releases: https://github.com/bibendi/dip/releases

Name		Name	Last commit message	Last commit date
Latest commit History 509 Commits
.danger		.danger
.github		.github
.make		.make
bin		bin
completions		completions
docs		docs
examples		examples
exe		exe
lib		lib
spec		spec
.gitignore		.gitignore
.pryrc		.pryrc
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTEXT_MAP.md		CONTEXT_MAP.md
Dangerfile		Dangerfile
Gemfile		Gemfile
INSTALL.md		INSTALL.md
LICENSE.txt		LICENSE.txt
Makefile		Makefile
README.md		README.md
Rakefile		Rakefile
docker-compose.yml		docker-compose.yml
hip.gemspec		hip.gemspec
hip.yml		hip.yml
lefthook-local.hip_example.yml		lefthook-local.hip_example.yml
lefthook.yml		lefthook.yml
schema.json		schema.json

License

ScriptonBasestar/hip

Folders and files

Latest commit

History

Repository files navigation

Hip

Presentations and examples

📚 Configuration Examples

Installation

Shell Completions

Integration with shell

Usage

hip.yml

Predefined environment variables

$HIP_OS

$HIP_WORK_DIR_REL_PATH

$HIP_CURRENT_USER

Modules

hip run

Options

Environment Variables

hip ls

Options

hip up

hip provision

hip compose

hip infra

hip ktl

hip ssh

hip validate

hip manifest

hip devcontainer

Features

Quick Start

Configuration Example

Available Templates

Feature Shortcuts

hip claude

Features

Quick Start

What Gets Generated

Usage in Claude Code

Example

Auto-Generation

📖 Documentation

Changelog

About

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages