Introduction

TSM is a comprehensive tool for managing Traefik proxy configurations in Docker environments. It provides a modern and efficient way to handle service discovery, certificate management, and auto-scaling for your Traefik services.

Key Features

• Service Discovery: Automatically discovers services from Docker Compose files
• Certificate Management: Flexible certificate generation and management with YAML configuration
• Auto-scaling: Prometheus-based monitoring and automatic service scaling
• Configuration Generation: Dynamic Traefik configuration based on service definitions
• User Management: Basic auth user file generation
• Docker Integration: Seamless integration with Docker and Docker Compose

Why TSM?

TSM simplifies the management of Traefik services by providing:

1. Automation: Reduces manual configuration and repetitive tasks
2. Consistency: Ensures uniform configuration across services
3. Scalability: Handles service scaling automatically based on metrics
4. Security: Manages certificates and authentication efficiently
5. Integration: Works seamlessly with existing Docker workflows

Getting Started

To get started with TSM, check out the Installation guide and follow the Quickstart tutorial.

Quickstart Guide

This guide will help you get started with TSM quickly. Follow these steps to set up and run your first service.

1. Install Dependencies

First, install the required dependencies:

tsm install-deps

2. Initialize Configuration

Initialize your configuration with your Docker Compose file:

tsm init-config -f docker-compose.yml

This will create the necessary configuration files in the proxy directory.

3. Configure Certificates

Edit the generated certificate configuration:

vim proxy/cert-config.yml

Then generate your certificates:

tsm generate-certs -c proxy/cert-config.yml

4. Generate Traefik Configuration

Generate the initial Traefik configuration:

tsm generate

For development, you can watch for changes:

tsm generate --watch

5. Launch Services

Start all your services:

tsm up

6. Monitor Services

Check the status of your services:

tsm status

To start auto-scaling monitoring:

tsm monitor

Example Docker Compose File

Here's a basic example of a Docker Compose file that works with TSM:

version: '3'

services:
  traefik:
    image: traefik:v2.10
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./proxy:/etc/traefik
    networks:
      - traefik

  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
    networks:
      - traefik

networks:
  traefik:
    external: true

Next Steps

• Learn more about CLI Commands
• Understand Certificate Management
• Explore advanced configuration options

Installation

TSM can be installed using several methods. Choose the one that best fits your needs.

Prerequisites

Before installing TSM, ensure you have:

• Docker installed and running
• Python 3.8 or higher (for pip installation)
• Basic understanding of Docker and Traefik concepts

Installation Methods

Using Homebrew (macOS/Linux)

brew install auser/tap/tsm

Using the Install Script

curl -LsSf https://raw.githubusercontent.com/auser/tsm/main/install.sh | sh

Using pip

pip install tsm

Post-Installation

After installation, you should:

1. Install dependencies:

   tsm install-deps
   

2. Verify the installation:

   tsm version
   

Next Steps

Once TSM is installed, proceed to the Quickstart guide to begin using TSM.

CLI Commands

TSM provides a comprehensive set of CLI commands for managing your Traefik services. Here are the most commonly used commands:

Generate Configuration

tsm generate [OPTIONS]

Options:
  --compose-file, -f PATH    Docker Compose file path
  --output-dir, -o PATH      Output directory for generated configs
  --domain-suffix, -d TEXT   Domain suffix for services
  --external-host TEXT       External host IP address
  --swarm-mode              Generate for Docker Swarm mode
  --watch, -w               Watch for file changes and regenerate

Discover Services

tsm discover [OPTIONS]

Options:
  --compose-file, -f PATH    Docker Compose file path

Scale Service

tsm scale SERVICE_NAME REPLICAS [OPTIONS]

Options:
  --compose-file, -f PATH    Docker Compose file path
  --update-config           Update Traefik config after scaling

Monitor Services

tsm monitor [OPTIONS]

Options:
  --compose-file, -f PATH    Docker Compose file path
  --scaling-config, -r PATH  Auto-scaling configuration file
  --prometheus-url, -p URL   Prometheus server URL
  --interval, -i SECONDS    Check interval in seconds
  --dry-run                Show what would be scaled without actually scaling

Show Service Status

tsm status [OPTIONS]

Options:
  --service, -s TEXT        Show status for specific service
  --detailed, -d           Show detailed information
  --format TEXT            Output format (table, json, yaml)

Initialize Configuration

tsm init-config [OPTIONS]

Options:
  --name, -n TEXT          Name of the project
  --environment, -e TEXT   Environment
  --compose-file, -f PATH  Docker Compose file path

Generate Certificates

tsm generate-certs [OPTIONS]

Options:
  --config, -c PATH        Path to certificate configuration YAML file
  --type TEXT             Certificate type: ca, server, client, peer, or all
  --name TEXT             Name for the certificate files
  --common-name TEXT      Common Name (CN) for the certificate
  --hosts TEXT            Comma-separated list of hosts for the cert
  --output-dir PATH       Base directory to write certs to

Install Dependencies

tsm install-deps

Generate Hosts File

tsm generate-hosts [OPTIONS]

Options:
  --compose-file, -f PATH  Docker Compose file path
  --ip TEXT               IP address to use for hosts entries
  --output, -o PATH      Output file for hosts block

Launch Services

tsm up [OPTIONS]

Options:
  --compose-file, -f PATH  Docker Compose file path

Clean Resources

tsm clean [OPTIONS]

Options:
  --all, -a              Clean all Docker resources
  --volumes              Remove volumes
  --networks             Remove networks

Show Version

tsm version

Certificate Management

TSM provides a flexible certificate management system that supports both command-line and YAML-based configuration.

Command Line Options

tsm generate-certs [OPTIONS]

Options:
  --config, -c PATH     Path to certificate configuration YAML file
  --type TEXT           Certificate type: ca, server, client, peer, or all
  --name TEXT           Name for the certificate files
  --common-name TEXT    Common Name (CN) for the certificate
  --hosts TEXT          Comma-separated list of hosts for the cert
  --output-dir PATH     Base directory to write certs to

YAML Configuration

The certificate configuration file (cert-config.yml) supports the following structure:

# Global defaults
defaults:
  common_name: "traefik"
  hosts: "localhost,127.0.0.1,traefik"
  domain: "example.com"
  profile: "server"
  permissions:
    mode: 0o644
    owner: "traefik"
    group: "traefik"

# CA Configuration
ca:
  generate: true
  name: "ca"
  common_name: "CA Name"
  hosts: "localhost,127.0.0.1"
  domain: "example.com"

# Individual Certificates
certificates:
  - name: "cert1"
    type: "server"
    common_name: "cert1"
    hosts: "localhost,127.0.0.1,cert1"
    permissions:
      mode: 0o600
      owner: "traefik"
      group: "traefik"

File Permissions

The certificate system supports flexible file permission management:

1. No permissions specified: No changes are made to file permissions
2. Only mode specified: Uses current user:group for ownership
3. Only owner specified: Uses current group
4. Full permissions: Sets mode, owner, and group

Example permission configurations:

# No permissions - no changes made
certificates:
  - name: "cert1"
    type: "server"
    common_name: "cert1"

# Only mode - uses current user:group
certificates:
  - name: "cert2"
    type: "server"
    permissions:
      mode: 0o600

# Only owner - uses current group
certificates:
  - name: "cert3"
    type: "server"
    permissions:
      owner: "traefik"

# Full permissions
certificates:
  - name: "cert4"
    type: "server"
    permissions:
      mode: 0o600
      owner: "traefik"
      group: "traefik"

Value Inheritance

Values are inherited in the following order (highest to lowest priority):

1. Certificate-specific configuration
2. CLI arguments
3. Environment variables
4. Global defaults

Certificate Bundles

Bundles allow you to group related certificates together. Each bundle can:

• Copy certificates from individual certificate definitions
• Apply its own permissions
• Override certificate names in the bundle

Example bundle:

bundles:
  example:
    - name: "bundle-cert1"
      source: "cert1"
      copy: true
      permissions:
        mode: 0o644
        owner: "traefik"
        group: "traefik"