diff --git a/docs/community/clients.md b/docs/community/clients.md index b61cde62f..ff9d9228e 100644 --- a/docs/community/clients.md +++ b/docs/community/clients.md @@ -4,54 +4,9 @@ Given the constraints, running Dokku commands remotely via SSH is fine. For cert While Dokku does not yet have an official client, there are a multitude of ways in which you can interact with your Dokku installation. The easiest is to use the **bash** client, though you may wish to use another. -## (bash, zsh, etc.) `dokku_client.sh` +## Official Client -Of all methods, this is the *most* official method of interacting with your Dokku installation. It is a bash script that interacts with a remote Dokku installation via `ssh`. It is available in `contrib/dokku_client.sh` in the root of the Dokku repository. - -It can be installed either via the [Homebrew](https://brew.sh) package manager (macOS only), or manually. - -### Installation via Homebrew - -To install, simply run the following command: - -```shell -brew install dokku/repo/dokku -``` - -### Manual installation - -To install manually, simply clone the Dokku repository down and add the `dokku` alias pointing at the script: - -```shell -git clone git@github.com:dokku/dokku.git ~/.dokku - -# optional: make sure that the dokku_client.sh version matches your Dokku version -cd ~/.dokku -git checkout - -# add the following to either your -# .bashrc, .bash_profile, or .profile file -alias dokku='$HOME/.dokku/contrib/dokku_client.sh' -``` - -Alternatively, if using another shell such as **zsh**, create an alias command which invokes the script using **bash**: - -```shell -# zsh: add the following to either .zshenv or .zshrc -alias dokku='bash $HOME/.dokku/contrib/dokku_client.sh' - -# fish: add the following to ~/.config/fish/config.fish -alias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh' - -# csh: add the following to .cshrc -alias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh' -``` - -### Usage - -Configure the `DOKKU_HOST` environment variable or run `dokku` from a repository with a git remote named `dokku` pointed at your Dokku host in order to use the script as normal. - -You can also configure a `DOKKU_PORT` environment variable if you are running ssh on a non-standard port. This defaults to `22`. +See the [remote commands documentation](/docs/deployment/remote-commands.md) for more information on how to install and use the official client. ## (nodejs) dokku-toolbelt diff --git a/docs/deployment/remote-commands.md b/docs/deployment/remote-commands.md index 348b94704..33a912cae 100644 --- a/docs/deployment/remote-commands.md +++ b/docs/deployment/remote-commands.md @@ -21,8 +21,75 @@ in order to avoid SSH interpretting Dokku arguments for itself. --force force flag. currently used in apps:destroy and other ":destroy" commands ``` -## Clients +## Official Client -You may optionally use a client to connect to your Dokku server. Most clients use the configured `git remote` to locate the Dokku server, though some allow for overriding this via an environment variable or flag. +You may optionally use the official client when connecting to the Dokku server. -Please refer to the [clients](/docs/community/clients.md) list for more details. +Of all methods, this is the *most* official method of interacting with your Dokku installation. It is a bash script that interacts with a remote Dokku installation via `ssh`. It is available in `contrib/dokku_client.sh` in the root of the Dokku repository. + +It can be installed either via the [Homebrew](https://brew.sh) package manager (macOS only), or manually. + +### Installation via Homebrew + +To install, simply run the following command: + +```shell +brew install dokku/repo/dokku +``` + +### Manual installation + +To install manually, simply clone the Dokku repository down and add the `dokku` alias pointing at the script: + +```shell +git clone git@github.com:dokku/dokku.git ~/.dokku + +# optional: make sure that the dokku_client.sh version matches your Dokku version +cd ~/.dokku +git checkout + +# add the following to either your +# .bashrc, .bash_profile, or .profile file +alias dokku='$HOME/.dokku/contrib/dokku_client.sh' +``` + +Alternatively, if using another shell such as **zsh**, create an alias command which invokes the script using **bash**: + +```shell +# zsh: add the following to either .zshenv or .zshrc +alias dokku='bash $HOME/.dokku/contrib/dokku_client.sh' + +# fish: add the following to ~/.config/fish/config.fish +alias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh' + +# csh: add the following to .cshrc +alias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh' +``` + +### Usage + +All commands have the application name automatically set via the `--app` flag on the remote server, and thus the app name does not need to be specified manually for core plugins. + +The client supports several environment variables: + +- `DOKKU_HOST` (default: `dokku` git remote): Used to interact with a specific remote server. Can be overriden via `--remote` flag. +- `DOKKU_PORT` (default: `22`): Used to specify a port to connect to the Dokku server on. + +It also supports several flags (all flags unspecified here are passed as is to the server): + +- `--app`: Override the remote app in use. +- `--trace`: Enable trace mode. +- `--remote`: Override the remote server. +- `--global`: Unsets the "app" value. May not be supported for the specified command. + +In addition, the following commands have special local side-effects: + +- `apps:create`: + - If no local `--app` flag is specified or detected from a `dokku` git remote, a random name is generated and used for the app. + - The `dokku` git remote is set if not already set. +- `apps:destroy`: + - Removes the local `dokku` git remote if set. + +## Unofficial Clients + +Please refer to the [community clients](/docs/community/clients.md) list for more details.