Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-16 20:17:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: document the official shell client

Browse Source 
Closes #3963

[ci skip]
This commit is contained in:
Jose Diaz-Gonzalez
2020-07-17 14:07:00 -04:00
parent 3f09c82379
commit bb33a2fe27
2 changed files with 72 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/community/clients.md
View File

@@ -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 <tag/branch>
# 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

73
docs/deployment/remote-commands.md
View File

@@ -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 <tag/branch>
# 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.