github.com/drud/ddev@v1.21.5-alpha1.0.20230226034409-94fcc4b94453/docs/content/users/extend/custom-commands.md (about) 1 # Custom Commands 2 3 Custom commands can easily be added to DDEV, to be executed on the host or in containers. 4 5 This involves adding a Bash script to the project in `.ddev/commands/host`, a specific container in `.ddev/commands/<containername>`, or globally in `~/.ddev/commands`. 6 7 Example commands in `ddev/commands/*/*.example` can be copied, moved, or symlinked. 8 9 For example, [.ddev/commands/host/mysqlworkbench.example](https://github.com/drud/ddev/blob/master/pkg/ddevapp/global_dotddev_assets/commands/host/mysqlworkbench.example) can be used to add a `ddev mysqlworkbench` command. Rename it from `mysqlworkbench.example` to `mysqlworkbench`. If you’re on macOS or Linux (or some configurations of Windows) you can `cd .ddev/commands/host && ln -s mysqlworkbench.example mysqlworkbench`. 10 11 The [`ddev mysql`](../usage/commands.md#mysql) runs the `mysql` client inside the `db` container command using this technique. See the [`ddev mysql` command](https://github.com/drud/ddev/blob/master/pkg/ddevapp/global_dotddev_assets/commands/db/mysql). 12 13 ## Notes for All Command Types 14 15 * The command filename is not what determines the name of the command. That comes from the “Usage” doc line (`## Usage: commandname`). 16 * To confirm that your custom command is available, run `ddev -h` and look for it in the list. 17 18 ## Host Commands 19 20 To provide host commands, place a Bash script in `.ddev/commands/host`. For example, a PhpStorm launcher to make the `ddev phpstorm` command might go in `.ddev/commands/host/phpstorm` with these contents: 21 22 ```bash 23 #!/usr/bin/env bash 24 25 ## Description: Open PhpStorm with the current project 26 ## Usage: phpstorm 27 ## Example: "ddev phpstorm" 28 29 # Example is macOS-specific, but easy to adapt to any OS 30 open -a PhpStorm.app ${DDEV_APPROOT} 31 ``` 32 33 ## Container Commands 34 35 To provide a command which will execute in a container, add a Bash script to `.ddev/commands/<container_name>`, for example, `.ddev/commands/web/mycommand`. The Bash script will be executed inside the named container. For example, see the [several standard DDEV script-based web container commands](https://github.com/drud/ddev/blob/master/pkg/ddevapp/global_dotddev_assets/commands/web). 36 37 You can run commands in custom containers as well as standard DDEV `web` and `db` containers. Use the service name, like `.ddev/commands/solr/<command>`. The only catch with a custom container is that your service must mount `/mnt/ddev_config` like the `web` and `db` containers do; the `volumes` section of `docker-compose.<servicename>.yaml` needs: 38 39 ``` 40 volumes: 41 - ".:/mnt/ddev_config" 42 ``` 43 44 For example, to add a `solrtail` command that runs in a Solr service, add `.ddev/commands/solr/solrtail` with: 45 46 ```bash 47 #!/bin/bash 48 49 ## Description: Tail the main solr log 50 ## Usage: solrtail 51 ## Example: ddev solrtail 52 53 tail -f /opt/solr/server/logs/solr.log 54 ``` 55 56 ## Global Commands 57 58 Global commands work exactly the same as project-level commands, they just need to go in your global `.ddev` directory. Your home directory has a `.ddev/commands` in it, where you can add host, web, or db commands. 59 60 ## Shell Command Examples 61 62 There are many examples of [global](https://github.com/drud/ddev/tree/master/pkg/ddevapp/global_dotddev_assets/commands) and [project-level](https://github.com/drud/ddev/tree/master/pkg/ddevapp/dotddev_assets/commands) custom/shell commands that ship with DDEV you can adapt for your own use. They can be found in your `~/.ddev/commands/*` directories and in your project’s `.ddev/commands/*` directories. There you’ll see how to provide usage, examples, and how to use arguments provided to the commands. For example, the [`xdebug` command](https://github.com/drud/ddev/blob/master/pkg/ddevapp/global_dotddev_assets/commands/web/xdebug) shows simple argument processing and the [launch command](https://github.com/drud/ddev/blob/master/pkg/ddevapp/global_dotddev_assets/commands/host/launch) demonstrates flag processing. 63 64 ## Environment Variables Provided 65 66 A number of environment variables are provided to these command scripts. These are generally supported, but please avoid using undocumented environment variables. Useful variables for host scripts are: 67 68 * `DDEV_APPROOT`: file system location of the project on the host 69 * `DDEV_DATABASE`: database in use, in format `type:version` (example: `mariadb:10.5`) 70 * `DDEV_DOCROOT`: relative path from approot to docroot 71 * `DDEV_HOSTNAME`: comma-separated list of FQDN hostnames 72 * `DDEV_HOST_DB_PORT`: localhost port of the database server 73 * `DDEV_HOST_HTTPS_PORT`: localhost port for HTTPS on web server 74 * `DDEV_HOST_MAILHOG_PORT`: localhost port for MailHog 75 * `DDEV_HOST_WEBSERVER_PORT`: localhost port of the web server 76 * `DDEV_MUTAGEN_ENABLED`: `true` if Mutagen is enabled 77 * `DDEV_PHP_VERSION`: current PHP version 78 * `DDEV_PRIMARY_URL`: primary project URL 79 * `DDEV_PROJECT`: project name, like `d8composer` 80 * `DDEV_PROJECT_TYPE`: `drupal8`, `typo3`, `backdrop`, `wordpress`, etc. 81 * `DDEV_ROUTER_HTTP_PORT`: router port for HTTP 82 * `DDEV_ROUTER_HTTPS_PORT`: router port for HTTPS 83 * `DDEV_SITENAME`: project name, like `d8composer` 84 * `DDEV_TLD`: top-level project domain, like `ddev.site` 85 * `DDEV_WEBSERVER_TYPE`: `nginx-fpm` or `apache-fpm` 86 * `GOARCH`: architecture (`arm64`, `amd64`) 87 * `GOOS`: operating system (`windows`, `darwin`, `linux`) 88 89 Useful variables for container scripts are: 90 91 * `DDEV_DOCROOT`: relative path from approot to docroot 92 * `DDEV_FILES_DIR`: directory of user-uploaded files 93 * `DDEV_HOSTNAME`: comma-separated list of FQDN hostnames 94 * `DDEV_MUTAGEN_ENABLED`: `true` if Mutagen is enabled 95 * `DDEV_PHP_VERSION`: current PHP version 96 * `DDEV_PRIMARY_URL`: primary URL for the project 97 * `DDEV_PROJECT`: project name, like `d8composer` 98 * `DDEV_PROJECT_TYPE`: `drupal8`, `typo3`, `backdrop`, `wordpress`, etc. 99 * `DDEV_ROUTER_HTTP_PORT`: router port for HTTP 100 * `DDEV_ROUTER_HTTPS_PORT`: router port for HTTPS 101 * `DDEV_SITENAME`: project name, like `d8composer` 102 * `DDEV_TLD`: top-level project domain, like `ddev.site` 103 * `DDEV_WEBSERVER_TYPE`: `nginx-fpm` or `apache-fpm` 104 * `IS_DDEV_PROJECT`: if `true`, PHP is running under DDEV 105 106 ## Annotations Supported 107 108 Custom commands support various annotations in the header for providing additional information to the user. 109 110 ### “Description” Annotation 111 112 `Description` should briefly describe the command in its help message. 113 114 Usage: `## Description: <command-description>` 115 116 Example: `## Description: my great custom command` 117 118 ### “Usage” Annotation 119 120 `Usage` should explain how to use the command in its help message. 121 122 Usage: `## Usage: <command-usage>` 123 124 Example: `## Usage: commandname [flags] [args]` 125 126 ### “Example” Annotation 127 128 `Example` should demonstrate how the command might be used. Use `\n` to force a line break. 129 130 Usage: `## Example: <command-example>` 131 132 Example: `## Example: commandname\ncommandname -h` 133 134 ### “Flags” Annotation 135 136 `Flags` should explain any available flags, including their shorthand when relevant, for the help message. It has to be encoded according the following definition: 137 138 If no flags are specified, the command will have its flags parsing disabled. Global flags like `--help` will not work unless the command supports them. 139 140 You can still do `ddev help <command>` to see the command's provided usage help. 141 142 Usage: `## Flags: <json-definition>` 143 144 This is the minimal usage of a flags definition: 145 146 Example: `## Flags: [{"Name":"flag","Usage":"sets the flag option"}]` 147 148 Output: 149 150 ```bash 151 Flags: 152 -h, --help help for ddev 153 -f, --flag sets the flag option 154 ``` 155 156 Multiple flags are separated by a comma: 157 158 Example: `## Flags: [{"Name":"flag1","Shorthand":"f","Usage":"flag1 usage"},{"Name":"flag2","Usage":"flag2 usage"}]` 159 160 Output: 161 162 ```bash 163 Flags: 164 -h, --help help for ddev 165 -f, --flag1 flag1 usage 166 --flag2 flag2 usage 167 ``` 168 169 The following fields can be used for a flag definition: 170 171 * `Name`: the name as it appears on command line 172 * `Shorthand`: one-letter abbreviated flag 173 * `Usage`: help message 174 * `Type`: possible values are `bool`, `string`, `int`, `uint` (defaults to `bool`) 175 * `DefValue`: default value for usage message 176 * `NoOptDefVal`: default value, if the flag is on the command line without any options 177 * `Annotations`: used by cobra.Command Bash autocomplete code (see <https://github.com/spf13/cobra/blob/master/bash_completions.md>) 178 179 ### “ProjectTypes” Annotation 180 181 If your command should only be visible for a specific project type, `ProjectTypes` will allow you to define the supported types. This is especially useful for global custom commands. See [Quickstart for many CMSes](../../users/quickstart.md) for more information about the supported project types. Multiple types are separated by a comma. 182 183 Usage: `## ProjectTypes: <list-of-project-types>` 184 185 Example: `## ProjectTypes: drupal7,drupal8,drupal9,backdrop` 186 187 ### “OSTypes” Annotation (Host Commands Only) 188 189 If your host command should only run on one or more operating systems, add the `OSTypes` annotation. Multiple types are separated by a comma. Valid types are: 190 191 * `darwin` for macOS 192 * `windows` for Windows 193 * `linux` for Linux 194 195 Usage: `## OSTypes: <list-of-os-types>` 196 197 Example: `## OSTypes: darwin,linux` 198 199 ### “HostBinaryExists” Annotation (Host Commands Only) 200 201 If your host command should only run if a particular file exists, add the `HostBinaryExists` annotation. 202 203 Usage: `## HostBinaryExists: <path/to/file>` 204 205 Example: `## HostBinaryExists: /Applications/Sequel ace.app` 206 207 ### “DBTypes” Annotation 208 209 If your command should only be available for a particular database type, add the `DBTypes` annotation. Multiple types are separated by a comma. Valid types the available database types. 210 211 Usage: `## DBTypes: <type>` 212 213 Example: `## DBTypes: postgres` 214 215 ### “HostWorkingDir” Annotation (Container Commands Only) 216 217 If your container command should run from the directory you are running the command in the host, add the `HostWorkingDir` annotation. 218 219 Example: `## HostWorkingDir: true` 220 221 ## Known Windows Issues 222 223 ### Line Endings 224 225 If you’re editing a custom command to be run in a container, it must have LF line endings and not traditional Windows CRLF line endings. Remember that a custom command in a container is a script that must execute in a Linux environment. 226 227 ### Bash 228 229 Commands can’t be executed if DDEV can’t find `bash`. If you’re running inside Git Bash in most any terminal, this shouldn’t be an issue, and DDEV should be able to find `git-bash` if it’s in `C:\Program Files\Git\bin` as well. But if neither of those is true, add the directory of `bash.exe` to your `PATH` environment variable.