Tango - WORK IN PROGRESS !!

Tango is a docker-compose file generator and manager. It generates a docker compose file from a list of available preconfigured docker images and set up all needed network rules.

Tango is a command line tool written in bash.

---

Main features

• Generate and run a fully configured docker-compose file.

• Pick services from a list of preconfigured available modules (calibre, cloud9, codeserver,...) to be composed.

• Entirely configurable through environment variables and files.

• Use Traefik2 as a reverse proxy to set up network route to access the services.

• Take care automaticly of HTTPS certificate generation using Let's encrypt.

• Advanced special features :

  • Can isolate a specific service network into a VPN (aka attach a vpn to only one container).
  • Tango can switch between diffrent isolation context to manage them.

---

Requirements

• bash 4
• git
• docker engine
• a standard linux host OS
• a wildcard domain name that point to your host (*.domain.org)

---

Usage

Installation

• Installation on your linux host

  git clone https://github.com/StudioEtrange/tango
  cd tango
  ./tango install
  

Quickstart for a standalone context

• Launch a single firefox service

  ./tango --module firefox --domain domain.org --freeport up
  ./tango --module firefox --domain domain.org --freeport info
  

• Tango generates for each services an URI with the service name as subdomain name. Here : https://firefox.mydomain.org:port

• --module firefox : A ready-to-use service attached to current tango context be manageable by tango commands. (see available modules)

• up : tango action to generate a docker compose file, configured it including the selected services AND launch them.

• --freeport : pick for you available HTTP and HTTPS ports on your host to expose the service.

  • If you are on a local network area, do not forget to forward these ports to your tango IP hosts.
  • Alternative : use command line option --port main@<port>@<secured port> to choose ports by yourself (i.e --port main@80@443). Secured port is the HTTPS version of an HTTP port.

    ./tango --module firefox --domain domain.org --port main@80@443 up
    ./tango --module firefox --domain domain.org --port main@80@443 info
    

• --domain domain.org : Specify your wildcard domain name that point to your host.

  • Alternative : use --domain auto-nip for testing purpose if you do not have your own domain name. See domain name generation for more information.

    ./tango --module firefox --domain auto-nip --port main@80@443 up
    ./tango --module firefox --domain auto-nip --port main@80@443 info
    

Samples usage of Tango

• See samples

---

Available Commands

In most cases, you will have to use only tango management commands below.

* tango management.
    install : install/update Tango dependencies.
    up [service [-b]] [--module module] [--plugin plugin] [--freeport] : launch services.
    down [service] [--module module] [--all] : down services.
    restart [service] [--module module] [--plugin plugin] [--freeport] : restart services.
    info [service] [--module module] [--plugin plugin] [--freeport] [-v] : give info.
    status [service] : see service status
    logs [service] [-f] : see service logs
    modules|services|plugins list : list available modules, plugins or default defined services within your current context.

* advanced management
    update <service> [--module module] : pull last version of the defined docker tag image for the service. Do not update running service.
    shell <service> [--userroot] : launch a shell into a running service. Shell can be launched as root user.
    gen [--module module] [--plugin plugin] [--freeport] : generate compose & env files and create needed files & folders.
    plugins exec-service <service> : exec all plugin attached to a running service.
    plugins exec <plugin> :  exec a plugin into all running service attached.

*  various commands
    cert <path> --domain=<domain> : generate self signed certificate for a domain into a current host folder.
    letsencrypt rm : delete generated letsencrypt cert [WARN : delete certs will regenerate request to letsencrypt. Too much requests and you may be banned for a time]
    letsencrypt logs : follow letsencrypt actions
    letsencrypt test : test certificate generation using dns-challenge
    vendor <path> : copy tango into another path (inside a tango folder : <path>/tango), mainly to vendorize tango into another folder.

---

Services

Tango concepts

• A service is a containerized application (i.e sabnzbd, calibreweb, cloud9, codeserver,...), accessible through HTTP, configured and managed by tango. At core level, a service is a yml definition of a docker-compose file.

• A module is a ready-to-use service with a markdown description, a yml predefined compose file and a set of configurable variables in an environment file (see modules catalogue)

• Tango leverage services exposition mechanisms using traefik2. Tango automaticly set up all traefik2 rules and routes to provide access to services.

• see details in variables documentation

---

Context

• Tango can manage several contexts. However, it has a default context named 'tango'.

• A context is a set of services, a configuration file, default services within a given folder.

• Tango can manage a context by executing its cli command on it. By default tango commands are executed in tango context itself.

• see details in contexts

---

Configuration and variables

• TODO REVIEW THIS DOCUMENTATION

• You could set every tango variables through variables environment files or shell environment variables and some from command line.

• Tango use this resolution descending priority order for declared variables

  • Shell environment variables
  • Command line variables
  • User environment file variables
  • Modules environment file variables
  • Current context environment file variables
  • Default tango environment file variables

• see details in variables documentation

---

Network

• TODO REVIEW THIS DOCUMENTATION
• see details in variables documentation

---

GPU

• TODO REVIEW THIS DOCUMENTATION

• First, you will need nvidia-docker2 or nvidia-container-toolkit depending on your docker version

• To make a GPU available into some service declare it with SERVICE_GPU=INTEL_QUICKSYNC|NVIDIA (ie : PLEX_GPU=NVIDIA)

• About intel quicksync :

  • To confirm your host kernel supports the Intel Quick Sync feature, the following command can be executed on the host lspci -v -s $(lspci | grep VGA | cut -d" " -f 1) which should output Kernel driver in use: i915
  • If your Docker host also has a dedicated graphics card, the video encoding acceleration of Intel Quick Sync Video may become unavailable when the GPU is in use.

---

Troubleshooting

• Problem with a volume
  • May occurs when you move some folder with your data
  • FIX : delete docker volume with docker volume rm <volumename>
  • Sample :

    ERROR: Configuration for volume tango_shared_internal_data specifies "device" driver_opt /foo/folder/tango_shared, but a volume with the same name uses a different "device" driver_opt (/foo/bar/tango_shared). If you wish to use the new configuration, please remove the existing volume "tango_shared_internal_data" first:
    $ docker volume rm tango_shared_internal_data
    

---

Side notes

• Tango was created initially as a framework for mambo media stack

• Tango itself is written with a bash framework stella

• I cannot use 3.x docker compose version, while --runtime or --gpus are not supported in docker compose format (docker/compose#6691)

• Why Bash ? Because ^^