npm package: @selectcode/deploy-cli
Description: The official selectcode cli used for anything infrastructure related
Author: Julian Hartl @julian-hartl
Latest version: 0.1.0-10

Deploy cli
=================

The offical select cli for anything infrastructure related.

[![Version](https://img.shields.io/npm/v/@selectcode/deploy-cli.svg)](https://npmjs.org/package/@selectcode/deploy-cli)
[![Downloads/week](https://img.shields.io/npm/dw/@selectcode/deploy-cli.svg)](https://npmjs.org/package/@selectcode/deploy-cli)

<!-- toc -->
* [Usage](#usage)
* [Configuration](#configuration)
* [Q&A](#qa)
* [Change log](#change-log)
* [Commands](#commands)
<!-- tocstop -->

# Usage

<!-- usage -->
```sh-session
$ npm install -g @selectcode/deploy-cli
$ deploy-cli COMMAND
running command...
$ deploy-cli (--version)
@selectcode/deploy-cli/0.1.0-9 darwin-arm64 node-v18.16.0
$ deploy-cli --help [COMMAND]
USAGE
  $ deploy-cli COMMAND
...
```
<!-- usagestop -->

# Configuration

<!-- configuration -->

## Authentication

The cli will automatically prompt you to login if you are not logged in. Alternatively you can login using
the `deploy-cli login` command.

### Environment variables

- `EASYPANEL_TOKEN`: The api token of your easypanel account.
- `EASYPANEL_ENDPOINT`: The domain of your easypanel instance.

## Config file

We will walk you through the process of setting up a service with our config file with an example on how to setup a
postgres database service with pgadmin.

First of all, this is the config file we are working with:

```yaml
version: 1
project: "julian-test"
auth:
  username: ${REGISTRY_USERNAME}
  password: ${REGISTRY_PASSWORD}
services:
  - name: postgres
    image: postgres:14.1
    env:
      - POSTGRES_DB=test
    secrets:
      - name: POSTGRES_PASSWORD
      - name: POSTGRES_USER
    mounts:
      - type: volume
        name: postgres-data
        mountPath: /var/lib/postgresql/data
  - name: pg-admin
    image: dpage/pgadmin4
    domains:
      - host: <url>
        path: /
        https: true
        port: 80
    secrets:
      - name: PGADMIN_DEFAULT_PASSWORD
      - name: PGADMIN_DEFAULT_EMAIL
        from: PGADMIN_DEFAULT_USER

```

We first specify the version and project name.
Then we specify the authentication for the docker registry.
After that we specify the services we want to deploy.
The postgres service uses the official postgres image and exposes its port internally.
We set the database name to `test` and set the `POSTGRES_PASSWORD` and `POSTGRES_USER` secrets.
Note that these secrets are not set in the config file. Instead we set them as environment variables.
The `postgres-data` volume is mounted to the `/var/lib/postgresql/data` directory inside the container.

The pgadmin service uses the `dpage/pgadmin4` image and exposes its port to the internet.
We set the `PGADMIN_DEFAULT_PASSWORD` and `PGADMIN_DEFAULT_EMAIL` secrets.
Note that the `PGADMIN_DEFAULT_EMAIL` secret is set from the `PGADMIN_DEFAULT_USER` environment variable.
Pg admin is accessible from the internet using the domain `<url>`.

To deploy this config file, simply run `deploy-cli deploy -f <path to config file>`.

#### Version

The version of the config file. Currently only `1` is supported.

#### Project

The project name. This is the name of the project in the easypanel dashboard.

#### Services

A list of services to deploy. Each service has the following properties:

##### Name

The name of the service. This is used to identify the service in the dashboard and in the cli.

##### Image

The image to use for the service. This can be any image from docker hub or a private registry.
Note that for private registries you need to set the `auth` property in the config file.
You can override it on a service level by setting the `auth` property on the service.

##### Ports

A list of ports to expose. Each port can be either a number or a string in the format `published:target`.
The ports are useful for exposing non-web apps. "Published" is the port on your host machine and "Target" is the port
inside your application. If you want to expose HTTP/HTTPS you should use the "Proxy" from the "Domains" tab.

WARNING: If you expose a port, it will be accessible from the internet. Make sure you know what you are doing.

##### Env

A list of environment variables to set.

##### Secrets

A list of secrets to set. Each secret can be either a string or an object with the following properties:
`name` - The name of the secret.
`from` - The name of the environment variable to get the secret from. If not set, the name of the secret will be used.

##### Mounts

A list of mounts to mount.
There are three types of mounts:

- `volume` - Mounts a volume. Needs the `name` property.
- `file` - Mounts a file. Needs the `content` or `file_path` property.
  
  If `content` is set, the content of the file will be set to the value of the property.

  If `file_path` is set, the content of the file will be set to the content of the file at the given path.
- `bind` - Mounts a directory on the host machine. Needs the `hostPath` property.

Every mount has a `mountPath` property which is the path inside the container to mount to.

##### Domains

A list of domains the service should be accessible from. Note that these domains need a dns entry pointing to the
easypanel loadbalancer.

Each domain has the following properties:

- `host` - The host of the domain.
- `path` - The path of the domain (defaults to `/`).
- `https` - Whether to use https or not (defaults to `true`).
- `port` - The application port to use.

##### mem_limit

The memory limit for the service.

##### cpu_limit

The cpu limit for the service.

##### command

The command to run inside the container.

##### timeout

The timeout in milliseconds for the service to start. Defaults to 45 seconds.

##### needed_uptime

The uptime in milliseconds the service needs to have. Defaults to 7 seconds.

<!-- configurationstop -->

# Q&A

<!-- qa -->

## How do I reference other services?

More often than not you need to reference another service, e.g. when wanting to connect to a database.
To achieve that (for now) you have to manually find out the container name of the service.
It is typically constructed like this: `<project name>_<service name>`.
So, e.g. let's say you have a postgres db service named `postgres` and you're project is named `project`.
Then the container name would be `project_postgres`.
You can therefore connect to the database using the following connection string: `postgres://postgres:5432/<db_name>`.

# Change log

<!-- changelog -->

## 0.0.3

- Added `DEPLOY_CLI_CI` environment variable to disable caching of the token in CI/CD environments.
- Improved detection of failed container starts.
- Internal code improvements.
- `env_file` property is now supported (load environment variables from a file).

## 0.0.4

- Fix printing of error message

## 0.0.5

- BREAKING CHANGE: Changed the domain schema to fit the new easypanel api. See the [config file](#config-file) section
  for more information.

## 0.0.6

- Added `command` property to the service config.

## 0.0.7

- Added `file_path` property to the `file` mount type.
- Remove `port` property. Use `ports` instead.
- Replace environment variable references in domain host.
- Remove validation from `host` in `domains`
- Added `timeout` property to service.
- Added `needed_uptime` property to service.
- Start stopped services when deployed.

## 0.0.8

- Move secrets validation before any updates on the service.
- Add warning message on invalid time unit in uptime parsing.
- Fix bug where there are more replicas than in the config file, and so the services fails to deploy.
- Fix bug where you could not update back to having zero domains.
- Add warning when disabled service is deployed.
- Make `forceRebuild` optional, so that the default value of the Easypanel-API is used (same behavior as frontend).  
- Add more context to error message, when deployment has failed.
- Only watch the status of the needed containers when waiting for the deployment of the service.
- Force rebuild for service on deployment.
- Added `EASYPANEL_DOMAIN` environment variable to set the domain of the easypanel api.

## 0.1.0

- Replace internal api client with [easypanel.js](https://www.npmjs.com/package/easypanel.js)
- Remove docker container health checks until this [issue](https://github.com/Fristroop/easypanel.js/issues/5) is resolved 
- Remove authentication via email and password. Use the `EASYPANEL_TOKEN` environment variable instead
- Remove login and logout commands
- Remove DEPLOY_CLI_CI environment variable
- Renamed `EASYPANEL_DOMAIN` to `EASYPANEL_ENDPOINT`
- Resolve Env-Var references in domain.port field
# Commands

<!-- commands -->
* [`deploy-cli deploy`](#deploy-cli-deploy)
* [`deploy-cli help [COMMANDS]`](#deploy-cli-help-commands)
* [`deploy-cli plugins`](#deploy-cli-plugins)
* [`deploy-cli plugins:install PLUGIN...`](#deploy-cli-pluginsinstall-plugin)
* [`deploy-cli plugins:inspect PLUGIN...`](#deploy-cli-pluginsinspect-plugin)
* [`deploy-cli plugins:install PLUGIN...`](#deploy-cli-pluginsinstall-plugin-1)
* [`deploy-cli plugins:link PLUGIN`](#deploy-cli-pluginslink-plugin)
* [`deploy-cli plugins:uninstall PLUGIN...`](#deploy-cli-pluginsuninstall-plugin)
* [`deploy-cli plugins reset`](#deploy-cli-plugins-reset)
* [`deploy-cli plugins:uninstall PLUGIN...`](#deploy-cli-pluginsuninstall-plugin-1)
* [`deploy-cli plugins:uninstall PLUGIN...`](#deploy-cli-pluginsuninstall-plugin-2)
* [`deploy-cli plugins update`](#deploy-cli-plugins-update)
* [`deploy-cli service deploy SERVICENAME`](#deploy-cli-service-deploy-servicename)
* [`deploy-cli service logs SERVICENAME`](#deploy-cli-service-logs-servicename)
* [`deploy-cli service ls`](#deploy-cli-service-ls)
* [`deploy-cli service rebuild SERVICENAME`](#deploy-cli-service-rebuild-servicename)
* [`deploy-cli service start SERVICENAME`](#deploy-cli-service-start-servicename)
* [`deploy-cli service stop SERVICENAME`](#deploy-cli-service-stop-servicename)
* [`deploy-cli update [CHANNEL]`](#deploy-cli-update-channel)

## `deploy-cli deploy`

Deploy all services in a config file

```
USAGE
  $ deploy-cli deploy [-c <value>]

FLAGS
  -c, --configFileName=<value>  [default: easypanel.yml] Name of the config file to use

DESCRIPTION
  Deploy all services in a config file

EXAMPLES
  $ deploy-cli deploy
```

## `deploy-cli help [COMMANDS]`

Display help for deploy-cli.

```
USAGE
  $ deploy-cli help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for deploy-cli.
```

_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.0.7/src/commands/help.ts)_

## `deploy-cli plugins`

List installed plugins.

```
USAGE
  $ deploy-cli plugins [--json] [--core]

FLAGS
  --core  Show core plugins.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  List installed plugins.

EXAMPLES
  $ deploy-cli plugins
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/index.ts)_

## `deploy-cli plugins:install PLUGIN...`

Installs a plugin into the CLI.

```
USAGE
  $ deploy-cli plugins add plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -s, --silent   Silences yarn output.
  -v, --verbose  Show verbose yarn output.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Installs a plugin into the CLI.
  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.


ALIASES
  $ deploy-cli plugins add

EXAMPLES
  $ deploy-cli plugins add myplugin 

  $ deploy-cli plugins add https://github.com/someuser/someplugin

  $ deploy-cli plugins add someuser/someplugin
```

## `deploy-cli plugins:inspect PLUGIN...`

Displays installation properties of a plugin.

```
USAGE
  $ deploy-cli plugins inspect PLUGIN...

ARGUMENTS
  PLUGIN  [default: .] Plugin to inspect.

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Displays installation properties of a plugin.

EXAMPLES
  $ deploy-cli plugins inspect myplugin
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/inspect.ts)_

## `deploy-cli plugins:install PLUGIN...`

Installs a plugin into the CLI.

```
USAGE
  $ deploy-cli plugins install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -s, --silent   Silences yarn output.
  -v, --verbose  Show verbose yarn output.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Installs a plugin into the CLI.
  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.


ALIASES
  $ deploy-cli plugins add

EXAMPLES
  $ deploy-cli plugins install myplugin 

  $ deploy-cli plugins install https://github.com/someuser/someplugin

  $ deploy-cli plugins install someuser/someplugin
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/install.ts)_

## `deploy-cli plugins:link PLUGIN`

Links a plugin into the CLI for development.

```
USAGE
  $ deploy-cli plugins link PLUGIN

ARGUMENTS
  PATH  [default: .] path to plugin

FLAGS
  -h, --help          Show CLI help.
  -v, --verbose
      --[no-]install  Install dependencies after linking the plugin.

DESCRIPTION
  Links a plugin into the CLI for development.
  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
  command will override the user-installed or core plugin implementation. This is useful for development work.


EXAMPLES
  $ deploy-cli plugins link myplugin
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/link.ts)_

## `deploy-cli plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

```
USAGE
  $ deploy-cli plugins remove plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ deploy-cli plugins unlink
  $ deploy-cli plugins remove

EXAMPLES
  $ deploy-cli plugins remove myplugin
```

## `deploy-cli plugins reset`

Remove all user-installed and linked plugins.

```
USAGE
  $ deploy-cli plugins reset
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/reset.ts)_

## `deploy-cli plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

```
USAGE
  $ deploy-cli plugins uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ deploy-cli plugins unlink
  $ deploy-cli plugins remove

EXAMPLES
  $ deploy-cli plugins uninstall myplugin
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/uninstall.ts)_

## `deploy-cli plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

```
USAGE
  $ deploy-cli plugins unlink plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ deploy-cli plugins unlink
  $ deploy-cli plugins remove

EXAMPLES
  $ deploy-cli plugins unlink myplugin
```

## `deploy-cli plugins update`

Update installed plugins.

```
USAGE
  $ deploy-cli plugins update [-h] [-v]

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Update installed plugins.
```

_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v4.1.8/src/commands/plugins/update.ts)_

## `deploy-cli service deploy SERVICENAME`

Deploy a service

```
USAGE
  $ deploy-cli service deploy SERVICENAME

DESCRIPTION
  Deploy a service

EXAMPLES
  $ deploy-cli service deploy my-service
```

## `deploy-cli service logs SERVICENAME`

View the logs of a service

```
USAGE
  $ deploy-cli service logs SERVICENAME [-w]

FLAGS
  -w, --watch  Watch the logs

DESCRIPTION
  View the logs of a service

EXAMPLES
  $ deploy-cli service logs my-service
```

## `deploy-cli service ls`

List all services

```
USAGE
  $ deploy-cli service ls [--columns <value> | -x] [--filter <value>] [--no-header | [--csv | --no-truncate]]
    [--output csv|json|yaml |  | ] [--sort <value>]

FLAGS
  -x, --extended         show extra columns
      --columns=<value>  only show provided columns (comma-separated)
      --csv              output is csv format [alias: --output=csv]
      --filter=<value>   filter property by partial string matching, ex: name=foo
      --no-header        hide table header from output
      --no-truncate      do not truncate output to fit screen
      --output=<option>  output in a more machine friendly format
                         <options: csv|json|yaml>
      --sort=<value>     property to sort by (prepend '-' for descending)

DESCRIPTION
  List all services

EXAMPLES
  $ deploy-cli service ls
```

## `deploy-cli service rebuild SERVICENAME`

Force the rebuild of a service

```
USAGE
  $ deploy-cli service rebuild SERVICENAME

DESCRIPTION
  Force the rebuild of a service

EXAMPLES
  $ deploy-cli service rebuild my-service
```

## `deploy-cli service start SERVICENAME`

Start a service

```
USAGE
  $ deploy-cli service start SERVICENAME

DESCRIPTION
  Start a service

EXAMPLES
  $ deploy-cli service start my-service
```

## `deploy-cli service stop SERVICENAME`

Stop a service

```
USAGE
  $ deploy-cli service stop SERVICENAME

DESCRIPTION
  Stop a service

EXAMPLES
  $ deploy-cli service stop my-service
```

## `deploy-cli update [CHANNEL]`

update the deploy-cli CLI

```
USAGE
  $ deploy-cli update [CHANNEL] [-a] [--force] [-i | -v <value>]

FLAGS
  -a, --available        See available versions.
  -i, --interactive      Interactively select version to install. This is ignored if a channel is provided.
  -v, --version=<value>  Install a specific version.
      --force            Force a re-download of the requested version.

DESCRIPTION
  update the deploy-cli CLI

EXAMPLES
  Update to the stable channel:

    $ deploy-cli update stable

  Update to a specific version:

    $ deploy-cli update --version 1.0.0

  Interactively select version:

    $ deploy-cli update --interactive

  See available versions:

    $ deploy-cli update --available
```

_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v4.1.4/src/commands/update.ts)_
<!-- commandsstop -->