dip CLI

The preflight section in dip.yml defines an array of shell commands that Dip runs before any command that interacts with a running container or cluster (e.g., dip compose ..., dip ktl ..., dip run ..., or interaction shorthands).

If any preflight command exits with a non-zero status, Dip aborts the operation. This is useful for verifying credentials, checking for required files, or ensuring environment variables are set.

Note: Preflight is NOT triggered by:

• dip down --all (cross-project teardown)
• dip ssh
• dip infra
• dip provision

preflight:
  - ./bin/check-credentials
  - test -f .env

Modules allow you to group related interaction commands in separate files to improve maintainability across multiple projects. Module files must be stored in a .dip subdirectory next to your dip.yml.

• Loading: List module names in the modules array in dip.yml.
• Expansion: Module contents are expanded into the main configuration.
• Overriding: You can override a command defined in a module by redefining it directly in your main dip.yml.
• Limitation: Nested modules are not supported.

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

# Redefining a module command in the main config
interaction:
  brakeman:
    command: docker run another-image ...

Use dip-skill to automatically configure a dip environment. It detects your project's tech stack and bootstraps the necessary dip.yml, Docker Compose files, and Dockerfiles.

npx skills add kalashnikovisme/dip-skill

The dip ssh up command runs an ssh-agent container that shares your host's ~/.ssh/id_rsa via a named volume ssh_data.

To use this, your docker-compose.yml must:

1. Set the environment variable SSH_AUTH_SOCK=/ssh/auth/sock.
2. Connect to the external volume ssh_data.

Usage:

• Standard: dip ssh up
• With specific UID: dip ssh up -u 1000

# docker-compose.yml requirement
services:
  web:
    environment:
      - SSH_AUTH_SOCK=/ssh/auth/sock
    volumes:
      - ssh-data:/ssh:ro

volumes:
  ssh-data:
    external:
      name: ssh_data

Install the dip CLI tool using the RubyGems package manager.

gem install dip

The dip console command uses an injection mechanism to provide convenient aliases for common tasks. This allows you to run dip commands directly as if they were native shell functions.

Automatic Aliases

If a dip.yml configuration exists, dip automatically creates aliases for:

1. Any keys defined under the interaction section of your dip.yml.
2. Core commands: compose, up, stop, down, provision, and build.

For example, if compose is aliased, running compose up in your shell is equivalent to running dip compose up.

Zsh Integration

If you are using zsh, dip hooks into the chpwd function. This means that whenever you change directories (cd), dip will automatically call dip_reload to ensure your environment and aliases remain synchronized with your current context.

Dip uses a dip.yml file for configuration. It supports an override mechanism where a file named dip.yml.override.yml can be used to merge additional settings into the base configuration.

File Discovery Logic:

1. Explicit Path: If the DIP_FILE environment variable is set, Dip uses that path. If override: true is active (during override loading), it automatically appends .override.yml to the path provided in DIP_FILE.
2. Automatic Search: If DIP_FILE is not set, Dip searches for dip.yml starting from the current working directory and traverses up the directory tree until the file is found or the root is reached.
3. Overrides: When loading overrides, if DIP_FILE is set to dip.yml, the system looks for dip.yml.override.yml.

You can extend your configuration by using the modules key in dip.yml. Modules must be specified as an array of strings. Each string corresponds to a filename located in a .dip directory relative to your dip.yml file.

For example, if your config has modules: [auth], Dip will look for .dip/auth.yml. The contents of these module files are deep-merged into the main configuration. Note that nested modules (modules within modules) are not supported.

When using profiles in your dip.yml configuration for a Docker Compose runner, dip automatically modifies the execution behavior to ensure compatibility with docker compose.

Specifically, if profiles are defined:

1. The method is forced to up (because docker compose does not support profiles for other commands like run).
2. The command is cleared.
3. run_options are removed because they are not supported by the up command.

Profiles are passed to the underlying command using the --profile <profile_name> flag for each profile specified.

When managing infrastructure services via dip, each service is identified by a name and is associated with specific Docker Compose and networking configurations.

An infrastructure service requires either a git repository URL or a local path.

Key attributes generated for a service include:

• Location: If using git, the service is stored at #{Dip.home_path}/infra/{name}/{ref}. If using a path, it uses the expanded local path.
• Project Name: The Docker Compose project name follows the pattern dip-infra-{name}-{ref}.
• Network Name: The Docker network name follows the pattern dip-net-{name}-{ref}.
• Network Environment Variable: To access the service's network, use the environment variable DIP_INFRA_NETWORK_{NAME_IN_UPPERCASE_WITH_UNDERSCORES} (e.g., a service named my-db uses DIP_INFRA_NETWORK_MY_DB).