fix: Install folder path and update README.md

Author: hypolas

.env.example

@@ -1,36 +1,39 @@
-# Variables d'environnement pour Azure DevOps Agent
-# Copiez ce fichier vers .env et remplissez les valeurs
+# Environment variables for Azure DevOps Agent
+# Copy this file to .env and fill in the values
 
-# URL de votre organisation Azure DevOps
-AZP_URL=https://dev.azure.com/votre-organisation
+# Your Azure DevOps organization URL
+AZP_URL=https://dev.azure.com/your-organization
 
-# Token d'accès personnel (PAT) pour Azure DevOps
-# Doit avoir les permissions: Agent Pools (read, manage), Build (read), Code (read)
-# Alternative: utiliser AWS_REGION + AZURE_DEVOPS_TOKEN_SECRET_ARN
-AZP_TOKEN=votre-token-ici
+# Personal Access Token (PAT) for Azure DevOps
+# Must have permissions: Agent Pools (read, manage), Build (read), Code (read)
+# Alternative: use AWS_REGION + AZURE_DEVOPS_TOKEN_SECRET_ARN
+AZP_TOKEN=your-token-here
 
-# Pool d'agents Azure DevOps
+# Azure DevOps agent pool
 AZP_POOL=Default
 
-# Nom de base pour les agents (sera suffixé par -${AGENT_NUMBER}-${INSTANCE_ID})
+# Base name for agents (will be suffixed with -${AGENT_NUMBER}-${INSTANCE_ID})
 AZP_AGENT_NAME=docker-agent
 
-# Numéro d'agent (1 à 7) - fourni au lancement du conteneur
+# Agent number (1 to 7) - provided at container startup
 AGENT_NUMBER=1
 
-# === Variables optionnelles ===
+# === Optional variables ===
 
-# ID de l'instance AWS (récupéré automatiquement si non fourni)
+# AWS instance ID (automatically retrieved if not provided)
 # INSTANCE_ID=i-1234567890abcdef0
 
-# Configuration AWS Secrets Manager (recommandé pour la production)
+# AWS Secrets Manager configuration (recommended for production)
 # AWS_REGION=eu-west-1
 # AZURE_DEVOPS_TOKEN_SECRET_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:azure-devops-token-AbCdEf
 
-# Image de conteneur par défaut (optionnel)
+# Default container image (optional)
 DEFAULT_CONTAINER_IMAGE=ubuntu:22.04
 
-# Volumes par défaut (optionnel)
-# Pour Windows/Podman: pas de socket monté, utiliser DOCKER_HOST
-# Pour Docker Desktop: /var/run/docker.sock:/var/run/docker.sock
-DEFAULT_VOLUMES=/cache:/cache,/data:/data
+# Default volumes (optional)
+# For Windows/Podman: no socket mounted, use DOCKER_HOST
+# For Docker Desktop: /var/run/docker.sock:/var/run/docker.sock
+DEFAULT_VOLUMES=/cache:/cache,/data:/data
+
+# Installation folder for the agent
+INSTALL_FOLDER=/opt/azagent

Dockerfile

@@ -1,4 +1,4 @@
-# Stage 1: Extraire la version de l'agent
+# Stage 1: Extract agent version
 FROM ubuntu:22.04 AS temp-version
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -11,9 +11,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 RUN AGENT_VERSION=$(curl -s https://api.github.com/repos/microsoft/azure-pipelines-agent/releases/latest | grep -oP '"tag_name": "v\K(.*)(?=")') && \
     echo "$AGENT_VERSION" > /tmp/agent_version.txt && \
-    echo "Version détectée: $AGENT_VERSION"
+    echo "Detected version: $AGENT_VERSION"
 
-# Stage 2: Télécharger l'agent Azure DevOps
+# Stage 2: Download Azure DevOps agent
 FROM ubuntu:22.04 AS agent-downloader
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -27,25 +27,25 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=temp-version /tmp/agent_version.txt /tmp/agent_version.txt
 
 RUN AGENT_VERSION=$(cat /tmp/agent_version.txt) && \
-    echo "Téléchargement de l'agent Azure DevOps..." && \
-    echo "Version détectée: $AGENT_VERSION" && \
+    echo "Downloading Azure DevOps agent..." && \
+    echo "Detected version: $AGENT_VERSION" && \
     \
-    # Détecter l'architecture pour choisir le bon agent
+    # Detect architecture to choose the right agent
     ARCH=$(dpkg --print-architecture 2>/dev/null || uname -m) && \
     case "$ARCH" in \
         amd64|x86_64) AGENT_ARCH="x64" ;; \
         arm64|aarch64) AGENT_ARCH="arm64" ;; \
         armhf|armv7l|armv7) AGENT_ARCH="arm" ;; \
-        *) echo "⚠️ Architecture non supportée: $ARCH, utilisation de x64 par défaut" && AGENT_ARCH="x64" ;; \
+        *) echo "⚠️ Unsupported architecture: $ARCH, using x64 by default" && AGENT_ARCH="x64" ;; \
     esac && \
     \
-    echo "Architecture détectée: $ARCH -> Agent: linux-$AGENT_ARCH" && \
-    mkdir -p /opt/azagent/agent && \
+    echo "Detected architecture: $ARCH -> Agent: linux-$AGENT_ARCH" && \
+    mkdir -p /opt/dl && \
     curl -fsSL "https://download.agent.dev.azure.com/agent/$AGENT_VERSION/vsts-agent-linux-$AGENT_ARCH-$AGENT_VERSION.tar.gz" -o "/tmp/agent.tar.gz" && \
-    tar xzf "/tmp/agent.tar.gz" -C /opt/azagent/agent && \
+    tar xzf "/tmp/agent.tar.gz" -C /opt/dl && \
     rm "/tmp/agent.tar.gz"
 
-# Stage 3: Télécharger aws-ssm
+# Stage 3: Download aws-ssm
 FROM ubuntu:22.04 AS aws-ssm-downloader
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -63,7 +63,7 @@ COPY download-github-binary.sh /tmp/
 RUN chmod +x /tmp/download-github-binary.sh && \
     /tmp/download-github-binary.sh "hypolas/aws-ssm-light" "aws-ssm"
 
-# Stage 4: Télécharger Docker CLI
+# Stage 4: Download Docker CLI
 FROM ubuntu:22.04 AS docker-downloader
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -81,63 +81,63 @@ RUN curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /
     && apt-get install -y --no-install-recommends docker-ce-cli docker-compose-plugin \
     && rm -rf /var/lib/apt/lists/*
 
-# Stage final: Image runtime minimale
+# Final stage: Minimal runtime image
 FROM ubuntu:22.04
 
-# Éviter les questions interactives pendant l'installation
+# Avoid interactive prompts during installation
 ENV DEBIAN_FRONTEND=noninteractive
-# Installer seulement les dépendances runtime nécessaires
+# Install only necessary runtime dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
     sudo \
     jq \
     git \
-    # Dépendances .NET runtime pour l'agent Azure DevOps
+    # .NET runtime dependencies for Azure DevOps agent
     libicu70 \
     liblttng-ust1 \
     libssl3 \
     && rm -rf /var/lib/apt/lists/*
 
-# Copier les binaires depuis les stages de build
+# Copy binaries from build stages
 COPY --from=temp-version /tmp/agent_version.txt /tmp/agent_version.txt
-COPY --from=agent-downloader /opt/azagent/ /opt/azagent/
-COPY --from=agent-downloader /opt/azagent/agent/ /opt/azagent/agent/
+COPY --from=agent-downloader /opt/dl /opt/dl
+# COPY --from=agent-downloader /opt/azagent/agent/ /opt/azagent/agent/
 COPY --from=aws-ssm-downloader /usr/local/bin/aws-ssm /usr/local/bin/aws-ssm
 COPY --from=docker-downloader /usr/bin/docker /usr/bin/docker
 COPY --from=docker-downloader /usr/libexec/docker/cli-plugins/docker-compose /usr/libexec/docker/cli-plugins/docker-compose
 
-# Créer l'utilisateur azureagent
+# Create azureagent user
 RUN useradd -m -s /bin/bash azureagent \
     && usermod -aG sudo azureagent \
     && echo "azureagent ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates
 
-# Créer les répertoires nécessaires et ajuster les permissions
+# Create necessary directories and adjust permissions
 RUN mkdir -p /opt/setup-scripts \
     && mkdir -p /cache \
     && mkdir -p /data \
     && mkdir -p /usr/libexec/docker/cli-plugins \
-    && chown -R azureagent:azureagent /opt/azagent \
+    && chown -R azureagent:azureagent /opt/dl \
     && chown -R azureagent:azureagent /opt/setup-scripts \
     && chmod +x /usr/local/bin/aws-ssm \
     && chmod +x /usr/bin/docker \
     && chmod +x /usr/libexec/docker/cli-plugins/docker-compose
 
-# Installer les dépendances .NET de l'agent Azure DevOps au build
+# Install .NET dependencies for Azure DevOps agent at build time
 WORKDIR /opt/azagent
 RUN if [ -f "./bin/installdependencies.sh" ]; then \
-        echo "Installation des dépendances .NET de l'agent Azure DevOps..." && \
+        echo "Installing .NET dependencies for Azure DevOps agent..." && \
         ./bin/installdependencies.sh; \
     fi && \
     chown -R azureagent:azureagent /opt/azagent
 
-# Copier les scripts de configuration
+# Copy configuration scripts
 COPY scripts/ /opt/setup-scripts/
 RUN chmod +x /opt/setup-scripts/*.sh \
     && chown -R azureagent:azureagent /opt/setup-scripts
 
-# Variables d'environnement par défaut
+# Default environment variables
 ENV INSTALL_FOLDER="/opt/azagent"
 ENV AZP_URL=""
 ENV AZP_TOKEN=""
@@ -150,24 +150,20 @@ ENV AZURE_DEVOPS_TOKEN_SECRET_ARN=""
 ENV DEFAULT_CONTAINER_IMAGE="ubuntu:22.04"
 ENV DEFAULT_VOLUMES="/var/run/docker.sock:/var/run/docker.sock,/cache:/cache,/data:/data"
 
-# Exposer le répertoire de travail
-VOLUME ["/cache", "/data"]
-
-# Script d'entrée
+# Entrypoint script
 COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh \
     && chown -R azureagent:azureagent /opt/azagent
 
-# Ajouter des labels avec la version de l'agent
+# Add labels with agent version
 RUN AGENT_VERSION=$(cat /tmp/agent_version.txt 2>/dev/null || echo "unknown") && \
     echo "LABEL agent.version=$AGENT_VERSION" >> /tmp/labels.txt
 
-# Labels pour métadonnées
-LABEL maintainer="hypolas" \
-      description="Azure DevOps Agent avec intégration AWS Secrets Manager" \
+# Metadata labels
+LABEL maintainer="Nicolas HYPOLITE" \
+      description="Azure DevOps Agent with AWS Secrets Manager integration" \
       org.opencontainers.image.source="https://github.com/hypolas/azure-agent"
 
 USER azureagent
-WORKDIR /opt/azagent
 
 ENTRYPOINT ["/entrypoint.sh"]

README.md

@@ -17,10 +17,9 @@ This Docker image configures and runs an Azure DevOps agent with container suppo
 - `AZP_POOL`: Agent pool name
 - `AZP_AGENT_NAME`: Base agent name (will be suffixed with -${AGENT_NUMBER})
 - `AGENT_NUMBER`: **Mandatory** - Unique identifier for each agent instance. Required to avoid configuration conflicts when mounting Docker volumes on disk.
+- `INSTALL_FOLDER`: **Mandatory** - Agent installation directory. Must be identical in both environment variable and volume mount path.
 
 ## Optional Environment Variables
-
-- `INSTALL_FOLDER`: Agent installation directory (default: /opt/azagent)
 - `INSTANCE_ID`: AWS instance ID (automatically retrieved with IMDSv2 if not provided)
 - `AWS_REGION`: AWS region for Secrets Manager (ex: eu-west-1)
 - `AZURE_DEVOPS_TOKEN_SECRET_ARN`: ARN of AWS secret containing Azure DevOps token
@@ -78,7 +77,84 @@ docker run -d \
 
 ### With Docker Compose (Recommended)
 
-The provided `docker-compose.yml` file automatically configures 7 agents (instances 1 to 7):
+Use the provided `docker-compose.yml` file (using environment variables):
+
+```yaml
+version: '3.8'
+
+services:
+  azure-agent:
+    build:
+      context: .
+      args:
+        # aws-ssm installed by default (hypolas/aws-ssm-light)
+        INSTALL_AWS_SSM: "true"
+
+    container_name: azure-devops-agent
+    hostname: azure-agent
+
+    environment:
+      # Azure DevOps configuration (required)
+      - AZP_URL=${AZP_URL}
+      - AZP_POOL=${AZP_POOL}
+      - AZP_AGENT_NAME=${AZP_AGENT_NAME:-azure-agent}
+      - AGENT_NUMBER=${AGENT_NUMBER:-1}
+      - INSTALL_FOLDER=${INSTALL_FOLDER}
+
+      # AWS for token retrieval (if AZP_TOKEN not provided)
+      - AWS_REGION=${AWS_REGION}
+      - AZURE_DEVOPS_TOKEN_SECRET_ARN=${AZURE_DEVOPS_TOKEN_SECRET_ARN}
+
+      # Direct token (optional, takes priority over AWS)
+      - AZP_TOKEN=${AZP_TOKEN}
+
+      # Container configuration
+      - DEFAULT_CONTAINER_IMAGE=ubuntu:22.04
+      - DEFAULT_VOLUMES=/var/run/docker.sock:/var/run/docker.sock,/cache:/cache,/data:/data
+
+    volumes:
+      # Docker socket for builds
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${INSTALL_FOLDER}:${INSTALL_FOLDER}
+    restart: unless-stopped
+
+    # Healthcheck to verify agent is running
+    healthcheck:
+      test: ["CMD-SHELL", "pgrep -f 'Agent.Listener' || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+```
+
+#### ⚠️ Critical: INSTALL_FOLDER Consistency
+
+**The `INSTALL_FOLDER` value MUST be identical in both the environment variable and the volume mount path. This is MANDATORY for the agent to function properly.**
+
+```yaml
+# ✅ CORRECT - Same path in both places (using variable)
+environment:
+  - INSTALL_FOLDER=${INSTALL_FOLDER}
+volumes:
+  - ${INSTALL_FOLDER}:${INSTALL_FOLDER}
+
+# Example with .env file:
+# INSTALL_FOLDER=/opt/azagent
+
+# ❌ WRONG - Different paths will cause FAILURE
+environment:
+  - INSTALL_FOLDER=/opt/azagent
+volumes:
+  - /opt/agent:/opt/azagent  # ← Different path, agent will NOT work
+```
+
+**Why this matters:**
+- The agent creates its configuration inside `${INSTALL_FOLDER}/${AGENT_NUMBER}/`
+- The volume mount must map to the exact same path
+- Mismatched paths will prevent the agent from finding its configuration files
+- **The service will FAIL to start if paths don't match**
+
+**Deployment:**
 
 ```bash
 # Copy the example file