# Déployer une image Docker

> Du Dockerfile au service en ligne, et le retour arrière quand ça casse.

Une **application conteneurisée** (ACS) part de ton dépôt : tu construis une image,
tu la pousses au registre Arkya, Arkya la met en service.

## Ce que ton image doit respecter

Quatre règles : écouter sur `$PORT`, écouter sur `0.0.0.0`, n'écrire que dans
`/home/container`, et sortir proprement sur `SIGTERM`. La racine du conteneur est en
lecture seule et le processus ne tourne pas en root — deux détails qui expliquent la
plupart des démarrages ratés.

<Card title="Écrire un Dockerfile pour Arkya" icon="docker" href="/guides/dockerfile">
  Les contraintes en détail, un Dockerfile complet, et les pannes courantes avec leur cause.
</Card>

## Premier déploiement

```bash
cd mon-api
ark init
```

<Note>
  L'emplacement peut aussi se réserver depuis l'espace client : sur le canevas d'un
  projet, **Ajouter un service** puis **Image Docker**. Dans ce cas, `ark init --app
  <nom>` reprend l'application existante au lieu d'en créer une.
</Note>

La commande demande le nom, le nœud et le projet, crée l'application chez Arkya, puis
écrit le manifeste :

```json arkya.json
{
  "app": "mon-api",
  "dockerfile": "Dockerfile",
  "context": ".",
  "env": {}
}
```

```bash
ark deploy
```

```
- construction de registry.arkya.gg/c-7f3a91c04d2e/mon-api:8f2c1d9a44e0 pour linux/amd64
ok image construite
- envoi de registry.arkya.gg/c-7f3a91c04d2e/mon-api:8f2c1d9a44e0
- enregistrement de la version chez Arkya
ok version 8f2c1d9a44e0 disponible
- mise en service de mon-api:8f2c1d9a44e0
ok mon-api tourne en 8f2c1d9a44e0
  51.210.44.12:30017
```

Le nom de version est le commit courant. Chaque déploiement en crée un nouveau, et les
anciens restent disponibles.

## Les variables

Deux endroits, deux usages.

**Dans le manifeste**, ce qui fait partie du dépôt et se relit dans une revue de code :

```json arkya.json
{
  "app": "mon-api",
  "env": {
    "LOG_LEVEL": "info",
    "FEATURE_PANIER": "1"
  }
}
```

`ark deploy` les pose à chaque déploiement.

**Par la commande**, ce qui ne doit pas être dans le dépôt :

```bash
ark env set mon-api DATABASE_URL="postgres://..." STRIPE_KEY="sk_live_..."
```

<Warning>
  Ne mets jamais un secret dans `arkya.json` : il partirait dans Git. Les secrets
  passent par `ark env set`, ou par un fichier `.env` ignoré et poussé avec
  `ark env push`.
</Warning>

## Brancher une base de données

```bash
ark project create Production
ark project attach mon-api Production
ark project attach pg-api Production

ark net pg-api
ark env set mon-api DATABASE_HOST=pg-api DATABASE_PORT=5432
ark net pg-api --private
ark restart mon-api
```

La base n'est plus joignable depuis Internet, mais `mon-api` la joint par son alias.

## Regarder ce que ça donne

```bash
ark logs --follow
```

```bash
ark info
```

## Revenir en arrière

Les versions poussées restent disponibles. Pas besoin de reconstruire :

```bash
ark status
```

```
versions
  8f2c1d9a44e0   en service
  7a1b2c3d4e5f   poussée
```

```bash
ark deploy --release 7a1b2c3d4e5f
```

```
- mise en service de mon-api:7a1b2c3d4e5f
ok mon-api tourne en 7a1b2c3d4e5f
```

C'est la manœuvre à connaître par cœur : trente secondes, et tu es revenu à la version
d'avant.

## Construire pour la bonne architecture

`ark build` demande à Arkya sur quelle architecture tourne le nœud et construit pour
elle. Sur un Mac Apple Silicon, ça veut dire une construction croisée vers
`linux/amd64` — plus lente, mais juste.

Pour forcer :

```bash
ark build --platform linux/arm64
```

## Ce qui coince le plus souvent

<AccordionGroup>
  <Accordion title="Le service tourne mais ne répond pas">
    L'application n'écoute pas sur `$PORT`, ou elle écoute sur `127.0.0.1` au lieu de
    `0.0.0.0`. Les deux donnent le même symptôme.
  </Accordion>
  <Accordion title="« EROFS » ou « permission denied » au démarrage">
    La racine est en lecture seule et le conteneur tourne en uid 988. Voir
    [Écrire un Dockerfile pour Arkya](/guides/dockerfile).
  </Accordion>
  <Accordion title="« exec format error » dans la console">
    L'image a été construite pour une autre architecture. Reconstruis sans `--platform`
    et laisse `ark build` choisir.
  </Accordion>
  <Accordion title="Les fichiers écrits disparaissent au déploiement">
    Ils ne sont pas dans `/home/container`. Voir
    [Disque, fichiers et persistance](/comprendre/stockage).
  </Accordion>
  <Accordion title="« Ton jeton a été refusé » pendant le push">
    `ark login` connecte aussi Docker au registre. Si tu as changé de jeton depuis,
    relance-le.
  </Accordion>
</AccordionGroup>