# Phase 2a — Deploy & Available Versions Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Allow admins to list available Docker image tags from Gitea registry and deploy a chosen version to an environment, all from the Central UI.

**Architecture:** Two new PHP services (GiteaRegistryService for tag listing via Docker Registry V2 API, DeployService for script execution via Symfony Process). Two new API Platform endpoints exposed via custom providers/processors. Frontend adds a deploy modal on the environment detail. Docker socket mounted for deploy script execution.

**Tech Stack:** PHP 8.4, Symfony 8, API Platform 4, Symfony HttpClient, Symfony Process, Nuxt 4, Vue 3

---

## File Structure

### Backend — Create

| File | Responsibility |
|------|---------------|
| `src/Service/GiteaRegistryService.php` | HTTP client for Gitea Docker Registry V2 API |
| `src/Service/DeployService.php` | Execute deploy.sh via Symfony Process |
| `src/ApiResource/TagList.php` | API Platform DTO for tag list response |
| `src/ApiResource/DeployResult.php` | API Platform DTO for deploy result response |
| `src/State/TagListProvider.php` | Provider that calls GiteaRegistryService |
| `src/State/DeployProcessor.php` | Processor that calls DeployService |

### Backend — Modify

| File | Change |
|------|--------|
| `.env` | Add GITEA_API_URL, GITEA_API_TOKEN |
| `docker-compose.yml` | Mount Docker socket in dev |
| `infra/prod/docker-compose.yml` | Mount Docker socket + deploy dirs in prod |
| `infra/prod/Dockerfile` | Install docker-cli in prod image |

### Frontend — Create

| File | Responsibility |
|------|---------------|
| `frontend/services/deploy.ts` | API calls for tags + deploy |
| `frontend/services/dto/deploy.ts` | TypeScript types for Tag and DeployResult |

### Frontend — Modify

| File | Change |
|------|--------|
| `frontend/pages/applications/[slug].vue` | Add deploy button + deploy modal |
| `frontend/i18n/locales/fr.json` | Deploy translation keys |

---

## Task 1: Environment variables and Docker config

**Files:**
- Modify: `.env`
- Modify: `docker-compose.yml`
- Modify: `infra/prod/docker-compose.yml`
- Modify: `infra/prod/Dockerfile`

- [ ] **Step 1: Add env vars to `.env`**

Add at the end of the file:

```
###> gitea ###
GITEA_API_URL=https://gitea.malio.fr
GITEA_API_TOKEN=change_me_in_env_local
###< gitea ###
```

- [ ] **Step 2: Mount Docker socket in dev docker-compose.yml**

In `docker-compose.yml`, add to the `php` service `volumes` list:

```yaml
      - /var/run/docker.sock:/var/run/docker.sock
```

- [ ] **Step 3: Mount Docker socket + deploy dirs in prod docker-compose**

In `infra/prod/docker-compose.yml`, add to the `app` service `volumes` list:

```yaml
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/www/sirh/deploy:/var/www/sirh/deploy:ro
      - /var/www/lesstime/deploy:/var/www/lesstime/deploy:ro
      - /var/www/inventory/deploy:/var/www/inventory/deploy:ro
```

- [ ] **Step 4: Install docker-cli in prod Dockerfile**

In `infra/prod/Dockerfile`, in the Stage 3 (production) `apt-get install` line, add `docker.io` to the list:

Replace:
```dockerfile
RUN apt-get update && apt-get install -y \
        libicu-dev libpq-dev libpng-dev libzip-dev libxml2-dev \
        nginx supervisor \
```

With:
```dockerfile
RUN apt-get update && apt-get install -y \
        libicu-dev libpq-dev libpng-dev libzip-dev libxml2-dev \
        nginx supervisor docker.io \
```

- [ ] **Step 5: Commit**

```bash
git add .env docker-compose.yml infra/prod/docker-compose.yml infra/prod/Dockerfile
git commit -m "feat : add Gitea env vars, mount Docker socket and deploy dirs"
```

---

## Task 2: GiteaRegistryService

**Files:**
- Create: `src/Service/GiteaRegistryService.php`

- [ ] **Step 1: Create the service**

```php
<?php

declare(strict_types=1);

namespace App\Service;

use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final readonly class GiteaRegistryService
{
    public function __construct(
        private HttpClientInterface $httpClient,
        #[Autowire('%env(GITEA_API_URL)%')]
        private string $giteaApiUrl,
        #[Autowire('%env(GITEA_API_TOKEN)%')]
        private string $giteaApiToken,
    ) {}

    /**
     * List available tags for a container image.
     *
     * @param string $registryImage e.g. "gitea.malio.fr/malio-dev/sirh"
     *
     * @return list<string>
     */
    public function listTags(string $registryImage): array
    {
        $parts = explode('/', $registryImage);

        if (\count($parts) < 3) {
            throw new \InvalidArgumentException(sprintf('Invalid registry image format: "%s". Expected "registry/owner/package".', $registryImage));
        }

        $owner = $parts[1];
        $package = implode('/', \array_slice($parts, 2));

        $url = sprintf('%s/v2/%s/%s/tags/list', $this->giteaApiUrl, $owner, $package);

        $response = $this->httpClient->request('GET', $url, [
            'headers' => [
                'Authorization' => sprintf('token %s', $this->giteaApiToken),
            ],
            'timeout' => 10,
        ]);

        $data = $response->toArray();

        $tags = $data['tags'] ?? [];

        // Sort: versions (vX.Y.Z) first descending, then others
        usort($tags, function (string $a, string $b): int {
            $aIsVersion = str_starts_with($a, 'v');
            $bIsVersion = str_starts_with($b, 'v');

            if ($aIsVersion && $bIsVersion) {
                return version_compare(ltrim($b, 'v'), ltrim($a, 'v'));
            }

            if ($aIsVersion) {
                return -1;
            }

            if ($bIsVersion) {
                return 1;
            }

            return strcmp($a, $b);
        });

        return $tags;
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add src/Service/GiteaRegistryService.php
git commit -m "feat : add GiteaRegistryService for listing container tags"
```

---

## Task 3: DeployService

**Files:**
- Create: `src/Service/DeployService.php`

- [ ] **Step 1: Create the service**

```php
<?php

declare(strict_types=1);

namespace App\Service;

use App\Entity\Environment;
use Symfony\Component\Process\Process;

final class DeployService
{
    /**
     * @return array{success: bool, output: string, exitCode: int}
     */
    public function deploy(Environment $environment, string $tag): array
    {
        $scriptPath = $environment->getDeployScriptPath();

        if (null === $scriptPath || !file_exists($scriptPath)) {
            return [
                'success' => false,
                'output' => sprintf('Deploy script not found: %s', $scriptPath ?? 'null'),
                'exitCode' => 1,
            ];
        }

        $process = new Process(
            ['bash', $scriptPath, $tag],
            dirname($scriptPath),
        );
        $process->setTimeout(300);

        $process->run();

        return [
            'success' => $process->isSuccessful(),
            'output' => $process->getOutput() . $process->getErrorOutput(),
            'exitCode' => $process->getExitCode() ?? 1,
        ];
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add src/Service/DeployService.php
git commit -m "feat : add DeployService for executing deploy scripts"
```

---

## Task 4: API Platform DTOs

**Files:**
- Create: `src/ApiResource/TagList.php`
- Create: `src/ApiResource/DeployResult.php`

- [ ] **Step 1: Create TagList DTO**

```php
<?php

declare(strict_types=1);

namespace App\ApiResource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use App\State\TagListProvider;

#[ApiResource(
    operations: [
        new Get(
            uriTemplate: '/applications/{slug}/tags',
            security: "is_granted('ROLE_ADMIN')",
            provider: TagListProvider::class,
        ),
    ],
)]
final class TagList
{
    /** @var list<string> */
    public array $tags = [];
}
```

- [ ] **Step 2: Create DeployResult DTO**

```php
<?php

declare(strict_types=1);

namespace App\ApiResource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use App\State\DeployProcessor;

#[ApiResource(
    operations: [
        new Post(
            uriTemplate: '/environments/{id}/deploy',
            security: "is_granted('ROLE_ADMIN')",
            processor: DeployProcessor::class,
        ),
    ],
)]
final class DeployResult
{
    public bool $success = false;
    public string $output = '';
    public string $tag = '';
}
```

- [ ] **Step 3: Commit**

```bash
git add src/ApiResource/TagList.php src/ApiResource/DeployResult.php
git commit -m "feat : add TagList and DeployResult API Platform DTOs"
```

---

## Task 5: TagListProvider

**Files:**
- Create: `src/State/TagListProvider.php`

- [ ] **Step 1: Create the provider**

```php
<?php

declare(strict_types=1);

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\ApiResource\TagList;
use App\Repository\ApplicationRepository;
use App\Service\GiteaRegistryService;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

final readonly class TagListProvider implements ProviderInterface
{
    public function __construct(
        private ApplicationRepository $applicationRepository,
        private GiteaRegistryService $giteaRegistryService,
    ) {}

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): TagList
    {
        $slug = $uriVariables['slug'] ?? '';
        $application = $this->applicationRepository->findOneBy(['slug' => $slug]);

        if (null === $application) {
            throw new NotFoundHttpException(sprintf('Application "%s" not found.', $slug));
        }

        $dto = new TagList();
        $dto->tags = $this->giteaRegistryService->listTags($application->getRegistryImage());

        return $dto;
    }
}
```

- [ ] **Step 2: Verify endpoint works**

```bash
# Login
docker exec -t php-central-fpm curl -s -c /tmp/cookies -X POST http://nginx/api/login_check \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# List tags (will fail if GITEA_API_TOKEN is not set in .env.local, that's expected in dev)
docker exec -t php-central-fpm curl -s -b /tmp/cookies http://nginx/api/applications/sirh/tags
```

- [ ] **Step 3: Commit**

```bash
git add src/State/TagListProvider.php
git commit -m "feat : add TagListProvider for listing registry tags"
```

---

## Task 6: DeployProcessor

**Files:**
- Create: `src/State/DeployProcessor.php`

- [ ] **Step 1: Create the processor**

```php
<?php

declare(strict_types=1);

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use App\ApiResource\DeployResult;
use App\Repository\EnvironmentRepository;
use App\Service\DeployService;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

final readonly class DeployProcessor implements ProcessorInterface
{
    public function __construct(
        private EnvironmentRepository $environmentRepository,
        private DeployService $deployService,
    ) {}

    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): DeployResult
    {
        $id = $uriVariables['id'] ?? null;
        $environment = $id ? $this->environmentRepository->find($id) : null;

        if (null === $environment) {
            throw new NotFoundHttpException(sprintf('Environment "%s" not found.', $id));
        }

        $requestData = $context['request']?->toArray() ?? [];
        $tag = $requestData['tag'] ?? null;

        if (null === $tag || '' === $tag) {
            throw new BadRequestHttpException('The "tag" field is required.');
        }

        $result = $this->deployService->deploy($environment, $tag);

        $dto = new DeployResult();
        $dto->success = $result['success'];
        $dto->output = $result['output'];
        $dto->tag = $tag;

        return $dto;
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add src/State/DeployProcessor.php
git commit -m "feat : add DeployProcessor for triggering deployments"
```

---

## Task 7: Frontend types and service

**Files:**
- Create: `frontend/services/dto/deploy.ts`
- Create: `frontend/services/deploy.ts`

- [ ] **Step 1: Create deploy types**

```typescript
type Tag = {
    name: string
}

type TagListResponse = {
    tags: string[]
}

type DeployResult = {
    success: boolean
    output: string
    tag: string
}
```

- [ ] **Step 2: Create deploy service**

```typescript
import type { TagListResponse, DeployResult } from './dto/deploy'

export function getAvailableTags(slug: string): Promise<TagListResponse> {
    return useApi().get<TagListResponse>(`/applications/${slug}/tags`, undefined, {
        toast: false,
    })
}

export function deploy(envId: number, tag: string): Promise<DeployResult> {
    return useApi().post<DeployResult>(`/environments/${envId}/deploy`, { tag }, {
        toast: false,
    })
}
```

- [ ] **Step 3: Commit**

```bash
git add frontend/services/dto/deploy.ts frontend/services/deploy.ts
git commit -m "feat : add frontend deploy types and service"
```

---

## Task 8: i18n translations

**Files:**
- Modify: `frontend/i18n/locales/fr.json`

- [ ] **Step 1: Add deploy translations**

Add the following keys to the existing `environments` section in `fr.json`:

```json
{
    "environments": {
        "...existing keys...",
        "deploy": {
            "button": "Deployer",
            "title": "Deployer une version",
            "selectTag": "Version a deployer",
            "selectPlaceholder": "Selectionner une version",
            "loadingTags": "Chargement des versions...",
            "noTags": "Aucune version disponible",
            "confirm": "Deployer",
            "deploying": "Deploiement en cours...",
            "success": "Deploiement reussi",
            "error": "Echec du deploiement",
            "output": "Sortie du deploiement"
        }
    }
}
```

Also add error keys:

```json
{
    "errors": {
        "...existing keys...",
        "deploy": {
            "tags": "Erreur lors du chargement des versions",
            "deploy": "Erreur lors du deploiement"
        }
    }
}
```

- [ ] **Step 2: Commit**

```bash
git add frontend/i18n/locales/fr.json
git commit -m "feat : add i18n translations for deploy feature"
```

---

## Task 9: Deploy modal and button on detail page

**Files:**
- Modify: `frontend/pages/applications/[slug].vue`

- [ ] **Step 1: Add imports and deploy state**

At the top of `<script setup>`, add the imports after existing ones:

```typescript
import type { DeployResult } from '~/services/dto/deploy'
import { getAvailableTags, deploy } from '~/services/deploy'
```

Add state variables after the existing ones (after `pendingMaintenanceByEnvId`):

```typescript
// Deploy modal
const showDeployModal = ref(false)
const deployEnvId = ref<number | null>(null)
const deployTags = ref<string[]>([])
const selectedTag = ref('')
const loadingTags = ref(false)
const isDeploying = ref(false)
const deployResult = ref<DeployResult | null>(null)
```

- [ ] **Step 2: Add deploy functions**

Add these functions after `removeLogFile`:

```typescript
async function openDeployModal(env: Environment) {
    deployEnvId.value = env.id!
    selectedTag.value = ''
    deployResult.value = null
    deployTags.value = []
    showDeployModal.value = true
    loadingTags.value = true
    try {
        const response = await getAvailableTags(slug)
        deployTags.value = response.tags ?? []
        if (deployTags.value.length > 0) {
            selectedTag.value = deployTags.value[0]
        }
    } finally {
        loadingTags.value = false
    }
}

async function handleDeploy() {
    if (!deployEnvId.value || !selectedTag.value) return
    isDeploying.value = true
    deployResult.value = null
    try {
        deployResult.value = await deploy(deployEnvId.value, selectedTag.value)
        if (deployResult.value.success) {
            await loadApplication()
        }
    } finally {
        isDeploying.value = false
    }
}

function closeDeployModal() {
    showDeployModal.value = false
    deployResult.value = null
}
```

- [ ] **Step 3: Add deploy button to each environment**

In the template, in the environment action buttons area (the `<div class="flex gap-2">` that contains the maintenance toggle button), add a deploy button before the maintenance button:

```vue
                            <MalioButton
                                :label="t('environments.deploy.button')"
                                icon-name="mdi:rocket-launch-outline"
                                icon-position="left"
                                @click="openDeployModal(env)"
                            />
```

- [ ] **Step 4: Add deploy modal to template**

Add after the existing environment modal (before the closing `</div>` of the root template):

```vue
        <!-- Deploy modal -->
        <AppModal
            v-model="showDeployModal"
            :submit-label="isDeploying ? t('environments.deploy.deploying') : t('environments.deploy.confirm')"
            :cancel-label="t('applications.form.cancel')"
            :loading="isDeploying"
            max-width="xl"
            @submit="handleDeploy"
            @update:model-value="!$event && closeDeployModal()"
        >
            <template #title>{{ t('environments.deploy.title') }}</template>

            <!-- Tag selection -->
            <div v-if="!deployResult">
                <div v-if="loadingTags" class="py-8 text-center text-neutral-400">
                    <Icon name="mdi:loading" size="24" class="animate-spin" />
                    <p class="mt-2 text-sm">{{ t('environments.deploy.loadingTags') }}</p>
                </div>

                <div v-else-if="deployTags.length === 0" class="py-8 text-center text-neutral-400">
                    <Icon name="mdi:package-variant" size="32" />
                    <p class="mt-2 text-sm">{{ t('environments.deploy.noTags') }}</p>
                </div>

                <div v-else>
                    <label class="mb-1 block text-sm font-medium text-neutral-700">
                        {{ t('environments.deploy.selectTag') }}
                    </label>
                    <select
                        v-model="selectedTag"
                        class="w-full rounded-md border border-neutral-300 px-3 py-2 text-sm focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500"
                    >
                        <option v-for="tag in deployTags" :key="tag" :value="tag">
                            {{ tag }}
                        </option>
                    </select>
                </div>
            </div>

            <!-- Deploy result -->
            <div v-else>
                <div
                    class="mb-4 flex items-center gap-2 rounded-lg px-4 py-3"
                    :class="deployResult.success
                        ? 'bg-green-50 text-green-700'
                        : 'bg-red-50 text-red-700'"
                >
                    <Icon
                        :name="deployResult.success ? 'mdi:check-circle' : 'mdi:alert-circle'"
                        size="20"
                    />
                    <span class="text-sm font-semibold">
                        {{ deployResult.success
                            ? t('environments.deploy.success')
                            : t('environments.deploy.error')
                        }}
                    </span>
                    <span class="ml-auto text-xs font-mono">{{ deployResult.tag }}</span>
                </div>

                <div>
                    <p class="mb-2 text-xs font-semibold uppercase tracking-wider text-neutral-400">
                        {{ t('environments.deploy.output') }}
                    </p>
                    <pre class="max-h-80 overflow-auto rounded-lg bg-neutral-900 p-4 text-xs text-green-400 font-mono whitespace-pre-wrap">{{ deployResult.output }}</pre>
                </div>
            </div>

            <!-- Override footer when showing result -->
            <template v-if="deployResult" #footer>
                <MalioButton
                    :label="t('applications.form.cancel')"
                    variant="tertiary"
                    @click="closeDeployModal"
                />
            </template>
        </AppModal>
```

- [ ] **Step 5: Verify in browser**

Run `make dev-nuxt`, login, go to `/applications/sirh`:
- Each environment should show a "Deployer" button with rocket icon
- Clicking it opens a modal
- The tag list will load (may fail if GITEA_API_TOKEN not configured — that's expected)
- The deploy will fail in dev (script not accessible) — that's expected

- [ ] **Step 6: Commit**

```bash
git add frontend/pages/applications/[slug].vue
git commit -m "feat : add deploy modal with tag selection and result display"
```

---

## Task 10: Build and verify

- [ ] **Step 1: Clear Symfony cache**

```bash
docker exec -t -u www-data php-central-fpm php bin/console cache:clear
```

- [ ] **Step 2: Build frontend**

```bash
make build-nuxtJS
```

- [ ] **Step 3: Verify API endpoints exist**

```bash
# Login
docker exec -t php-central-fpm curl -s -c /tmp/cookies -X POST http://nginx/api/login_check \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Tags endpoint (will return error about token, that's OK)
docker exec -t php-central-fpm curl -s -b /tmp/cookies http://nginx/api/applications/sirh/tags

# Deploy endpoint (will return error about script, that's OK)
docker exec -t php-central-fpm curl -s -b /tmp/cookies -X POST http://nginx/api/environments/1/deploy \
  -H "Content-Type: application/json" \
  -d '{"tag":"latest"}'
```

Both endpoints should return structured JSON responses (even if errors), not 404s.

- [ ] **Step 4: Final commit if adjustments needed**

```bash
git add -A
git commit -m "fix : adjustments from end-to-end testing"
```