# Vast.ai — Guide de création de templates

> Référence condensée pour créer et configurer ses propres templates sur Vast.ai.

---

## 1. Identification

| Champ | Description |
|---|---|
| **Template Name** | Nom affiché sur la carte du template. |
| **Template Description** | Description optionnelle, utile si le template est partagé/public. |

---

## 2. Image Docker (`Image Path:Tag`)

Format obligatoire : `repository/image_name:tag`

Exemples d'images compatibles :
- Images publiques DockerHub : `nginx:latest`, `postgres:14`, `python:3.11`
- Images Vast.ai : `vastai/base-image`, `vastai/pytorch`
- Registres alternatifs (chemin complet requis) : `nvcr.io/nvidia/pytorch:25.04-py3`, `ghcr.io/…`, `gcr.io/…`

**Tag spécial `[Automatic]`** : sélectionne automatiquement l'image compatible avec la version CUDA de la machine (nécessite que le tag contienne la version CUDA, ex: `my-image-cuda-12.8`).

---

## 3. Ports

- Ajouter les ports TCP/UDP nécessaires à l'accès externe.
- Un port externe aléatoire est assigné et mappé vers le port interne du container.
- Alternative via tunnel SSH :
  ```bash
  ssh -p [SSH_PORT] [USER]@[REMOTE_HOST] -L [LOCAL_PORT]:localhost:[REMOTE_PORT]
  ```

---

## 4. Variables d'environnement

- Ajouter les variables requises par l'image Docker.
- **Ne jamais mettre de secrets dans un template public** → utiliser les variables d'environnement du compte (`cloud.vast.ai/account/`) qui sont injectées dans toutes les instances.

### Variables spéciales

| Variable | Rôle |
|---|---|
| `PROVISIONING_SCRIPT` | URL d'un script shell exécuté au démarrage de l'instance |
| `PORTAL_CONFIG` | Configure l'accès aux applications via l'Instance Portal |

---

## 5. Modes de lancement

| Mode | Description |
|---|---|
| **Jupyter + SSH** | Installe Jupyter (port `8080`) et SSH (port `22`) au runtime. Entrypoint Docker ignoré. |
| **SSH uniquement** | Comme ci-dessus, sans Jupyter. Entrypoint Docker ignoré. |
| **docker ENTRYPOINT** | Le container s'exécute exactement comme prévu. Aucun outil supplémentaire ajouté. |

> ⚠️ En mode Jupyter ou SSH, l'entrypoint Docker original **n'est pas exécuté**. Utiliser le **On-start Script** pour démarrer les services.

---

## 6. On-start Script (Jupyter/SSH uniquement)

Script Bash exécuté au démarrage. Exemples :

```bash
# Exécuter un script existant dans l'image
chmod +x /usr/local/bin/start.sh
bash /usr/local/bin/start.sh

# Modifier un fichier de configuration
sed -i 's/-sslOnly//g' /dockerstartup/vnc_startup.sh

# Créer un répertoire
sudo -i -u kasm-user mkdir -p /home/kasm-user/Desktop

# Persister les variables d'environnement
env >> /etc/environment
```

> Toujours appeler la commande ENTRYPOINT/CMD originale à la fin du script.

---

## 7. PROVISIONING_SCRIPT — Personnalisation au runtime

**Méthode la plus simple** pour personnaliser un template sans rebuilder une image Docker.

### Configuration
1. Éditer un template (ex: `vastai/base-image` ou `vastai/pytorch`)
2. Ajouter la variable d'environnement `PROVISIONING_SCRIPT` avec une URL vers un script shell (GitHub, Gist, etc.)

### Exemple de script
```bash
#!/bin/bash
cd /workspace/
set -eo pipefail

# Activer l'environnement virtuel
. /venv/main/bin/activate

# Installer des packages
pip install your-packages

# Télécharger des fichiers
wget -P "${WORKSPACE}/" https://example.org/my-application.tar.gz
tar xvf ${WORKSPACE}/my-application.tar.gz

# Configurer un service Supervisor
echo "my-supervisor-config" > /etc/supervisor/conf.d/my-application.conf
echo "my-supervisor-wrapper" > /opt/supervisor-scripts/my-application.sh
chmod +x /opt/supervisor-scripts/my-application.sh

# Reconfigurer le portail
export PORTAL_CONFIG="localhost:1111:11111:/:Instance Portal|localhost:1234:11234:/:My Application"

# Recharger Supervisor
supervisorctl reload
```

> Toutes les installations doivent aller dans `/workspace/` pour la persistance.

---

## 8. PORTAL_CONFIG — Accès aux applications

Structure :
```
hostname:external_port:local_port:url_path:Application Name|...
```

- Séparateur entre applications : `|`
- Séparateur entre paramètres : `:`
- `hostname` = toujours `localhost` dans les containers Docker
- Si `external_port ≠ local_port` → Caddy agit en reverse proxy
- Si `external_port = local_port` → Caddy ne proxifie pas (utile pour Jupyter)

Exemple complet :
```bash
"localhost:8002:18002:/hello:MyApp|localhost:1111:11111:/:Instance Portal|localhost:8080:18080:/:Jupyter|localhost:8384:18384:/:Syncthing"
```

---

## 9. Images Docker personnalisées (build custom)

### Option A : FROM une image Vast.ai (recommandé)
```dockerfile
FROM vastai/base-image:cuda-12.6.3-cudnn-devel-ubuntu22.04-py313
# ou
FROM vastai/pytorch:2.6.0-cuda-12.6.3-py312

WORKDIR /opt/workspace-internal/
RUN . /venv/main/bin/activate && your-installation-commands
```

### Option B : FROM n'importe quelle image de base
Compatible avec toute image publique ou privée.

**Étapes** :
1. Écrire le Dockerfile
2. `docker build` + `docker push` vers un registre
3. Créer un template avec le chemin de l'image personnalisée

---

## 10. Authentification Docker (images privées)

Renseigner les credentials dans la section **Docker Repository Authentication**.

| Registre | Server Name |
|---|---|
| Docker Hub | *(laisser vide)* |
| GitHub Container Registry | `ghcr.io` |
| Google Container Registry | `gcr.io` |

---

## 11. Paramètres supplémentaires

| Paramètre | Description |
|---|---|
| **Disk Space** | Espace disque minimum pour les instances créées depuis ce template |
| **Extra Filters** | Restreindre les machines affichées (ex: CPU architecture AMD64/ARM64) |
| **Visibility** | Public (visible dans la recherche) ou Privé (accessible via URL uniquement) |

> ⚠️ Ne jamais mettre de secrets dans un template public.

---

## 12. Sauvegarde et lancement

| Bouton | Action |
|---|---|
| **Create** | Sauvegarde dans "My Templates" |
| **Create & Use** | Sauvegarde et ouvre la page des offres |

Le template génère aussi une **commande CLI** équivalente (section lecture seule).

---

## Cas d'usage courants

**Lancer une application existante (ex: nginx)**
1. Trouver l'image officielle sur DockerHub
2. Créer un template avec l'image + ports requis
3. Sauvegarder et lancer

**Personnaliser un template Vast recommandé**
1. Éditer un template recommandé
2. Ajouter `PROVISIONING_SCRIPT` pointant vers votre script
3. Voir section 7 ci-dessus

**Construire sa propre image Docker**
1. Créer un Dockerfile (optionnellement FROM une image Vast)
2. Build + push vers un registre
3. Créer un template avec le chemin de l'image custom