### Web Server Setup with Routegroup and Middleware

Source: https://github.com/umputun/spot/blob/master/CLAUDE.md

This example shows how to set up an HTTP server using `routegroup` and apply middleware for recovery, throttling, and basic authentication. It also demonstrates defining routes and starting the server.

```go
router := routegroup.New(http.NewServeMux())
router.Use(rest.Recoverer(), rest.Throttle(), rest.BasicAuth())
router.Mount("/api").Route(func(r *routegroup.Bundle) {
    // Define routes here
})
srv := &http.Server{Addr: addr, Handler: router}
srv.ListenAndServe()
```

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

### Install and Test Go OLE Library

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/go-ole/go-ole/README.md

Instructions for installing the go-ole library, running tests, and executing an example program for Excel integration. This involves using `go get` and `go run` commands.

```bash
go get github.com/go-ole/go-ole
cd /path/to/go-ole/
go test

cd /path/to/go-ole/example/excel
go run excel.go
```

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

### Docker Setup for PostgreSQL

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/lib/pq/TESTS.md

Starts a PostgreSQL container using Docker, exposing the default PostgreSQL port. This is useful for setting up a test database environment.

```bash
docker run --expose 5432:5432 postgres
```

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

### Install Spot using deb package (Ubuntu/Debian)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs Spot on Ubuntu/Debian-based systems by downloading and installing a .deb package. Requires specifying the version and architecture.

```bash
wget https://github.com/umputun/spot/releases/download/<version>/spot_<version>_linux_<arch>.deb
sudo dpkg -i spot_<version>_linux_<arch>.deb
```

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

### Install and Run Local Go Doc Site

Source: https://github.com/umputun/spot/blob/master/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Installs the pkgsite tool and runs a local Go Doc site. This is useful for previewing package documentation locally before publishing.

```bash
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite
```

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

### Install Golang Color Library

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/fatih/color/README.md

This snippet shows how to install the color library using the go get command. It's a prerequisite for using the library's functionalities.

```bash
go get github.com/fatih/color
```

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

### Install Spot using Universal Install Script (Linux/macOS)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs the latest version of Spot on Linux and macOS using a universal installation script. The script detects the OS and architecture automatically. It's recommended to review the script before execution.

```bash
wget https://raw.githubusercontent.com/umputun/spot/master/install.sh
sudo sh install.sh
```

```bash
curl -sSfL https://raw.githubusercontent.com/umputun/spot/master/install.sh | sudo sh
```

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

### Install Spot using go install (Requires Go)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs Spot and spot-secrets binaries using the Go programming language's build tool. This method requires Go to be installed on the system.

```bash
go install github.com/umputun/spot/cmd/spot@latest
go install github.com/umputun/spot/cmd/spot-secrets@latest
```

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

### Run Spot Command Examples

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Demonstrates basic commands for running the Spot tool. Shows how to execute all tasks, a specific task, or a specific task for a specific target.

```bash
spot
```

```bash
spot --task=deploy-things
```

```bash
spot --task=deploy-things --target=prod
```

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

### Install Spot using rpm package (CentOS/RHEL/Fedora)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs Spot on RPM-based Linux distributions like CentOS, RHEL, Fedora, and AWS Linux. Requires downloading and installing an .rpm package.

```bash
wget https://github.com/umputun/spot/releases/download/v<version>/spot_v<version>_linux_<arch>.rpm
sudo rpm -i spot_v<version>_linux_<arch>.rpm
```

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

### Install pq Go Package

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/lib/pq/README.md

This command installs the pq PostgreSQL driver for Go using the go get command. It fetches the latest version of the package and makes it available for use in your Go projects.

```go
go get github.com/lib/pq
```

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

### Go Error Wrapping Example

Source: https://github.com/umputun/spot/blob/master/CLAUDE.md

Illustrates idiomatic Go error handling using `fmt.Errorf` with the `%w` verb for error wrapping, facilitating debugging by preserving the original error context.

```go
return fmt.Errorf("failed to process request: %w", err)
```

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

### Install Go-MySQL-Driver

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/go-sql-driver/mysql/README.md

Installs the Go-MySQL-Driver using the go tool. Requires Git to be installed and in the system's PATH.

```bash
go get -u github.com/go-sql-driver/mysql
```

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

### Spot Playbook - Full Format Example (YAML)

Source: https://context7.com/umputun/spot/llms.txt

An example of a comprehensive Spot playbook in YAML format. It defines multiple targets, tasks, and commands, including script execution, file copying, permission setting, service restarts, and health checks. It also shows error handling and task-specific configurations.

```yaml
# deploy.yml - Full playbook example
user: deploy
ssh_key: ~/.ssh/deploy_key
inventory: inventory.yml

targets:
  prod:
    hosts:
      - {host: "app1.example.com", name: "app1"}
      - {host: "app2.example.com", name: "app2", port: 2222}
  staging:
    groups: ["staging"]
  dev:
    names: ["devbox1", "devbox2"]
    tags: ["development"]

tasks:
  - name: deploy-application
    on_error: "curl -X POST https://slack.webhook/error -d 'Deploy failed: {SPOT_ERROR}'"
    commands:
      - name: backup current version
        script: |
          mkdir -p /var/backups/app
          cp -r /var/www/app /var/backups/app/$(date +%Y%m%d_%H%M%S)

      - name: upload new version
        copy: {"src": "dist/", "dst": "/var/www/app/", "mkdir": true}

      - name: set permissions
        script: |
          chown -R www-data:www-data /var/www/app
          chmod -R 755 /var/www/app
        options: {sudo: true}

      - name: restart service
        script: systemctl restart app.service
        options: {sudo: true}

      - name: health check
        wait: {"cmd": "curl -sf http://localhost:8080/health", "timeout": "60s", "interval": "2s"}

  - name: cleanup-old-deployments
    targets: ["prod"]
    commands:
      - name: remove old backups
        script: find /var/backups/app -maxdepth 1 -mtime +7 -type d -exec rm -rf {} \;
        options: {sudo: true}
```

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

### Install Spot using apk package (Alpine Linux)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs Spot on Alpine Linux using the apk package manager. This method involves downloading and adding the .apk package.

```bash
wget https://github.com/umputun/spot/releases/download/<version>/spot_<version>_linux_<arch>.apk
sudo apk add spot_<version>_linux_<arch>.apk
```

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

### Install Spot using Homebrew (macOS)

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs the Spot and spot-secrets binaries on macOS using the Homebrew package manager. This is a convenient method for macOS users.

```bash
brew tap umputun/apps
brew install umputun/apps/spot
```

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

### MySQL Connection String Examples

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/go-sql-driver/mysql/README.md

Demonstrates various formats for MySQL connection strings, including Unix sockets, TCP/IP with different hosts and ports, IPv6, and specific configurations like TLS and SQL modes. These examples cover common scenarios for connecting to different MySQL instances.

```text
user@unix(/path/to/socket)/dbname
```

```text
root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local
```

```text
user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true
```

```text
user:password@/dbname?sql_mode=TRADITIONAL
```

```text
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci
```

```text
id:password@tcp(your-amazonaws-uri.com:3306)/dbname
```

```text
user:password@unix(/cloudsql/project-id:region-name:instance-name)/dbname
```

```text
user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped
```

```text
user:password@/dbname
```

```text
user:password@/
```

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

### Install go-colorable Package

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/mattn/go-colorable/README.md

This command shows how to install the go-colorable package using the Go build tool. This is a prerequisite for using the package in your Go projects.

```bash
go get github.com/mattn/go-colorable
```

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

### Install Latest Development Version with Go Get

Source: https://github.com/umputun/spot/blob/master/site/docs/index.md

Installs the latest development versions of Spot and secrets using the 'go get' command. Requires Go 1.16+ to be installed. This method fetches directly from the master branch and may install unstable versions.

```bash
go install github.com/umputun/spot/cmd/spot@master
go install github.com/umputun/spot/cmd/secrets@master
```

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

### Install and Upgrade properties Go Library

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/magiconair/properties/README.md

Provides the command to install or upgrade the properties Go library to the latest version using the go get command.

```bash
go get -u github.com/magiconair/properties
```

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

### Install aec package

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/morikuni/aec/README.md

This command installs the aec Go package using the go get command. It fetches the package and its dependencies from the specified GitHub repository.

```bash
go get github.com/morikuni/aec
```

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

### Spot Playbook - Simplified Format Example (YAML)

Source: https://context7.com/umputun/spot/llms.txt

Illustrates a simplified Spot playbook structure in YAML for single-task deployments. This format uses a flat list of commands under a 'task' key, suitable for straightforward automation workflows.

```yaml
# simple-deploy.yml - Simplified playbook
user: deploy
ssh_key: ~/.ssh/deploy_key
targets: ["app1.example.com", "app2.example.com:2222"]

task:
  - name: pull latest code
    script: |
      cd /var/www/app
      git fetch origin
      git reset --hard origin/main

  - name: install dependencies
    script: |
      cd /var/www/app
      npm ci --production

  - name: build application
    script: |
      cd /var/www/app
      npm run build
    env: {NODE_ENV: production}

  - name: restart pm2
    script: pm2 restart app
```

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

### Install netdb Go Package

Source: https://github.com/umputun/spot/blob/master/vendor/modernc.org/libc/honnef.co/go/netdb/README.md

This snippet shows the command to install the netdb Go package using the go get command. It ensures you have the latest version of the package available for your project.

```sh
go get honnef.co/go/netdb
```

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

### Organize Go Imports

Source: https://github.com/umputun/spot/blob/master/CLAUDE.md

Demonstrates the standard Go import organization, prioritizing standard library, then third-party, and finally project-specific packages, separated by blank lines.

```go
import (
    "context"
    "fmt"
    "net/http"

    "github.com/go-pkgz/lgr"
    "github.com/jessevdk/go-flags"

    "github.com/umputun/spot/pkg/config"
)
```

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

### fsnotify Script Test Syntax Example

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/fsnotify/fsnotify/CONTRIBUTING.md

Demonstrates the syntax for creating test cases in the `testdata` directory. It shows how to define actions and their expected output using a shell-like format.

```shell
# Create a new empty file with some data.
watch /
echo data >/file

Output:
    create  /file
    write   /file
```

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

### Platform-Specific Test Example in fsnotify

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/fsnotify/fsnotify/CONTRIBUTING.md

Illustrates how to write platform-specific tests within the fsnotify test script format. This allows for testing behavior unique to certain operating systems like Windows.

```shell
watch /
touch /file

Output:
    # Tested if nothing else matches
    create    /file

    # Windows-specific test.
    windows:
        write  /file

You can specify multiple platforms with a comma (e.g. "windows, linux:").
"kqueue" is a shortcut for all kqueue systems (BSD, macOS).
```

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

### Inventory File Example with Groups (YAML)

Source: https://github.com/umputun/spot/blob/master/README.md

Demonstrates the structure of a Spot inventory file in YAML format when defining host groups. Each group can contain a list of hosts, with optional parameters like `host`, `name`, `port`, `user`, and `tags` for each host.

```yaml
groups:
  dev:
    - {host: "h1.example.com", name: "h1", tags:["us-east1", "vpc-1234567"]}
    - {host: "h2.example.com", port: 2233, name: "h2"}
    - {host: "h3.example.com", user: "user1"}
    - {host: "h4.example.com", user: "user2", name: "h4"}
  staging:
    - {host: "h5.example.com", port: 2233, name: "h5"}
    - {host: "h6.example.com", user: "user3", name: "h6"}
```

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

### Mock Generation using moq

Source: https://github.com/umputun/spot/blob/master/CLAUDE.md

This Go code comment illustrates the command to generate mocks for an interface using the `moq` tool. It specifies the output file, package, and the interface to mock.

```go
//go:generate moq -out mocks/accessor.go -pkg mocks -skip-ensure -fmt goimports . Accessor
```

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

### Run Spot Playbooks via CLI

Source: https://context7.com/umputun/spot/llms.txt

Demonstrates various ways to execute Spot playbooks using the command-line interface. Options include specifying playbooks, targets, tasks, concurrency, dry runs, verbose output, environment variables, SSH settings, and filtering commands.

```bash
# Run default playbook (spot.yml) on default target
spot

# Run specific playbook on production target
spot -p deploy.yml -t prod

# Run specific task with increased concurrency
spot -p deploy.yml -t prod -n deploy-app -c 4

# Dry run to preview commands without execution
spot -p deploy.yml -t prod --dry

# Run with verbose output and environment variables
spot -p deploy.yml -t prod -v -e VERSION:1.2.3 -e ENV:production

# Override SSH settings
spot -p deploy.yml -t prod -u deploy -k ~/.ssh/deploy_key --timeout=60s

# Run only specific commands from a task
spot -p deploy.yml -t prod --only="copy config" --only="restart service"

# Skip specific commands
spot -p deploy.yml -t prod -s "cleanup" -s "notify"

# Run all commands locally (no SSH)
spot -p deploy.yml --local

# Use with secrets provider
spot -p deploy.yml -t prod --secrets.provider=spot --secrets.key=mykey --secrets.conn=secrets.db
```

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

### VSCode YAML Schema Association

Source: https://github.com/umputun/spot/blob/master/schemas/README.md

This JSON configuration snippet is used within VSCode's settings.json file to associate specific YAML files with their corresponding JSON schemas. It requires the redhat.vscode-yaml plugin to be installed. The configuration maps schema URLs to file patterns, enabling schema validation and autocompletion for inventory.yml and spot.yml files.

```json
{
    "yaml.schemas": {
        "https://raw.githubusercontent.com/umputun/spot/master/schemas/inventory.json": "inventory.yml",
        "https://raw.githubusercontent.com/umputun/spot/master/schemas/playbook.json": "spot.yml"
    }
}
```

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

### DSN Format Examples

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/go-sql-driver/mysql/README.md

Illustrates the general and specific formats of a Data Source Name (DSN), including optional components and a minimal representation. It shows how to construct a DSN string for database connections.

```text
[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]
```

```text
username:password@protocol(address)/dbname?param=value
```

```text
/dbname
```

```text
/
```

```text
/dbname%2Fwithslash
```

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

### Dynamic Targets and Host Variables

Source: https://context7.com/umputun/spot/llms.txt

Illustrates dynamic target resolution using environment variables populated by scripts, and setting host-specific variables. This allows for flexible deployment targeting and configuration based on runtime information.

```yaml
# Dynamic target from variable
tasks:
  - name: discover target
    targets: ["default"]
    commands:
      - name: get deployment target
        script: |
          export TARGET_HOST=$(curl -s https://api.example.com/next-deploy-target)
        options: {local: true}

  - name: deploy to discovered host
    targets: ["$TARGET_HOST"]
    commands:
      - name: run deployment
        script: /opt/deploy.sh

# Variables with host-specific values
tasks:
  - name: configure per-host
    commands:
      - name: set host config
        script: |
          echo "hostname={SPOT_REMOTE_NAME}" > /etc/app/host.conf
          echo "address={SPOT_REMOTE_ADDR}" >> /etc/app/host.conf

      - name: register host-specific var
        script: |
          export CONFIG_${SPOT_REMOTE_NAME}="configured"
        register: ["CONFIG_{SPOT_REMOTE_NAME}"]
```

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

### Execute Single-Line Script with Environment Variables (YAML)

Source: https://github.com/umputun/spot/blob/master/README.md

Demonstrates how to execute a single-line script on a remote host using Spot. Environment variables can be defined and will be prepended to the command. This is useful for simple, one-off commands.

```yaml
commands:
    - name: some command
      script: ls -laR /tmp
      env: {FOO: bar, BAR: qux}
```

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

### Install ansible-vault-go package

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/sosedoff/ansible-vault-go/README.md

This command installs the ansible-vault-go package using the Go build tool. Ensure you have Go installed and configured correctly in your environment.

```bash
go get github.com/sosedoff/ansible-vault-go
```

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

### Connect to MySQL using Go's database/sql

Source: https://github.com/umputun/spot/blob/master/vendor/github.com/go-sql-driver/mysql/README.md

Demonstrates how to open a database connection using the Go-MySQL-Driver and the standard database/sql package. It also shows how to configure connection pool settings like max lifetime, max open connections, and max idle connections.

```go
import (
	"database/sql"
	"time"

	_ "github.com/go-sql-driver/mysql"
)

// ...

db, err := sql.Open("mysql", "user:password@/dbname")
if err != nil {
	panic(err)
}
// See "Important settings" section.
db.SetConnMaxLifetime(time.Minute * 3)
db.SetMaxOpenConns(10)
db.SetMaxIdleConns(10)
```