### Set Up Virtual Environment and Install Requirements

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/testing.md

Creates a virtual environment named 'deployfish' for Python 3.11.9, sets it as the local environment, and installs project dependencies from requirements.txt. Ensure pyenv and pip are up-to-date.

```shell
pyenv virtualenv 3.11.9 deployfish
pyenv local deployfish
pip install --upgrade pip wheel
pip install -r requirements.txt
```

--------------------------------

### Install Cement

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Install the Cement framework, which is a prerequisite for developing deployfish plugins.

```bash
pip install cement
```

--------------------------------

### Terraform Configuration Example

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config_processors.md

Illustrates how to configure the terraform section in deployfish.yml to specify a state file and define lookups for dynamic values.

```yaml
terraform:
    statefile: s3://my-statefile
    lookups:
        cluster_name: 'prod-cluster-name'
```

--------------------------------

### Install Python Version

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/testing.md

Installs a specific Python version using pyenv. Ensure pyenv is installed and configured.

```shell
pyenv install 3.11.9
```

--------------------------------

### Basic deployfish.yml Configuration

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/intro.md

This is a minimal example of a `deployfish.yml` file defining an ECS service with load balancing, container specifications, and environment variables.

```yaml
services:
  - name: my-service
    environment: prod
    cluster: my-cluster
    count: 2
    load_balancer:
      service_role_arn: arn:aws:iam::123142123547:role/ecsServiceRole
      load_balancer_name: my-service-elb
      container_name: my-service
      container_port: 80
    family: my-service
    network_mode: bridge
    task_role_arn: arn:aws:iam::123142123547:role/myTaskRole
    containers:
      - name: my-service
        image: 123142123547.dkr.ecr.us-west-2.amazonaws.com/my-service:0.0.1
        cpu: 128
        memory: 256
        ports:
          - "80"
        environment:
          - ENVIRONMENT=prod
          - ANOTHER_ENV_VAR=value
          - THIRD_ENV_VAR=value
```

--------------------------------

### Install deployfish using pip

Source: https://github.com/caltechads/deployfish/blob/master/README.md

Installs the deployfish package using pip. It is recommended to use a Python virtual environment for installation.

```bash
pip install deployfish
```

--------------------------------

### YAML Example: Using Terraform Lookups in Service Definition

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Demonstrates how to replace service definition values with Terraform outputs using the `${terraform.lookup_key}` syntax.

```yaml
services:
  - name: my-service
    cluster: ${terraform.cluster_name}
    environment: prod
    count: 2
    service_role_arn: ${terraform.ecs_service_role}
    load_balancer:
      load_balancer_name: ${terraform.elb_name}
      container_name: my-service
      container_port: 80
    family: my-service
    network_mode: bridge
    task_role_arn: ${terraform.task_role_arn}
    vpc_configuration:
      security_groups: ${terraform.security_groups}
      subnets: ${terraform.subnets}
    containers:
      - name: my-service
        image: ${terraform.ecr_repo_url}:0.1.0
        cpu: 128
        memory: 256
        ports:
          - "80"
        environment:
          - S3_BUCKET=${terraform.storage_bucket}
```

--------------------------------

### Specifying Host and Container Ports

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial2.md

This example shows how to map a specific host port (8000) to a container port (80) for external access.

```yaml
ports:
  - "8000:80"
```

--------------------------------

### Example Service Definition with Helper Tasks

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Defines a complete service configuration including environment details, load balancing, container settings, and helper tasks for running commands like database migrations or index updates. This demonstrates how to associate specific commands with container tasks.

```yaml
services:
  - name: foobar-prod
    environment: prod
    cluster: foobar-prod-cluster
    count: 2
    service_role_arn: arn:aws:iam::123142123547:role/ecsServiceRole
    load_balancer:
      load_balancer_name: foobar-prod-elb
      container_name: foobar
      container_port: 80
    family: foobar-prod
    network_mode: bridge
    task_role_arn: arn:aws:iam::123142123547:role/myTaskRole
    execution_role: arn:aws:iam::123142123547:role/myExecutionRole
    containers:
      - name: foobar
        image: foobar:0.0.1
        cpu: 128
        memory: 512
        ports:
          - "80"
          - "443"
        environment:
          - ENVIRONMENT=prod
          - SECRETS_BUCKET_NAME=my-secrets-bucket
    tasks:
      - launch_type: FARGATE
        network_mode: awsvpc
        vpc_configuration:
          subnets:
            - subnet-1234
            - subnet-1235
          security_groups:
            - sg-12345
        schedule_role: arn:aws:iam::123142123547:role/ecsEventsRole
        containers:
          - name: foobar
            cpu: 128
            memory: 256
        commands:
          - name: migrate
            containers:
              - name: foobar
                command: ./manage.py migrate
          - name: update_index
            schedule: cron(5 * * * ? *)
            containers:
              - name: foobar
                command: ./manage.py update_index
```

--------------------------------

### Example deployfish.yml structure for ServiceHelperTaskAdapter

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

This YAML structure demonstrates how to define services with helper tasks, including general overrides and specific command configurations for containers.

```yaml
services:
  - name: foobar
    family: foobar
    network_mode: host
    task_role_arn: arn:aws:iam:23140983205498:role/task-role
    containers:
      - name: foo
        image: foo:1.2.3
        cpu: 128
        memory: 256
        environment:
            - ENVVAR1=bar
            - ENVVAR2=baz
    [...]

    tasks:
        # General overrides/settings that apply to all sub-tasks of this entry
        # There can be multiple entries if you need separate sets of global settings
        - family: foobar-helper1
          network_mode: bridge
          task_role_arn: arn:aws:iam:23140983205498:role/task-role2
          launch_type: FARGATE
          schedule_role: arn:aws:...
          vpc_configuration:
            subnets:
              - subnet-1
              - subnet-2
            security_groups:
              - sg-1
              - sg-2
            public_ip: true
          containers:
            - name: foo
              cpu: 256
              memory: 512
              logging:
                  driver: awslogs
          commands:
            - name: migrate
              containers:
                - name: foo
                  command: manage.py migrate
            - name: update_index
              schedule: cron(5 * * * ? *)
              containers:
                - name: foo
                  command: manage.py update_index
              command: manage.py update_index

```

--------------------------------

### Docker Label Definition Examples

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Shows the two formats for defining Docker labels in deployfish.yml (list of key=value or dictionary) and how they are transformed into the output dictionary format.

```yaml
labels:
    - FOO=bar
    - BAZ=bash
```

```yaml
labels:
    FOO: bar
    BAZ: bash
```

```json
{
    'FOO': 'bar',
    'BAZ': 'bash'
{
}
```

--------------------------------

### Example Usage of get_deployfish_replacements

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config_processors.md

Demonstrates how to retrieve deployfish replacement strings for a given section and item name. This is useful for understanding the available dynamic values within the configuration.

```default
If we have a ``services`` entry like this::

    services:
        - name: foobar-test
          environment: test
          cluster_name: foobar-cluster

and we do::

    processor.get_deployfish_replacement('services', 'foobar-test')

we get back::

    {
        '{name}': 'foobar-test',
        '{service-name}': 'foobar-test',
        '{environment}': 'test',
        '{cluster-name}': 'foobar-cluster',
    }

```

--------------------------------

### YAML Example: Environment Variable Replacement in Service Config

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Demonstrates how to inject shell environment variables into a service's configuration using the `${env.VAR}` syntax.

```yaml
services:
  - name: foobar-prod
    environment: prod
    config:
      - MY_PASSWORD=${env.MY_PASSWORD}
```

--------------------------------

### ServiceDiscoveryServiceAdapter Data Structure

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/service_discovery.md

Example of the expected data structure for initializing the ServiceDiscoveryServiceAdapter.

```json
{
    "namespace": "local",
    "name": "test",
    "dns_records": [
        {
            "type": "A",
            "ttl": "60"
        }
    ]
}
```

--------------------------------

### ServiceDiscoveryService get() method parameters

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/service_discovery.md

The 'pk' parameter for the get() method can be a service ID, a namespaced identifier, or just the service name.

```python
pk is one of:

* a service id, which starts with "srv-"
* a string like '{namespace_pk}:{service_name}'
* a string like '{service_name}'
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/testing.md

Executes all unit tests discovered by the Python unittest module. This command should be run after setting up the virtual environment and installing requirements.

```bash
python -m unittest discover
```

--------------------------------

### Get Service Information

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial1.md

This command retrieves and displays detailed information about a deployed service.

```bash
deploy info hello-world-test
```

--------------------------------

### YAML Example: Terraform Configuration with S3 Statefile

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Sets up the `terraform` section in `deployfish.yml` to use an S3-based Terraform state file for variable lookups.

```yaml
terraform:
  statefile: 's3://terraform-remote-state/my-service-terraform-state'
  lookups:
    ecs_service_role: 'ecs-service-role'
    cluster_name: '{service-name}-ecs-cluster-name'
    elb_name: '{service-name}-elb-name'
    storage_bucket: 's3-{environment}-bucket'
    task_role_arn: '{service-name}-task-role-arn'
    ecr_repo_url: 'ecr-repository-url'
```

--------------------------------

### Volume Definition Examples

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Shows the two forms of volume definitions in deployfish.yml: the new style referencing a named storage volume and the old style specifying host and container paths.

```yaml
volumes:
    - storage:/container/path
```

```yaml
volumes:
    - /host/path:/container/path
    - /host/path-ro:/container/path-ro:ro
```

--------------------------------

### Port Mapping Examples

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Illustrates the conversion of simple port strings or host:container mappings in deployfish.yml to the structured format required by AWS ECS task definitions.

```yaml
ports:
    - "80"
    - "8443:443"
    - "8125:8125/udp"
```

```json
[
    {"containerPort": 80, "protocol": "tcp"},
    {"containerPort": 443, "hostPort": 8443, "protocol": "tcp"},
    {"containerPort": 8125, "hostPort": 8125, "protocol": "udp"},
]
```

--------------------------------

### Example deployfish.yml Configuration

Source: https://github.com/caltechads/deployfish/blob/master/README.md

A basic configuration file for defining an ECS service with deployfish. This includes service name, environment, cluster details, load balancer configuration, network mode, task role, and container specifications.

```yaml
services:
  - name: my-service
    environment: prod
    cluster: my-cluster
    count: 2
    load_balancer:
      service_role_arn: arn:aws:iam::123142123547:role/ecsServiceRole
      load_balancer_name: my-service-elb
      container_name: my-service
      container_port: 80
    family: my-service
    network_mode: bridge
    task_role_arn: arn:aws:iam::123142123547:role/myTaskRole
    containers:
      - name: my-service
        image: 123142123547.dkr.ecr.us-west-2.amazonaws.com/my-service:0.0.1
        cpu: 128
        memory: 256
        memoryReservation: 128
        ports:
          - "80"
        environment:
          - ENVIRONMENT=prod
          - ANOTHER_ENV_VAR=value
          - THIRD_ENV_VAR=value
```

--------------------------------

### Environment Variable Definition Examples

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Demonstrates the two ways environment variables can be defined in deployfish.yml (list of key=value or dictionary) and their conversion to the AWS ECS task definition format.

```yaml
environment:
    - FOO=bar
    - BAZ=bash
```

```yaml
environment:
    FOO: bar
    BAZ: bash
```

```json
[
    {"name": "FOO", "value": "bar"},
    {"name": "BAZ", "value": "bash}"
]
```

--------------------------------

### YAML Example: Terraform Configuration with Terraform Enterprise

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Configures the `terraform` section for use with Terraform Enterprise, specifying workspace and organization instead of a statefile.

```yaml
terraform:
  workspace: sample_workspace
  organization: sampleOrganization
  lookups:
    ecs_service_role: 'ecs-service-role'
    cluster_name: '{service-name}-ecs-cluster-name'
    elb_name: '{service-name}-elb-name'
    storage_bucket: 's3-{environment}-bucket'
    task_role_arn: '{service-name}-task-role-arn'
    ecr_repo_url: 'ecr-repository-url'
    security_groups: '{service-name}-security-groups'
    subnets: 'service-subnets'
```

--------------------------------

### Using Terraform List and Map Outputs

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial5.md

Integrate Terraform outputs for lists and maps into service definitions. This example shows how to use lookups for 'security_groups' and 'load_balancer' configurations.

```yaml
terraform:
  statefile: 's3://hello-world-remotestate-file/hello-world-terraform-state'
  lookups:
    cluster_name: '{environment}-cluster-name'
    security_groups: 'service-security-groups'
    load_balancer: 'load-balancer-config'

services:
  - name: hello-world
    cluster: ${terraform.cluster_name}
    environment: prod
    count: 1
    load_balancer: ${terraform.load_balancer}
    vpc_configuration:
      security_groups: ${terraform.security_groups}
```

--------------------------------

### deployfish.main.maybe_do_cli_debugging

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/main.md

Enables client-style debugging for Python scripts if the '--debugpy' flag is present in the command line arguments. It facilitates remote debugging setup.

```APIDOC
## deployfish.main.maybe_do_cli_debugging

### Description
Enables client-style debugging by checking for the `--debugpy` flag in the provided arguments. If found, it attempts to connect to a remote debug server using `REMOTE_DEBUG_HOST` and `REMOTE_DEBUG_PORT` environment variables (defaulting to localhost:5678).

### Method
None (This is a function call)

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None (This function modifies behavior based on flags and environment variables, does not return a value.)

#### Response Example
None
```

--------------------------------

### Add a Custom Controller

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Example of creating a custom controller by inheriting from ReadOnlyCrudBase. It demonstrates setting metadata, defining model relationships, overriding help messages, and configuring Jinja2 for template rendering.

```python
from cement import ex
import click
from jinja2 import ChoiceLoader, Environment, PackageLoader

from deployfish.controllers.crud import ReadOnlyCrudBase
from myplugin.models.myplugin import MyPlugin

class MyPluginController(ReadOnlyCrudBase):

    class Meta:
        label = "myplugin"
        description = 'Work with MyPlugin'
        help = 'Work with MyPlugin'
        stacked_type = 'nested'

    model: Type[Model] = MyPlugin

    help_overrides: Dict[str, str] = {
        'exists': 'Show whether a MyPlugin exists in deployfish.yml',
        'list': 'List available MyPlugin from deployfish.yml',
    }

    info_template: str = 'detail--myplugin.jinja2'

    list_ordering: str = 'Name'
    list_result_columns: Dict[str, Any] = {
        'Name': 'name',
    }

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # Set up Jinja2 environment with a ChoiceLoader to load templates from the main application and the plugin
        self.jinja2_env = Environment(
            loader=ChoiceLoader([
                PackageLoader('deployfish', 'templates'),       # Load templates from the main application
                PackageLoader('myplugin', 'templates')          # Load templates from the plugin
            ])
        )
        # Import the color and section_title filters from deployfish.ext.ext_df_jinja2 in order to render the templates
        self.jinja2_env.filters['color'] = color
        self.jinja2_env.filters['section_title'] = section_title

    @ex(
        help='Show details about a MyPlugin.',
        arguments=[
            (['pk'], {'help': 'the name of the MyPlugin in deployfish.yml'})
        ],
    )
    @handle_model_exceptions
    def info(self) -> None:
        """
        Show details about a MyPlugin in AWS.
        """
        loader = self.loader(self)
        obj = loader.get_object_from_aws(self.app.pargs.pk)
        # Use the Jinja2 environment to render the template rather than the default Cement renderer that only takes
        # a local template name
        template = self.jinja2_env.get_template(self.info_template)
        self.app.print(template.render(obj=obj))
```

--------------------------------

### Deploying the Service

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial2.md

This command initiates the deployment of the 'hello-world-test' service to the configured cluster.

```bash
deploy create hello-world-test
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/contributing.md

Change into the project's directory after cloning.

```bash
cd deployfish
```

--------------------------------

### Install AWS CLI v2 on Mac

Source: https://github.com/caltechads/deployfish/blob/master/README.md

Installs AWS CLI v2 on a Mac system. This process involves uninstalling older versions, installing via Homebrew, and setting up the Session Manager plugin.

```bash
# Uninstall any old versions of the cli
pip uninstall awscli

# Deactivate any pyenv environment so we can be in the system-wide Python interpreter
cd ~

# Install the new AWS CLI from brew -- it's no longer pip installable
brew update
brew install awscli

# Install the Session Manager plugin
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
unzip sessionmanager-bundle.zip
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin
```

--------------------------------

### Deploy with Custom Configuration File

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial1.md

If your configuration file has a different name, use the '-f' flag to specify it when creating a service.

```bash
deploy -f myconfigfile.yml create hello-world-test
```

--------------------------------

### Creating Services for Environments

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial5.md

Create services for a specified environment using the 'deploy create' command. This command deploys the service configurations defined for that environment.

```bash
deploy create test
```

```bash
deploy create prod
```

--------------------------------

### EventTargetManager

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/events.md

Manages EventTarget resources. Allows for getting, listing, saving, and deleting event targets.

```APIDOC
## Class deployfish.core.models.events.EventTargetManager

### Description
Manages EventTarget resources. Allows for getting, listing, saving, and deleting event targets.

### Methods
#### get(pk: str, **kwargs) -> EventTarget
Retrieves a specific event target by its primary key.

#### list(rule: EventScheduleRule) -> Sequence[EventTarget]
Lists all event targets associated with a given event schedule rule.

#### delete(obj: Model, **_) -> None
Deletes an event target.

#### save(obj: Model, **_) -> None
Saves an event target.
```

--------------------------------

### Service Configuration with Ports, Command, and Environment

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial2.md

This configuration defines a service with a hello-world container, exposing port 80, setting a custom Docker command, and defining environment variables.

```yaml
services:
  - name: hello-world-test
    cluster: hello-world-cluster
    count: 1
    family: hello-world
    containers:
      - name: hello-world
        image: tutum/hello-world
        cpu: 128
        memory: 256
        ports:
          - "80"
        command: /usr/bin/supervisord
        environment:
          - VAR1=test
          - VAR2=anothervar
          - DEBUG=True
```

--------------------------------

### Update Service Configuration (Count)

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial3.md

Modify the service configuration to change the number of running containers, for example, to 2.

```default
services:
  - name: hello-world-test
    cluster: hello-world-cluster
    count: 2
    family: hello-world
    load_balancer:
    ...
```

--------------------------------

### SecretManager

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/secrets.md

Manages AWS SSM Parameter Store parameters, providing methods to get, list, save, and delete secrets.

```APIDOC
## class deployfish.core.models.secrets.SecretManager

Bases: [`Manager`](abstract.md#deployfish.core.models.abstract.Manager)

Manages our SSM Parameter Store parameters.

### Properties

* **service**: `str` = 'ssm'

### Methods

* **convert(parameter_data: dict[str, Any]) -> [Secret](#deployfish.core.models.secrets.Secret)**: Converts raw parameter data into a Secret object.
* **get(pk: str, **_) -> [Secret](#deployfish.core.models.secrets.Secret)**: Retrieves a single secret by its primary key.
* **get_many(pks: [list](abstract.md#deployfish.core.models.abstract.Manager.list)[str], **_) -> Sequence[[Secret](#deployfish.core.models.secrets.Secret)]**: Retrieves multiple secrets by their primary keys.
* **list_names(prefix: str) -> [list](abstract.md#deployfish.core.models.abstract.Manager.list)[str]**: Lists the names of all secrets under a given prefix.
* **list(prefix: str, decrypt: bool = True) -> Sequence[[Secret](#deployfish.core.models.secrets.Secret)]**: Lists all secrets under a given prefix, with an option to decrypt them.
* **save(obj: [Model](abstract.md#deployfish.core.models.abstract.Model), **_) -> str**: Saves a secret object to the parameter store.
* **delete_many_by_name(pks: [list](abstract.md#deployfish.core.models.abstract.Manager.list)[str]) -> None**: Deletes multiple secrets by their names.
* **delete(obj: [Model](abstract.md#deployfish.core.models.abstract.Model), **_) -> None**: Deletes a single secret object.
```

--------------------------------

### deployfish.main.main

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/main.md

The main entry point for the Deployfish CLI application.

```APIDOC
## deployfish.main.main

### Description
Main entry point for the Deployfish command-line interface application. This function orchestrates the application's startup and execution.

### Method
None (This is a function call)

### Endpoint
None

### Parameters
None

### Request Example
None

### Response
None
```

--------------------------------

### EventScheduleRuleManager

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/events.md

Manages EventScheduleRule resources. Provides methods for getting, listing, saving, deleting, enabling, and disabling event schedule rules.

```APIDOC
## Class deployfish.core.models.events.EventScheduleRuleManager

### Description
Manages EventScheduleRule resources. Provides methods for getting, listing, saving, deleting, enabling, and disabling event schedule rules.

### Methods
#### get(pk: str, **_) -> EventScheduleRule
Retrieves a specific event schedule rule by its primary key.

#### list() -> Sequence[EventScheduleRule]
Lists all available event schedule rules.

#### save(obj: Model, **_) -> str
Saves an event schedule rule.

#### delete(obj: Model, **_) -> None
Deletes an event schedule rule.

#### enable(obj: EventScheduleRule) -> None
If `obj` is disabled, change its state to "ENABLED". Otherwise, do nothing.

* **Parameters:**
  **obj** – the rule to enable

#### disable(obj: EventScheduleRule) -> None
If `obj` is enabled, change its state to "DISABLED". Otherwise, do nothing.

* **Parameters:**
  **obj** – the rule to disable
```

--------------------------------

### ECS Service Tasks Configuration

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Example of configuring helper tasks for an ECS service, including general overrides and container definitions.

```yaml
services:
    - name: foobar-prod
      ...

      tasks:
          # general overrides
        - network_mode: bridge
          task_role_arn: new task role
          containers:
```

--------------------------------

### Load Plugin and Register Hooks/Controllers

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Initializes the plugin by registering the custom controller, adding a template directory, and registering hooks. This code is typically placed in the plugin's main `__init__.py` file.

```python
import os

from cement import App

import myplugin.adapters  # noqa:F401

from .controllers.myplugin import MyPluginController
from .hooks import pre_config_interpolate_add_myplugin_section

__version__ = "0.0.1"


def add_template_dir(app: App):
    path = os.path.join(os.path.dirname(__file__), 'templates')
    app.add_template_dir(path)


def load(app: App) -> None:
    app.handler.register(MyPluginController)
    app.hook.register('post_setup', add_template_dir)
    app.hook.register('pre_config_interpolate', pre_config_interpolate_add_myplugin_section)
```

--------------------------------

### convert Method

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/abstract.md

Converts the adapter's data into the data structures needed to initialize a deployfish model.

```APIDOC
## convert

### Description
This method is the meat of the adapter – it is what takes `self.data` and returns the data structures needed to initialize our model. The return type varies by what the model needs.

### Method Signature
`convert() → tuple[dict[str, Any], dict[str, Any]]`

### Returns
A tuple containing two dictionaries: the converted data structures for model initialization.
```

--------------------------------

### Verify AWS CLI Version

Source: https://github.com/caltechads/deployfish/blob/master/README.md

Checks the installed version of the AWS CLI. This is useful for troubleshooting EXEC functionality, ensuring version 2 is being used.

```bash
aws --version
```

--------------------------------

### Deployfish Create Command with Environment File

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial4.md

Command to create a service, specifying an environment file to load variables into the runtime environment.

```default
deploy --env_file=config.env create hello-world-test
```

--------------------------------

### Generate Plugin Structure

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Use the Cement CLI to generate the basic directory structure for a new deployfish plugin.

```bash
cement generate plugin deployfish/plugins
```

--------------------------------

### Config.new

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config.md

Class method to create a new Config instance.

```APIDOC
## classmethod Config.new(**kwargs) -> Config

### Description
Creates a new Config instance.

### Parameters
* **kwargs** – Arbitrary keyword arguments passed to the Config constructor.
```

--------------------------------

### Config Class

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config.md

Initializes the Config class, reading the deployfish.yml file and handling variable substitutions.

```APIDOC
## class deployfish.config.config.Config(filename: str, raw_config: dict[str, Any] = None, boto3_session: Session = None)

### Description
This class reads our `deployfish.yml` file and handles the allowed variable substitutions in string values for service entries under the sections named in [`processable_sections`](#deployfish.config.config.Config.processable_sections).

Allowed variable substitutions:

* `${terraform.<lookup key>}`:  If we have a `terraform:` section in our YAML, replace this with the terraform lookup value for `<lookup key>`.
* `${env.<environment var>}``:  If the environment variable `<environment var>` exists in our environment, replace this with the value of that environment variable.

### Parameters
* **filename** – the path to our config file
* **Keyword Arguments**:
  * **raw_config** – if, supplied, use this as our config data instead of loading if from `filename`
```

--------------------------------

### Adapter Class Initialization

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/abstract.md

Initializes the Adapter with data from a data source. It converts the source data into appropriate data structures for initializing a deployfish model.

```APIDOC
## Adapter

### Description
Given a dict of data from a data source, convert it appropriate data structures to be used to initialize a deployfish model. Minimally this means translating the source data into the data structure returned by an apporpriate `describe_*` AWS API call. In more complicated cases, there may be additional data returned also.

### Class Signature
`deployfish.core.adapters.abstract.Adapter(data: dict[str, Any], partial: bool = False, **kwargs)`

### Parameters
* **data** (dict[str, Any]) - A dictionary containing data from a data source.
* **partial** (bool, optional) - Defaults to False. Indicates if the data is partial.
* **kwargs** - Additional keyword arguments.
```

--------------------------------

### Configure deployfish-slack Plugin

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/plugins/slack.md

Add this configuration stanza to your `~/.deployfish.yml` file to enable and configure the Slack plugin. Ensure you replace placeholders with your actual Slack token and channel.

```yaml
plugin.slack:
    enabled: true
    token: <your-slack-token>
    channel: <your-slack-channel>
```

--------------------------------

### Define Placement Constraints for Tasks

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Use the `placement_constraints` option to specify rules for task placement. This example shows constraints for distinct instances and filtering by instance type.

```yaml
tasks:
    - name: foobar-prod
      placement_constraints:
        - type: distinctInstance
        - type: memberOf
          expression: 'attribute:ecs.instance-type =~ t2.*'
```

--------------------------------

### Instantiate Model with Configuration

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/adapters.md

Generates a configured Model subclass instance using the extracted configuration and a specified adapter name.

```python
instance = MyModel.new(item_config, 'deployfish')
```

--------------------------------

### Entrypoint Configuration

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Specifies the entry point command for a container. Deployfish splits the string into an array for ECS.

```yaml
containers:
  - name: foo
    image: 123142123547.dkr.ecr.us-west-2.amazonaws.com/foo:0.0.1
    entrypoint: /entrypoint.sh here are arguments
```

--------------------------------

### Config.load_config

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config.md

Reads the deployfish.yml file from disk and returns it as parsed YAML.

```APIDOC
## method Config.load_config(filename: str) -> dict[str, Any]

### Description
Read our deployfish.yml file from disk and return it as parsed YAML.

### Parameters
* **filename** – the path to our deployfish.yml file

### Returns
The raw contents of the deployfish.yml file decoded to a dict
```

--------------------------------

### Get Cluster Information

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/advanced.md

Use this command to view detailed information about the EC2 instances that constitute your ECS cluster. This includes cluster status, instance details, and running services.

```bash
deploy cluster info web-test
```

--------------------------------

### restart

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/ecs.md

Restarts the running tasks for a service by terminating existing tasks and allowing ECS to start new ones. Supports immediate termination or a stabilized wait after each task kill.

```APIDOC
## restart

### Description
Restart the running tasks for a service. What this really means is kill off each task in the service and let ECS start new ones in their places.

### Method
Not applicable (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **hard** (bool) – if True, kill all tasks immediately; if False, wait for the service to stabilize after killing each task
* **waiter_hooks** (list[AbstractWaiterHook]) – a list of waiter hooks to use when invoking the ‘services_stable’ waiter

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### MyPluginAdapter Implementation

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Implement the `MyPluginAdapter` by inheriting from `deployfish.core.adapters.abstract.Adapter`. The `convert` method should return data and kwargs for the controller.

```python
from copy import deepcopy

from deployfish.core.adapters.abstract import Adapter


class MyPluginAdapter(Adapter):

    def convert(self):
        data = deepcopy(self.data)
        kwargs = {}
        return data, kwargs
```

--------------------------------

### Define Volumes for ECS Tasks

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Configure different types of volumes for your ECS tasks, including task-specific, shared, and host-mounted volumes. Ensure custom Docker volume drivers are installed on your ECS container machines.

```yaml
tasks:
  - name: foobar-prod
    cluster: foobar-prod
    volumes:
      - name: storage_task
        config:
          scope: task
          autoprovision: true
          driver: my_vol_driver:latest
      - name: storage
        config:
          scope: shared
          driver: my_vol_driver:latest
          driverOpts:
            opt1: value1
            opt2: value2
          labels:
            key: value
            key: value
      - name: local_storage
        path: /host/path
```

--------------------------------

### Enable Mysql Plugin

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/plugins/mysql.md

To enable the mysql plugin, add this stanza to your ~/.deployfish.yml file. This configures deployfish itself.

```yaml
plugin.mysql:
  enabled: true
```

--------------------------------

### Config.services

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config.md

Returns a list of services from the configuration.

```APIDOC
## property Config.services: list[dict[str, Any]]

### Description
Returns a list of services from the configuration.

### Returns
A list of service dictionaries.
```

--------------------------------

### Configure deployfish-sqs Plugin

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/plugins/sqs.md

Add this stanza to your `~/.deployfish.yml` to enable and configure the SQS plugin. You can specify multiple queues and optionally omit the AWS profile if using the default.

```yaml
plugin.sqs:
    enabled: true
    queue:
      - name: <your-sqs-queue-name>
        type: <your-sqs-message-type>
        profile: <your-aws-profile>
```

--------------------------------

### Show Service Config in AWS

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

View the current service configuration values in AWS using the 'deploy service config show' command.

```bash
deploy service config show hello-world-test
```

--------------------------------

### ECSService.create

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/controllers/service.md

Create an ECS Service in AWS from what is in deployfish.yml.

```APIDOC
## ECSService.create

### Description
Create an ECS Service in AWS from what is in deployfish.yml.

### Method
POST

### Endpoint
/service

### Parameters
#### Request Body
- **service_definition** (object) - Required - The definition of the ECS Service to create, as specified in deployfish.yml.

### Request Example
{
  "example": "{\"serviceName\": \"my-new-service\", \"clusterName\": \"my-cluster\", \"desiredCount\": 2, \"taskDefinition\": \"my-task-def:1\"}"
}

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the service was created.
- **details** (object) - Details of the created ECS Service.

#### Response Example
{
  "example": "{\"message\": \"ECS Service 'my-new-service' created successfully.\", \"details\": {\"serviceName\": \"my-new-service\", \"clusterName\": \"my-cluster\", \"desiredCount\": 2}}"
}
```

--------------------------------

### VpcConfigurationMixin

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ecs.md

Provides methods for retrieving VPC configurations.

```APIDOC
## class deployfish.core.adapters.deployfish.ecs.VpcConfigurationMixin

Bases: `object`

#### data *: dict[str, Any]*

#### get_vpc_configuration(source: dict[str, Any] = None) → dict[str, Any]


```

--------------------------------

### Initialize Model Instance

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/adapters.md

Initializes a Model instance using the converted data. This is typically done after the adapter has processed the configuration.

```python
instance = MyModel.__init__(data)
```

--------------------------------

### Write Config to AWS

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial4.md

Command to save the local configuration parameters to AWS Parameter Store.

```default
deploy config write hello-world-test
```

--------------------------------

### SSHTunnelAdapter.convert()

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/adapters/ssh.md

The convert method transforms the adapter's data into the required structures for model initialization. The specific output format depends on the model's needs.

```APIDOC
## SSHTunnelAdapter.convert()

### Description
This method is the core of the adapter, responsible for taking `self.data` and producing the data structures necessary for initializing a model. The exact structure of the returned data is determined by the requirements of the target model.

### Method
`convert()`

### Returns
tuple[dict[str, Any], dict[str, Any]] - A tuple containing two dictionaries, representing the transformed data.
```

--------------------------------

### Clone the Deployfish Repository

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/contributing.md

Clone your forked repository to your local machine. Replace 'your-username' with your actual GitHub username.

```bash
git clone git@github.com:your-username/deployfish.git
```

--------------------------------

### Config.tasks

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/config/config.md

Returns a list of tasks from the configuration.

```APIDOC
## property Config.tasks: list[dict[str, Any]]

### Description
Returns a list of tasks from the configuration.

### Returns
A list of task dictionaries.
```

--------------------------------

### Show Task Config in AWS

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

View the current task configuration values in AWS using the 'deploy task config show' command.

```bash
deploy task config show hello-world-test
```

--------------------------------

### deployfish.controllers.base.BaseServiceSecrets.sync

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/controllers/base.md

Synchronizes environment variables from deployfish.yml to specified environment files, creating backups of existing files.

```APIDOC
## deployfish.controllers.base.BaseServiceSecrets.sync

### Description
For each standalone task and service, if the task/service has an “env_file:” defined, export the ${{env.VAR}} related secrets to that “env_file:". Save a backup copy of the existing “env_file:".

### Method
None (This is a Python method, not an HTTP endpoint)

### Endpoint
None
```

--------------------------------

### Show Current Config in AWS

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial4.md

Command to view the current configuration parameters stored in AWS Parameter Store for a specific service.

```default
deploy config show hello-world-test
```

--------------------------------

### Bash Command: Import Environment Variables with --import_env

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Shows how to use the `--import_env` flag with the `deploy` command to make shell environment variables available for replacement.

```bash
deploy --import_env <subcommand> [options]
```

--------------------------------

### Container Command for Deployfish Entrypoint

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial4.md

Specifies the original command to be executed after deployfish entrypoint has set up the environment variables from AWS Parameter Store.

```default
command: /usr/bin/supervisord
```

--------------------------------

### Basic Service with Multiple Containers

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Defines a service with two containers, specifying their names, images, CPU, and memory requirements.

```yaml
services:
  - name: foobar-prod
    cluster: foobar-cluster
    count: 2
    containers:
      - name: foo
        image: my_repository/foo:0.0.1
        cpu: 128
        memory: 256
      - name: bar
        image: my_repository/baz:0.0.1
        cpu: 256
        memory: 1024
```

--------------------------------

### ServiceHelperTask.new

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/ecs.md

A factory method for creating ServiceHelperTask instances. It accepts an object, source, and additional keyword arguments for adapter use.

```APIDOC
## ServiceHelperTask.new

### Description
This is a factory method.

#### NOTE
The `**kwargs` here is for the Adapter to use, not for the Model constructor. So don’t be confused if kwargs are passed in here which do not get used on the model.

### Method
*classmethod*

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **obj** (any) - The object to create the task from.
* **source** (any) - The source of the object.
* **\*\*kwargs** - Additional keyword arguments for the adapter.

### Request Example
None

### Response
#### Success Response
* **ServiceHelperTask** - A new instance of ServiceHelperTask.

#### Response Example
None
```

--------------------------------

### SSHTunnelManager.list

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/api/models/ssh.md

Lists all SSHTunnels, optionally filtered by service name or port.

```APIDOC
## list(service_name: str = None, port: int = None)

### Description
Lists all SSHTunnels, optionally filtered by service name or port.

### Method
Not applicable (Python method)

### Parameters
#### Query Parameters
- **service_name** (str) - Optional - Filters the list by service name.
- **port** (int) - Optional - Filters the list by port number.

### Response
#### Success Response
- **Sequence[SSHTunnel]** - A sequence of SSHTunnel objects matching the filter criteria.
```

--------------------------------

### Enable Plugin in Deployfish Configuration

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/runbook/extending.md

Configuration snippet for `~/.deployfish.yml` to enable a custom plugin. This involves setting the plugin's key and enabling it.

```yaml
plugin.myplugin:
  enabled: true
```

--------------------------------

### Bash Command: Specify Environment File with --env_file

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/yaml.md

Illustrates using the `--env_file` option to load environment variables from a file, which must be in `VAR=VAL` format.

```bash
deploy --env_file=<filename> <subcommand> [options]
```

--------------------------------

### Dockerfile Entrypoint for Deployfish Entrypoint

Source: https://github.com/caltechads/deployfish/blob/master/docs/source/tutorial4.md

Sets the Docker container's entrypoint to the deployfish entrypoint command. This allows deployfish to manage environment variables from AWS Parameter Store.

```default
ENTRYPOINT ["deploy", "entrypoint"]
```