---

argument_specs:
  main:
    short_description: Docker container
    description: "Sets up a docker container. Supports defining networks, building a custom image, setting up memcached, databases and a reverse proxy, creating a user on the host to run the container as, named volumes, bind mounts (either auto-created or existing)."
    options:
      docker_service:
        description: "The name of the docker service (example: gitea)"
        type: str
        required: true
      docker_service_suffix:
        description: "A suffix used to allow running multiple instances of the same service on a host. If docker_service is gitea and docker_service_suffix production, the container will be gitea_production"
        type: str
        required: false
      docker_image:
        description: "Docker image to use for the container. If dockerfile is defined, it will be used as base for locally built image (example: gitea/gitea:latest)"
        type: str
        required: true
      dockerfile:
        description: "A list of dockerfile instructions to add to the base image"
        type: list
        elements: str
        required: false
        default: []
      docker_host_user:
        description: "If true, creates a user on the host for this service. The container will run as this user's uid/gid. Bind mount volumes will be owned by this user."
        type: bool
        required: false
        default: true

      docker_database:
        description: "Database type to set up. It will be run in a docker container accessible to the service at host <service name (with _suffix if suffix is defined)>_db on default port."
        type: str
        required: false
        choices:
          - postgres
          - mariadb
          - mongo
          - none
        default: none
      database_passwords:
        description: "database_passwords[docker_service] is a string with the password used for communication between the service and database. Required if docker_database is postgres or mariadb"
        type: dict
        required: false
      docker_mariadb_config:
        description: |
          A dict specifying config for mariadb. For example
          mysqld:
            innodb_buffer_pool_size: '4G'
            aria_pagecache_buffer_size': '4G'
          would set
          [mysqld]
          innodb_buffer_pool_size = 4G
          aria_pagecache_buffer_size = 4G
        type: dict
        required: false
        default: {}
      docker_additional_services:
        description: "List of additional services to configure (in separate containers). These will be accessible with hostname <docker_service_name>[_suffix]_<additional_service>"
        type: list
        required: false
        elements: str
        choices:
          - memcached
          - redis
        default: []
      docker_redis_persistence:
        description: Whether to save redis data to persistent storage
        type: bool
        required: false
        default: false
      docker_phpmyadmin_basicauth:
        description: Whether to enable basicauth for phpmyadmin
        type: bool
        required: false
        default: true
      docker_phpmyadmin_basicauth_users:
        description: Dict of users and their password hashes for phpmyadmin basic auth. Required if docker_phpmyadmin_basicauth is true and phpmyadmin is used.
        type: dict
        required: false
        default: {}

      docker_volume_type:
        description: "Defines whether to use named volumes or bind mounts for mounts with name"
        type: str
        required: false
        choices:
          - named
          - bind
        default: named
      docker_volumes:
        description: "DEPRECATED List of docker volumes to mount inside the container. Use docker_mounts instead. DEPRECATED"
        type: list
        required: false
        default: []
        elements: str
      docker_mounts:
        description: "List of bind mounts or volumes to be mounted inside the container. Each element is a dict with path and exactly one of name, src or template"
        type: list
        required: false
        default: []
        elements: dict
        options:
          path:
            description: "The path inside the container to mount at"
            type: str
            required: true
          name:
            description: "If docker_volume_type is named, the name of the named volume to be mounted at path. If docker_volume_type is bind, the name of the folder to create under /opt/<service>[/suffix]/mounts/ and mount at path."
            type: str
            required: false
          src:
            description: "Host path to bind mount inside the container."
            type: str
            required: false
          template:
            description: "Name of template without .j2 extension. Will be templated at /opt/<service>[/suffix]/mounts/<template> and mounted inside the container."
            type: str
            required: false
      reverse_proxy_type:
        description: "Defines which kind of reverse proxy to configure for the container. Traefik support is experimental."
        type: str
        required: false
        choices:
          - caddy
          - traefik
          - none
        default: caddy
      docker_image_http_port:
        description: "The port for http listener inside the container. Will be mapped to the host port defined in ports. Required if reverse_proxy_type is not none."
        type: int
        required: false
      docker_proxy_target_protocol:
        description: "Protocol to use for proxy connection"
        type: str
        required: false
        choices:
          - http
          - https
        default: http
      ports:
        description: "ports[docker_service]['http'] or ports[docker_service]['https'] defines the port on which the container will listen on for reverse proxy connections. Required if reverse_proxy_type is caddy. If ports[docker_service]['phpmyadmin'] is defined and docker_database is mariadb, phpmyadmin will is installed."
        type: dict
      docker_vhost_domains:
        description: "docker_vhost_domains[docker_service] is a list which defines which domains should be proxied to the container. Required if reverse_proxy_type is not none. docker_vhost_domains[docker_service + '_phpmyadmin'] is used for phpmyadmin"
        type: dict
      docker_published_ports:
        description: "A list of published ports in docker format (<host listen address>:<host port>:<container port>)"
        type: list
        required: false
        default: []
      docker_env:
        description: "A dict of environment variables for the container"
        type: dict
        required: false
        default: {}
      docker_entrypoint:
        description: "Docker entrypoint as list of command and arguments"
        type: list
        required: false
        elements: str
      docker_command:
        description: "Docker command as list of arguments or command and arguments"
        type: list
        required: false
        elements: str
      docker_network_mode:
        description: "Docker container network mode"
        type: str
        required: false
      timezone:
        description: "Timezone set in the TZ env var"
        type: str
        required: false
        default: Etc/UTC