### Run Replica Detection Example Script (Shell)

Source: https://github.com/localrivet/dosync/blob/main/examples/README.md

This script automates the setup, execution, and cleanup of the replica detection example. It checks for Docker and Docker Compose, builds the example if necessary, starts Docker Compose services, runs the replica detector, and prompts for cleanup.

```shell
cd examples
./run_example.sh
```

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

### Scaling DOSync Fleet Example

Source: https://github.com/localrivet/dosync/blob/main/README.md

Illustrates how to scale the DOSync deployment by adding more servers or increasing the number of replicas per server. This demonstrates the horizontal scalability of the multi-server setup.

```bash
# Initial deployment
# 2 servers × 3 replicas = 6 total containers

# Add server 3
# 3 servers × 3 replicas = 9 total containers

# Add servers 4-5
# 5 servers × 3 replicas = 15 total containers

# Adjust replicas per server
# 5 servers × 5 replicas = 25 total containers
```

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

### Installing and Managing DOSync as a Systemd Service (bash)

Source: https://context7.com/localrivet/dosync/llms.txt

Provides commands to install the DOSync binary, start the systemd service, enable it for boot-time startup, check its status, and view logs. This ensures DOSync runs reliably in the background.

```bash
# Install DOSync binary
curl -sSL https://raw.githubusercontent.com/localrivet/dosync/main/install.sh | bash

# Start the service
sudo systemctl start dosync.service

# Enable automatic start on boot
sudo systemctl enable dosync.service

# Check service status
sudo systemctl status dosync.service

# View service logs
sudo journalctl -u dosync.service -f
```

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

### Starter Docker Compose Configuration for DOSync

Source: https://github.com/localrivet/dosync/blob/main/docs/getting-started.md

A minimal Docker Compose configuration to run DOSync as a service. It specifies the image, restart policy, volume mounts for Docker socket, configuration files, and environment variables for registry credentials and check interval.

```yaml
services:
  dosync:
    image: localrivet/dosync:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./docker-compose.yml:/app/docker-compose.yml
      - ./backups:/app/backups
      - ./dosync.yaml:/app/dosync.yaml # Mount your dosync.yaml config
    environment:
      - DOCKERHUB_USERNAME=${DOCKERHUB_USERNAME}
      - DOCKERHUB_PASSWORD=${DOCKERHUB_PASSWORD}
      - CHECK_INTERVAL=1m
```

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

### Install DOSync using Installation Script

Source: https://github.com/localrivet/dosync/blob/main/README.md

This bash command downloads and executes the DOSync installation script directly from GitHub. This is a convenient method for quickly setting up DOSync on a system.

```bash
curl -sSL https://raw.githubusercontent.com/localrivet/dosync/main/install.sh | bash
```

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

### Execute First DOSync Sync Command

Source: https://github.com/localrivet/dosync/blob/main/docs/getting-started.md

The command to run DOSync for the first time to check for updates and synchronize services. It requires a Docker Compose file as input.

```bash
dosync sync -f docker-compose.yml
```

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

### Start Docker Compose Services (Shell)

Source: https://github.com/localrivet/dosync/blob/main/examples/README.md

Manually starts the Docker Compose services defined in the docker-compose.yml file. This includes services like web, API, database, and cache, with replicas configured using scale properties, deploy directives, or naming conventions.

```shell
cd examples
docker-compose up -d
```

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

### Run Replica Detection Example (Bash)

Source: https://github.com/localrivet/dosync/blob/main/examples/replica-detection/README.md

Commands to navigate to the example directory and run the replica detection program. Supports running with default or specific Docker Compose files and services.

```bash
cd examples/replica-detection

go run main.go

go run main.go ../docker-compose.yml

go run main.go ../docker-compose.yml web
```

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

### Build and Install DOSync from Source

Source: https://github.com/localrivet/dosync/blob/main/README.md

This sequence of bash commands clones the DOSync repository, builds the binary using `make build`, and then installs it to `/usr/local/bin/dosync` with execute permissions. This method is useful for development or when needing the latest unreleased code.

```bash
git clone https://github.com/localrivet/dosync.git
cd dosync
make build
sudo cp ./release/$(go env GOOS)/$(go env GOARCH)/dosync /usr/local/bin/dosync
sudo chmod +x /usr/local/bin/dosync
```

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

### Minimal dosync.yaml Configuration

Source: https://github.com/localrivet/dosync/blob/main/docs/getting-started.md

A basic dosync.yaml file to configure registry credentials and backup settings. It specifies the Docker Hub username and password, and the directory and number of backups to keep.

```yaml
registry:
  dockerhub:
    username: ${DOCKERHUB_USERNAME}
    password: ${DOCKERHUB_PASSWORD}
backup:
  dir: ./backups
  keep: 5
```

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

### Tag Selection Policies

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Explains the different policies for selecting tags, including semver, numerical, and alphabetical, with examples of filtering and extraction.

```APIDOC
## Tag Selection Policies

### Description
This section describes the various policies used by DOSync to select the appropriate image tags based on filtering, extraction, and sorting criteria.

### Supported Policy Types

- **semver:** Selects tags based on semantic versioning, with optional version constraints.
- **numerical:** Selects tags based on extracted numbers (e.g., build numbers, timestamps).
- **alphabetical:** Selects tags based on lexicographical order (useful for date-based tags).

### Example: Semver Policy (Standard Tags)

```yaml
registry:
  dockerhub:
    imagePolicy:
      policy:
        semver:
          range: '>=1.0.0 <2.0.0' # Only 1.x versions
```

### Example: Semver Policy with Extraction

For tags like `v1.2.3-alpine3.17`:

```yaml
registry:
  ghcr:
    imagePolicy:
      filterTags:
        pattern: '^(?P<semver>[0-9]+\.[0-9]+\.[0-9]+)-.*'
        extract: '$semver'
      policy:
        semver:
          range: '>=1.0.0'
```

### Example: Numerical Policy (Build Timestamps)

For tags like `main-abc1234-1718435261`:

```yaml
registry:
  dockerhub:
    imagePolicy:
      filterTags:
        pattern: '^main-[a-fA-F0-9]+-(?P<ts>\d+)$'
        extract: 'ts'
      policy:
        numerical:
          order: desc # Highest timestamp wins
```

### Example: Alphabetical Policy (Date-Based Tags)

For tags like `RELEASE.2024-06-01T12-00-00Z`:

```yaml
registry:
  quay:
    imagePolicy:
      filterTags:
        pattern: '^RELEASE\.(?P<timestamp>.*)Z$'
        extract: '$timestamp'
      policy:
        alphabetical:
          order: desc # Most recent date wins
```

### Example: Filtering for Release Candidates Only

```yaml
registry:
  dockerhub:
    imagePolicy:
      filterTags:
        pattern: '.*-rc.*'
      policy:
        semver:
          range: ''
```

See [Architecture](architecture.md) for more on how tag selection fits into the update flow.
```

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

### Deploying DOSync via Docker Compose CLI

Source: https://github.com/localrivet/dosync/blob/main/README.md

Commands to deploy the Docker Compose setup on each server in the fleet. This involves cloning the infrastructure repository and running the Docker Compose command to start the services in detached mode.

```bash
# On each server (server1, server2, server3, etc.)
git clone your-infra-repo
cd your-infra-repo
docker compose up -d
```

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

### Cleanup Docker Containers (Bash)

Source: https://github.com/localrivet/dosync/blob/main/examples/replica-detection/README.md

Command to stop and remove Docker containers created for the replica detection example.

```bash
cd examples
docker-compose down
```

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

### Common Policy Example: Semantic Versioning (YAML)

Source: https://github.com/localrivet/dosync/blob/main/README.md

Examples of configuring image policies for standard semantic versioning tags. This includes selecting any version above a certain point, only stable 1.x versions, or including pre-releases.

```yaml
imagePolicy:
  policy:
    semver:
      range: '>=1.0.0' # Any version 1.0.0 or higher
```

```yaml
imagePolicy:
  policy:
    semver:
      range: '>=1.0.0 <2.0.0' # Only 1.x versions
```

```yaml
imagePolicy:
  policy:
    semver:
      range: '>=1.0.0-0' # Include pre-releases
```

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

### Common Policy Example: Date-based Releases (Minio) (YAML)

Source: https://github.com/localrivet/dosync/blob/main/README.md

An example policy for date-based release tags, similar to Minio's format. It filters tags using a regex to capture the timestamp and then uses alphabetical ordering (ascending) to select the earliest date in this format.

```yaml
imagePolicy:
  filterTags:
    pattern: '^RELEASE\.(?P<timestamp>.*)Z$'
    extract: '$timestamp'
  policy:
    alphabetical:
      order: asc # Ascending for dates in this format
```

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

### GHCR Configuration Example

Source: https://github.com/localrivet/dosync/blob/main/examples/ghcr-test/README.md

An example YAML configuration for GHCR integration within DOSync. It demonstrates how to specify the GitHub Personal Access Token (PAT) and optionally the username, along with an image policy for tag selection.

```yaml
registry:
  ghcr:
    token: "${GITHUB_PAT}"      # Required: GitHub Personal Access Token
    username: "localrivet"      # Optional: GitHub username
    imagePolicy:                # Optional: Tag selection policy
      policy:
        alphabetical:
          order: desc
```

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

### Common Policy Example: Build Pipeline Tags (YAML)

Source: https://github.com/localrivet/dosync/blob/main/README.md

An example of configuring an image policy for build pipeline tags that include a Git SHA and a timestamp. It uses numerical sorting based on the extracted timestamp to select the latest build.

```yaml
imagePolicy:
  filterTags:
    pattern: '^main-[a-fA-F0-9]+-(?P<ts>\d+)$'
    extract: 'ts'
  policy:
    numerical:
      order: desc # Highest timestamp wins
```

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

### Configure Registry Authentication for DOSync

Source: https://github.com/localrivet/dosync/blob/main/docs/troubleshooting.md

Provides two methods for configuring registry authentication in DOSync to resolve 'unauthorized' or 'failed to get tags' errors. The recommended approach involves mounting the Docker configuration file. Alternatively, credentials can be specified directly in the `dosync.yaml` file.

```yaml
dosync:
  image: localrivet/dosync:latest
  volumes:
    - /root/.docker/config.json:/root/.docker/config.json:ro  # Add this
    - /var/run/docker.sock:/var/run/docker.sock
    # ... other volumes
```

```yaml
# dosync.yaml
registry:
  ghcr:
    token: ${GITHUB_PAT}
    username: yourusername
```

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

### Docker Compose Scale-Based Replicas Example (YAML)

Source: https://github.com/localrivet/dosync/blob/main/README.md

Illustrates how Docker Compose's `scale` and `deploy.replicas` directives are used to create multiple instances (replicas) of a service. DOSync can detect these scale-based replicas for consistent updates.

```yaml
services:
  web:
    image: nginx:latest
    scale: 3 # Creates 3 replicas

  api:
    image: node:latest
    deploy:
      replicas: 2 # Creates 2 replicas using swarm mode syntax
```

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

### Enabling and Configuring Admin API

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Illustrates how to enable and configure the Admin API in DOSync. This includes enabling the API, specifying the listen address and port, and setting an authentication token for secure access.

```yaml
admin:
  enabled: true
  listen: 0.0.0.0:8080
  auth_token: ${ADMIN_TOKEN}
```

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

### Common Policy Example: Filtering Release Candidates (YAML)

Source: https://github.com/localrivet/dosync/blob/main/README.md

An example policy to filter and select only release candidate tags. It uses a regex pattern to identify tags containing '-rc' and then applies a semver policy without specific range constraints.

```yaml
imagePolicy:
  filterTags:
    pattern: '.*-rc.'
  policy:
    semver:
      range: ''
```

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

### Docker Compose Integration

Source: https://context7.com/localrivet/dosync/llms.txt

Instructions on how to run DOSync as a container within a Docker Compose setup, including necessary volume mounts and environment variables.

```APIDOC
## Docker Compose Integration

### Running DOSync as a Container

The recommended way to run DOSync alongside your application services.

### `docker-compose.yml` Example
```yaml
services:
  # Your application services
  webapp:
    image: ghcr.io/your-org/webapp:v1.0.0
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    image: gcr.io/your-project/api:v2.1.0
    ports:
      - "3000:3000"

  # DOSync service - monitors and updates other services
  dosync:
    image: localrivet/dosync:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./docker-compose.yml:/app/docker-compose.yml
      - ./backups:/app/backups
      - ./dosync.yaml:/app/dosync.yaml
      - ./.env:/app/.env:ro
    environment:
      - CONFIG_PATH=/app/dosync.yaml
      - ENV_FILE=/app/.env
      - SYNC_FILE=/app/docker-compose.yml
      - SYNC_INTERVAL=2m
      - SYNC_VERBOSE=true
      - SYNC_ROLLING_UPDATE=true
      - SYNC_STRATEGY=one-at-a-time
      - SYNC_HEALTH_CHECK=http
      - SYNC_HEALTH_ENDPOINT=/health
      - SYNC_ROLLBACK_ON_FAILURE=true
```

### Environment Variable Configuration

All sync flags can be set via environment variables.

### `.env` File Example
```bash
CONFIG_PATH=/app/dosync.yaml
ENV_FILE=/app/.env
SYNC_FILE=/app/docker-compose.yml
SYNC_INTERVAL=5m
SYNC_VERBOSE=true
SYNC_ROLLING_UPDATE=true
SYNC_STRATEGY=one-at-a-time
SYNC_HEALTH_CHECK=docker
SYNC_HEALTH_ENDPOINT=/health
SYNC_DELAY=30s
SYNC_ROLLBACK_ON_FAILURE=true

# Registry credentials
GITHUB_TOKEN=ghp_your_token_here
DOCKERHUB_USERNAME=myuser
DOCKERHUB_PASSWORD=mypassword
DOCR_TOKEN=dop_v1_your_token
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your_secret
```
```

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

### Traefik Configuration for Load Balancing

Source: https://github.com/localrivet/dosync/blob/main/README.md

Example Traefik configuration file (`traefik.yml`) for routing traffic to DOSync-managed services. It defines entry points for HTTP and HTTPS and enables Docker provider to discover services.

```yaml
# traefik.yml
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false
```

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

### Basic GitHub Container Registry (GHCR) Configuration (dosync.yaml)

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Basic configuration for authenticating with GitHub Container Registry (GHCR). It requires a personal access token and optionally accepts a username.

```yaml
registry:
  ghcr:
    token: "${GITHUB_TOKEN}"      # Required: GitHub Personal Access Token
    username: "myusername"        # Optional: GitHub username (defaults to token owner)
    imagePolicy:                  # Optional: Advanced tag selection
      policy:
        alphabetical:
          order: desc
```

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

### Image Policy Configuration (dosync.yaml)

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Defines how DOSync selects image tags for updates, including filtering based on regular expressions and applying versioning policies like semantic versioning ranges.

```yaml
imagePolicy:
  filterTags:
    pattern: '^v(?P<semver>[0-9]+\.[0-9]+\.[0-9]+)$'
    extract: '$semver'
  policy:
    semver:
      range: '>=1.0.0 <2.0.0'
```

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

### DOSync Basic Usage (Bash)

Source: https://github.com/localrivet/dosync/blob/main/README.md

Provides basic command-line examples for running the `dosync sync` command. It shows how to run with default settings, use an environment file for credentials, enable verbose output, and set a custom polling interval.

```bash
# Run manually with default settings
dosync sync -f docker-compose.yml

# Run with environment file and verbose output
dosync sync -e .env -f docker-compose.yml --verbose

# Run with custom polling interval (check every 5 minutes)
dosync sync -f docker-compose.yml -i 5m
```

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

### Configure Registry Credentials in .env File

Source: https://github.com/localrivet/dosync/blob/main/README.md

This example shows how to set up registry credentials using a `.env` file. It includes placeholders for tokens and passwords for various registries like DigitalOcean, Docker Hub, and AWS ECR. These variables can be used by DOSync for authentication.

```env
# DigitalOcean (only if using DigitalOcean Container Registry)
DO_TOKEN=your_digitalocean_token_here
# Docker Hub
DOCKERHUB_USERNAME=youruser
DOCKERHUB_PASSWORD=yourpassword
# AWS ECR
AWS_ACCESS_KEY_ID=yourkey
AWS_SECRET_ACCESS_KEY=yoursecret
# ...and so on for other registries
```

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

### Run DOSync in Docker Compose

Source: https://github.com/localrivet/dosync/blob/main/docs/usage.md

Starts the DOSync service as a container within a Docker Compose setup. This command assumes a 'docker-compose.yml' file is present and configured for a service named 'dosync'.

```bash
docker compose up -d dosync
```

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

### Build and Run Replica Detector (Go)

Source: https://github.com/localrivet/dosync/blob/main/examples/README.md

Builds the replica detector Go program from the source file and then runs it. Alternatively, it can be run directly using 'go run'. The program can optionally take the Docker Compose file path and a service name as arguments.

```go
# From project root
go build -o examples/replica_detector examples/replica_detection.go
cd examples
./replica_detector
```

```go
go run examples/replica_detection.go
```

```go
./replica_detector docker-compose.yml web
```

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

### Execute One-at-a-Time Deployment via CLI

Source: https://context7.com/localrivet/dosync/llms.txt

Demonstrates how to initiate a 'one-at-a-time' deployment using the DOSync command-line interface. This command specifies the configuration file and deployment parameters.

```bash
# CLI usage
dosync sync -f docker-compose.yml \
  --rolling-update \
  --strategy one-at-a-time \
  --health-check http \
  --health-endpoint /health \
  --delay 10s \
  --rollback-on-failure
```

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

### GHCR Authentication Error Message Examples

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Illustrates the difference in error messages for GHCR authentication failures between older and newer versions of DOSync. Newer versions provide more detailed and actionable error information.

```text
# Before (v0.1.4 and earlier):
Error getting tags for ghcr.io repo: API request failed with status code: 404

# After (v0.1.5+):
GHCR authentication failed for tax-equity/solar-equity-hub: invalid token or insufficient permissions (URL: https://ghcr.io/v2/tax-equity/solar-equity-hub/tags/list)
```

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

### Manage DOSync Services with Docker Compose

Source: https://github.com/localrivet/dosync/blob/main/docs/troubleshooting-dosync-deployment.md

Commands to manage DOSync services using Docker Compose, including stopping, starting, and restarting all services defined in the compose.prod.yaml file. These commands are essential for deployment and updates.

```bash
# Stop all services
cd /opt/solar-equity-hub
docker compose -f compose.prod.yaml down

# Start all services
docker compose -f compose.prod.yaml up -d

# Restart specific service
docker compose -f compose.prod.yaml restart dosync
```

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

### Bash Script for Initial Application Deployment

Source: https://github.com/localrivet/dosync/blob/main/docs/multi-server-architecture.md

This bash script outlines the initial deployment process for an application. It involves building a Docker image with a specific version tag, pushing it to a container registry (GHCR), and then waiting for DOSync instances to detect the new image and deploy it. The script includes a command to check the logs of the DOSync service on a server to verify the deployment status.

```bash
# 1. Push initial image
docker build -t ghcr.io/yourorg/app:v1.0.0 .
docker push ghcr.io/yourorg/app:v1.0.0

# 2. All DOSync instances detect and deploy
# Wait 2-3 minutes (polling interval)
# Check deployment status on any server:
ssh server1 "docker logs dosync"

```

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

### Create and Configure Stub Replica Manager for Testing (Go)

Source: https://github.com/localrivet/dosync/blob/main/internal/replica/README.md

Demonstrates how to create a stub replica manager for testing purposes in Go. It shows how to initialize the stub manager, access and configure stub detectors (ScaleBased and NameBased) with test data, and then use the stubbed manager to retrieve replicas. This is useful for isolating components and testing logic without actual Docker interactions.

```go
import (
	"fmt"
	replica "github.com/localrivet/dosync/internal/replica"
)

// Create a stub replica manager for testing
stubManager, err := replica.CreateStubReplicaManager("docker-compose.yml")
if err != nil {
    // Handle error
    fmt.Printf("Error creating stub manager: %v\n", err)
    return
}

// Access the stub detectors and configure them with test data
scaleDetector := stubManager.GetDetector(replica.ScaleBased).(*replica.StubScaleBasedDetector)
scaleDetector.Replicas = map[string][]replica.Replica{
    "web": {
        {ServiceName: "web", ReplicaID: "1", ContainerID: "container1", Status: "running"},
        {ServiceName: "web", ReplicaID: "2", ContainerID: "container2", Status: "running"},
    },
}

nameDetector := stubManager.GetDetector(replica.NameBased).(*replica.StubNamedServiceDetector)
nameDetector.Replicas = map[string][]replica.Replica{
    "database": {
        {ServiceName: "database", ReplicaID: "blue", ContainerID: "container3", Status: "running"},
        {ServiceName: "database", ReplicaID: "green", ContainerID: "container4", Status: "running"},
    },
}

// Use the stubbed manager in tests
replicas, err := stubManager.GetAllReplicas()
if err != nil {
    // Handle error
    fmt.Printf("Error getting all replicas: %v\n", err)
    return
}

fmt.Printf("Detected %d replicas using stub manager.\n", len(replicas))
```

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

### Perform Basic Health Check Using HealthChecker in Go

Source: https://github.com/localrivet/dosync/blob/main/internal/health/README.md

Demonstrates the basic usage of the `HealthChecker` interface in Go. It shows how to create a `HealthCheckConfig`, instantiate a `HealthChecker` (using a factory, assumed to be implemented elsewhere), and then perform a health check on a given `replica`. The output indicates whether the service is healthy or if an error occurred.

```go
// Create health check configuration
config := health.HealthCheckConfig{
    Type:             health.HTTPHealthCheck,
    Endpoint:         "/health",
    Port:             8080,
    Timeout:          time.Second * 5,
    RetryInterval:    time.Second,
    SuccessThreshold: 2,
    FailureThreshold: 3,
}

// Create health checker using factory (to be implemented in later subtasks)
checker, err := health.NewHealthChecker(config)
if err != nil {
    log.Fatalf("Failed to create health checker: %v", err)
}

// Check a replica's health
replica := replica.Replica{
    ServiceName: "web",
    ReplicaID:   "1",
    ContainerID: "container123",
    Status:      "running",
}

healthy, err := checker.Check(replica)
if err != nil {
    log.Fatalf("Health check failed: %v", err)
}

if healthy {
    fmt.Println("Service is healthy!")
} else {
    fmt.Println("Service is unhealthy!")
}
```

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

### Stop Docker Compose Services (Shell)

Source: https://github.com/localrivet/dosync/blob/main/examples/README.md

Stops and removes the Docker containers and networks created by Docker Compose. This is used for cleaning up resources after running the examples.

```shell
docker-compose down
```

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

### DOSync CLI Advanced Usage Examples

Source: https://github.com/localrivet/dosync/blob/main/docs/usage.md

Demonstrates advanced command-line usage for DOSync, including setting custom polling intervals, using alternative Docker Compose files, and enabling verbose output for debugging purposes.

```bash
dosync sync -f docker-compose.yml -i 2m
dosync sync -f my-stack.yml
dosync sync -f docker-compose.yml --verbose
```

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

### Download and Execute add-to-compose.sh Script

Source: https://github.com/localrivet/dosync/blob/main/README.md

This snippet downloads the `add-to-compose.sh` script from GitHub, makes it executable, and then runs it. This script is used to automatically add the DOSync service to an existing Docker Compose setup. Registry credentials can be provided as environment variables.

```bash
curl -sSL https://raw.githubusercontent.com/localrivet/dosync/main/add-to-compose.sh > add-to-compose.sh
chmod +x add-to-compose.sh
./add-to-compose.sh
```

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

### Manage DOSync as a Systemd Service (Bash)

Source: https://github.com/localrivet/dosync/blob/main/README.md

Provides essential bash commands for managing the DOSync systemd service. This includes starting, enabling on boot, checking status, and viewing logs. These commands are executed with root privileges using `sudo`.

```bash
# Start the service
sudo systemctl start dosync.service

# Enable automatic start on boot
sudo systemctl enable dosync.service

# Check service status
sudo systemctl status dosync.service

# View service logs
sudo journalctl -u dosync.service -f
```

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

### Metrics API

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Provides access to Prometheus-compatible metrics exposed by DOSync.

```APIDOC
## Metrics API

### Description
DOSync exposes a Prometheus-compatible metrics endpoint if enabled in `dosync.yaml`. This endpoint provides insights into sync operations, errors, and durations.

### Method
GET

### Endpoint
`/metrics`

### Query Parameters
None

### Request Body
None

### Request Example
`http://localhost:9090/metrics`

### Response
#### Success Response (200)
- **Metrics**: Prometheus-formatted time-series data.

#### Response Example
```
# HELP dosync_sync_count Total number of sync operations.
# TYPE dosync_sync_count counter
dosync_sync_count 150
# HELP dosync_sync_errors_total Total number of sync errors.
# TYPE dosync_sync_errors_total counter
dosync_sync_errors_total 5
```

### Configuration
Metrics can be enabled and configured in `dosync.yaml`:

```yaml
metrics:
  enabled: true
  listen: 0.0.0.0:9090
```

See `internal/metrics/` for implementation details.
```

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

### Admin API

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Endpoints for health checks, triggering syncs, and administrative actions.

```APIDOC
## Admin API

### Description
The Admin API provides endpoints for health checks, triggering manual syncs, and retrieving the current sync status. It is configurable via `dosync.yaml`.

### Base Endpoint
`/admin`

### Configuration
Admin API can be enabled and configured in `dosync.yaml`:

```yaml
admin:
  enabled: true
  listen: 0.0.0.0:8080
  auth_token: ${ADMIN_TOKEN}
```

### Endpoints

#### 1. Health Check

- **Method:** GET
- **Endpoint:** `/admin/health`
- **Description:** Performs a health check on the DOSync service.
- **Request Example:** `http://localhost:8080/admin/health`
- **Response:** `200 OK` if healthy.

#### 2. Trigger Manual Sync

- **Method:** POST
- **Endpoint:** `/admin/sync`
- **Description:** Triggers a manual synchronization process.
- **Request Example:** `http://localhost:8080/admin/sync`
- **Response:** `202 Accepted` indicating the sync has been initiated.

#### 3. Get Sync Status

- **Method:** GET
- **Endpoint:** `/admin/status`
- **Description:** Retrieves the current status of the synchronization process.
- **Request Example:** `http://localhost:8080/admin/status`
- **Response Example:**
  ```json
  {
    "status": "running",
    "lastSync": "2024-06-20T10:00:00Z"
  }
  ```

See `internal/health/` and `internal/manager/` for implementation details.
```

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

### Get Current Status

Source: https://context7.com/localrivet/dosync/llms.txt

Retrieves the current deployment status for all services managed by DOSync.

```APIDOC
## GET /api/v1/metrics/current

### Description
Returns the current deployment status for all services.

### Method
GET

### Endpoint
`/api/v1/metrics/current`

### Parameters
None

### Request Example
```bash
curl http://localhost:8080/api/v1/metrics/current
```

### Response
#### Success Response (200)
- **service_name** (string) - The name of the service.
- **version** (string) - The current deployed version of the service.
- **timestamp** (string) - The timestamp of the last deployment.
- **success** (boolean) - Indicates if the last deployment was successful.

#### Response Example
```json
{
  "webapp": {
    "service_name": "webapp",
    "version": "v2.0.1",
    "timestamp": "2024-01-15T10:30:00Z",
    "success": true
  },
  "api": {
    "service_name": "api",
    "version": "v3.1.0",
    "timestamp": "2024-01-15T09:15:00Z",
    "success": true
  }
}
```
```

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

### Run DOSync Environment Variable Expansion Test with Go

Source: https://github.com/localrivet/dosync/blob/main/examples/config-tests/README.md

This Go command executes the environment variable expansion test for DOSync configuration. It sets up test environment variables, loads configuration files (dosync-env-test.yaml and dosync-complex-env-test.yaml), verifies variable expansion, and reports the success or failure of each test case.

```bash
# Navigate to the config-tests directory
cd examples/config-tests

# Run the environment variable expansion test
go run main.go
```

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

### Dashboard API - Get Services with Metrics

Source: https://context7.com/localrivet/dosync/llms.txt

Retrieves a list of all services that are currently being monitored by DOSync.

```APIDOC
## Dashboard API

### Get Services with Metrics

Returns a list of all services being monitored.

### Method
GET

### Endpoint
`/api/v1/metrics/services`

### Request Example
```bash
curl http://localhost:8080/api/v1/metrics/services
```

### Response
#### Success Response (200)
- **services** (array of strings) - A list of service names.

#### Response Example
```json
["webapp", "api", "worker"]
```
```

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

### Run Unit and Integration Tests (Go)

Source: https://github.com/localrivet/dosync/blob/main/internal/replica/README.md

Details the commands for running tests within the package using the Go testing framework. It covers running unit tests only, running tests with verbose output, and running specific tests using patterns. Integration tests require Docker to be running and are skipped by default.

```bash
# Run unit tests only
go test ./internal/replica

# Run with verbose output
go test -v ./internal/replica

# Run specific test
go test -run TestNamedServiceRegexPatterns ./internal/replica
```

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

### Dashboard API - Get Deployment History

Source: https://context7.com/localrivet/dosync/llms.txt

Retrieves the deployment history for a specific service, supporting pagination and search parameters.

```APIDOC
### Get Deployment History

Returns deployment history for a specific service with pagination and search.

### Method
GET

### Endpoint
`/api/v1/metrics/history/{serviceName}`

### Query Parameters
- **limit** (integer) - Optional - The maximum number of deployments to return.
- **offset** (integer) - Optional - The number of deployments to skip before starting to collect the result set.

### Request Example
```bash
# Get last 50 deployments for webapp service
curl "http://localhost:8080/api/v1/metrics/history/webapp?limit=50&offset=0"
```

### Response
#### Success Response (200)
- **deployments** (array) - A list of deployment objects, each containing details like version, timestamp, status, etc.

#### Response Example
```json
{
  "deployments": [
    {
      "version": "v1.0.1",
      "timestamp": "2024-06-15T10:00:00Z",
      "status": "success"
    },
    {
      "version": "v1.0.0",
      "timestamp": "2024-06-10T09:00:00Z",
      "status": "success"
    }
  ]
}
```
```

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

### Get Service Statistics

Source: https://context7.com/localrivet/dosync/llms.txt

Retrieves deployment statistics for a specific service, including success rate, average deployment time, and rollback count.

```APIDOC
## GET /api/v1/metrics/stats/{service_name}

### Description
Returns deployment statistics for a given service, including success rate, average deployment time, and rollback count.

### Method
GET

### Endpoint
`/api/v1/metrics/stats/{service_name}`

### Parameters
#### Path Parameters
- **service_name** (string) - Required - The name of the service to retrieve statistics for.

### Request Example
```bash
curl http://localhost:8080/api/v1/metrics/stats/webapp
```

### Response
#### Success Response (200)
- **service** (string) - The name of the service.
- **success_rate** (number) - The success rate of deployments for the service.
- **avg_time** (number) - The average deployment time in seconds.
- **rollbacks** (integer) - The number of rollbacks performed for the service.

#### Response Example
```json
{
  "service": "webapp",
  "success_rate": 98.5,
  "avg_time": 45.2,
  "rollbacks": 2
}
```
```

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

### Name-Based Replica Detection Example (YAML)

Source: https://github.com/localrivet/dosync/blob/main/docs/architecture.md

Illustrates DOSync's ability to detect replicas based on naming conventions within the Docker Compose file. This is useful for strategies like blue-green deployments or manually numbered service instances.

```yaml
services:
  database-blue:
    image: postgres:latest
  database-green:
    image: postgres:latest
  cache-1:
    image: redis:latest
  cache-2:
    image: redis:latest
```

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

### GHCR Token Environment Variable

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Sets the GitHub Personal Access Token for GHCR authentication. This should be stored securely, typically in a `.env` file.

```env
# .env file
GITHUB_TOKEN=ghp_your_github_personal_access_token_here
```

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

### Configure Canary Deployment Strategy

Source: https://context7.com/localrivet/dosync/llms.txt

Sets up the 'canary' deployment strategy for DOSync, which deploys to a small subset of replicas first for validation before a full rollout. Includes percentage, health check, and delay configurations.

```yaml
strategy:
  type: canary
  percentage: 10  # Deploy to 10% of replicas first
  healthCheck:
    type: http
    endpoint: /health
  delayBetweenUpdates: 60s
  rollbackOnFailure: true
```

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

### Get Services with Metrics via API

Source: https://context7.com/localrivet/dosync/llms.txt

Retrieves a list of all services currently being monitored by DOSync through its dashboard API. This is useful for understanding the scope of monitored services.

```bash
curl http://localhost:8080/api/v1/metrics/services

# Response:
# ["webapp", "api", "worker"]
```

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

### Configure DOSync via Environment Variables

Source: https://context7.com/localrivet/dosync/llms.txt

Sets up DOSync's behavior and credentials using environment variables, overriding or complementing configuration files. Supports various sync parameters and registry authentication.

```bash
# .env file
CONFIG_PATH=/app/dosync.yaml
ENV_FILE=/app/.env
SYNC_FILE=/app/docker-compose.yml
SYNC_INTERVAL=5m
SYNC_VERBOSE=true
SYNC_ROLLING_UPDATE=true
SYNC_STRATEGY=one-at-a-time
SYNC_HEALTH_CHECK=docker
SYNC_HEALTH_ENDPOINT=/health
SYNC_DELAY=30s
SYNC_ROLLBACK_ON_FAILURE=true

# Registry credentials
GITHUB_TOKEN=ghp_your_token_here
DOCKERHUB_USERNAME=myuser
DOCKERHUB_PASSWORD=mypassword
DOCR_TOKEN=dop_v1_your_token
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your_secret
```

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

### Registry Credentials Environment Variables

Source: https://github.com/localrivet/dosync/blob/main/docs/configuration.md

Environment variables used to store sensitive credentials for various container registries. These should be set in your environment or a `.env` file for security.

```env
DO_TOKEN=your_digitalocean_token_here
DOCKERHUB_USERNAME=youruser
DOCKERHUB_PASSWORD=yourpassword
AWS_ACCESS_KEY_ID=yourkey
AWS_SECRET_ACCESS_KEY=yoursecret
GITHUB_TOKEN=your_github_personal_access_token
```