---

argument_specs:
  main:
    short_description: Docker service
    description: "Sets up a docker service. 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_namespace:
        description: The namespace of the service. This can be used when multiple containers should be part of the service. Used as the default network, the name of the directory where bind mounts are created and the prefix for volume names.
        type: str
        required: false
        default: "{{ docker_service }}"
      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 service will be gitea-production"
        type: str
        required: false
        default: ""
      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. For mariadb, you can also
          define database_passwords[docker_service + '_root'] if you want to
          set a password for the mariadb root user
        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_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
          readonly:
            description: "If true, volume will be mounted as read only inside the container. Only applies for named and src mounts."
            type: bool
            required: false
            default: false
          mode:
            description: "Permissions for the created/templated directory. Defaults to '0644' for files, '0755' for directories. Doesn't apply for named volumes."
            type: str
            required: false
          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 read only inside the container."
            type: str
            required: false
          copypath:
            description: "Name of file or directory to copy. Will be deployed from files/<copypath> to /opt/<service>[/suffix]/mounts/<copypath> and mounted read only 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_networks:
        description: A list of docker networks for docker service. Defaults to docker name
        type: list
        required: false
        default:
          - name: "{{ docker_namespace }}"
        elements: dict
        options:
          name:
            description: Name of the docker network
            type: str
            required: true
      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_memory:
        description: Memory limit for the container
        type: str
        required: false
      docker_restart_policy:
        description: Restart policy of the service
        type: str
        required: false
        default: always
      docker_network_mode:
        description: "Docker container network mode"
        type: str
        required: false
        default: ""
      timezone:
        description: "Timezone set in the TZ env var"
        type: str
        required: false
        default: Etc/UTC