# Variables et références

> Les variables d’environnement d’une application, ses secrets, et les références qui la relient aux bases du projet sans écrire d’adresse.

Source : https://docs.arkya.gg/applications/variables

## Où les poser

Les variables d’une application se règlent à deux endroits. Choisis-en un seul.

- **L’onglet Variables** de l’application, dans l’espace client. C’est le bon endroit pour un secret ou la connexion à une base. Tu peux y coller un fichier `.env`, et marquer une variable comme secrète : sa valeur reste masquée à l’écran.
- **Le champ `env` de `arkya.json`**, envoyé par `ark deploy`. Il convient aux valeurs simples, sans secret, puisqu’il part dans Git.

> **Attention**
>
> `ark deploy` remplace toutes les variables de l’application par celles du manifeste, dès que `env` n’est pas vide. Si tu passes par l’espace client, laisse `"env": {}` dans `arkya.json`.

Enregistrer les variables relance l’application : elle les lit au démarrage.

## Les règles

- Un nom s’écrit avec des lettres, des chiffres et des tirets bas, sans commencer par un chiffre.
- Une application porte au plus 100 variables, de 4 096 caractères chacune.
- `PORT` est posée par Arkya : tu ne peux pas la définir. Voir [Préparer ton image](https://docs.arkya.gg/applications/image).

## Les références

Une référence remplace une adresse que tu n’as pas à connaître. Arkya la résout à chaque démarrage.

| Référence | Devient |
| --- | --- |
| `${boutique-db.HOST}` | l’hôte interne du service `boutique-db` |
| `${boutique-db.PORT}` | son port |
| `${boutique-db.URL}` | `hôte:port`, sans protocole ni identifiants |

- Le nom est celui du service, en minuscules. L’onglet Variables liste tes voisins sous **Voisins du projet**.
- Seuls les applications et les bases du même projet peuvent être citées. Un nom inconnu est refusé à l’enregistrement.
- `HOST`, `PORT` et `URL` s’écrivent en majuscules. Toute autre forme reste du texte, sans remplacement.

> **Bon à savoir**
>
> `${boutique-db.URL}` ne contient ni `postgres://`, ni utilisateur, ni mot de passe. Pour une URL de connexion complète, compose-la comme ci-dessous.

## Brancher une base

Ouvre l’onglet **Connexion** de la base : il donne l’utilisateur, le nom de la base et une URL modèle. Le mot de passe n’est affiché qu’à la création ; perdu, il se régénère depuis le même onglet.

Puis, dans l’onglet Variables de l’application :

**PostgreSQL**

```dotenv
DATABASE_URL=postgres://arkya:MOT_DE_PASSE@${boutique-db.URL}/boutique_db
```

**MariaDB**

```dotenv
DATABASE_URL=mysql://arkya:MOT_DE_PASSE@${boutique-db.URL}/boutique_db
```

**Redis**

```dotenv
REDIS_URL=redis://:MOT_DE_PASSE@${boutique-cache.URL}
```

**Variables séparées**

```dotenv
DB_HOST=${boutique-db.HOST}
DB_PORT=${boutique-db.PORT}
DB_USER=arkya
DB_PASSWORD=MOT_DE_PASSE
DB_NAME=boutique_db
```

Marque comme secrètes les variables qui contiennent le mot de passe.

## Depuis l’API

`GET /api/apps/boutique/environment` rend les variables, celles posées par Arkya et la liste des voisins. `PUT` sur la même route **remplace** toutes les variables : renvoie toujours l’ensemble. Voir [L’API HTTP](https://docs.arkya.gg/api).