update doc

	- [Ajouter des transformations](#ajouter-des-transformations)

- [Clients de référence](#clients-de-référence)

- [Tests](#tests)

- [Mise en production](#mise-en-production)

## Description du service

### Format d'échange

Le client fournit au serveur une tâche (un _job_) à effectuer sous forme d'une archive tar *gzippée* (*.tar.gz) contenant a minima **à sa racine**:

Le client fournit au serveur une tâche (un _job_) à effectuer sous forme d'une archive tar *gzippée* (*.tar.gz) 

contenant a minima **à sa racine**:

- les fichiers à transformer

- un fichier nommé job.json décrivant les transformations souhaitées sur ces fichiers

On peut également ajouter des fichiers utiles à la conversion, tel que des feuilles de styles ou des fichiers de fontes par exemple.

On peut également ajouter des fichiers utiles à la conversion, tel que des feuilles de styles ou des fichiers de 

fontes par exemple.

#### Structure du fichier job.json

... décrit une transformation unique à effectuer sur les documents fournis dans l'archive, sans options.

La seule clef obligatoire pour le job est la clef ```transformations```, contenant la liste des transformations à faire. La seule clef obligatoire pour la transformation est la clef ```name```, contenant le nom de la transformation.

La seule clef obligatoire pour le job est la clef ```transformations```, contenant la liste des transformations à faire.

La seule clef obligatoire pour la transformation est la clef ```name```, contenant le nom de la transformation.

Un cas plus complet:

        "notify_hook": "http://www.domain.tld/notify-me/"

    }

... décrit 2 transformations consécutives, dont une avec une option, ainsi qu'une URL de notification (```notify_hook```) qui sera appelée par le serveur à la fin du _job_.

... décrit 2 transformations consécutives, dont une avec une option, ainsi qu'une URL de notification 

(```notify_hook```) qui sera appelée par le serveur à la fin du _job_.

Les résultats des transformations sont également fournis par le serveur sous forme d'archive tar _gzippée_.

Attend dans le corps de la requête une archive de _job_ correctement formée. 

Retourne un [UUID version 4](https://fr.wikipedia.org/wiki/Universal_Unique_Identifier#Version_4 "UUID v4") sous forme de chaîne de caractères. L'UUID retourné est l'identifiant du _job_, à conserver pour les prochaines requêtes.

Retourne un [UUID version 4](https://fr.wikipedia.org/wiki/Universal_Unique_Identifier#Version_4 "UUID v4") sous 

forme de chaîne de caractères. L'UUID retourné est l'identifiant du _job_, à conserver pour les prochaines requêtes.

Si l'option ```block=1``` est passée dans l'URL (```/job/?block=1```), alors le comportement est différent: ce n'est pas l'UUID qui sera retourné mais directement le résultat des transformations, de manière identique à ```GET /job/[UUID]```.

Si l'option ```block=1``` est passée dans l'URL (```/job/?block=1```), alors le comportement est différent: ce n'est 

pas l'UUID qui sera retourné mais directement le résultat des transformations, de manière identique à ```GET /job/[UUID]```.

En fonction de la configuration du serveur, la soumission d'un nouveau _job_ peut nécessiter une authentification. Dans ce cas, l'entête HTTP Authorization doit être renseigné sous la forme suivante:

En fonction de la configuration du serveur, la soumission d'un nouveau _job_ peut nécessiter une authentification. 

Dans ce cas, l'entête HTTP Authorization doit être renseigné sous la forme suivante:

    Authorization: [UUID de l'application] [signature HMAC de l'archive]

Au cas où l'UUID fait référence à un _job_ n'existant pas sur ce serveur, un statut HTTP 404 est retourné.

En fonction de la configuration du serveur, la récupération d'un _job_ terminé peut nécessiter une authentification. Dans ce cas, l'entête HTTP Authorization doit être renseigné sous la forme suivante:

En fonction de la configuration du serveur, la récupération d'un _job_ terminé peut nécessiter une authentification. 

Dans ce cas, l'entête HTTP Authorization doit être renseigné sous la forme suivante:

    Authorization: [UUID de l'application] [signature HMAC de l'UUID du job]

### Notification

Dans le cas où une URL a été fournie dans la clef ```notify_hook``` du fichier job.json, le serveur effectue une requête POST sur cette URL avec l'UUID du _job_ en corps de requête.

Dans le cas où une URL a été fournie dans la clef ```notify_hook``` du fichier job.json, le serveur effectue une 

requête POST sur cette URL avec l'UUID du _job_ en corps de requête.

## Serveur de référence

### Variables d'environnement et configuration par défaut:

- ```CIRCE_HOST``` (```0.0.0.0```)

- ```CIRCE_HOST``` (```127.0.0.1```)

- ```CIRCE_PORT``` (```8000```)

- ```CIRCE_DEBUG``` (```False```)

- ```CIRCE_DEBUG``` (```0```)

- ```CIRCE_WORKERS``` (```number of CPUs```)

- ```CIRCE_WORKING_DIR``` (```$HOME/.circe/```)

- ```CIRCE_ENABLE_WEB_UI``` (```False```)

- ```CIRCE_ENABLE_WEB_UI``` (```0```)

- ```CIRCE_WEB_UI_CRYPT_KEY``` (```"you should really change this"```)

- ```CIRCE_WEB_UI_REMOVE_USER_FILES_DELAY``` (```7200```)

- ```CIRCE_USE_AUTH``` (```True```)

- ```CIRCE_USE_AUTH``` (```1```)

- ```CIRCE_TRANSFORMATIONS_MODULE``` (```None```)

Vous pouvez renseigner ces variables à différents endroits, en fonction de vos besoins:

- dans le fichier lu au démarrage de votre shell (~/.zshrc, ~/.bashrc, etc)

- dans un fichier .env dans votre répertoire de travail (celui où vous vos trouvez quand vous lancez circe)

- directement avant la commande circe, sur la même ligne

Exemple type d'un fichier .env:

	CIRCE_TRANSFORMATIONS_MODULE=mon_module_de_transfos

	CIRCE_ENABLE_WEB_UI=1

	CIRCE_WEB_UI_CRYPT_KEY="53CreT"

	CIRCE_USE_AUTH=0

### Utilisation en ligne de commande

Un certain nombre de commande sont disponibles dans circe.py. Pour les afficher:

Un certain nombre de commande sont disponibles dans circe. Pour les afficher:

    (venv) ➜  src ✗ circe --help

    usage: circe [-h]

La variable d'environnement CIRCE_TRANSFORMATIONS_MODULE contient le nom du module Python contenant les transformations

que vous souhaitez rendre disponible dans le service.

Une transformation est un Python callable (fonction ou classe) prenant en argument le dossier de travail du job, une instance de logging.Logger ainsi qu'un dictionnaire d'options (facultatif). Exemple minimal d'une transformation:

Une transformation est un Python callable (fonction ou classe) prenant en argument le dossier de travail du job, une 

instance de logging.Logger ainsi qu'un dictionnaire d'options (facultatif). Exemple minimal d'une transformation:

    def ne_fait_rien(working_dir: str, logger: logging.Logger, options: dict = None):

        pass  # ajouter ici le code transformant les documents

            print(file_name)

Une [librairie cliente équialente en Java](https://git.unicaen.fr/certic/circe-java-client) est disponible

ainsi qu'une [librairie minimale en PHP](https://git.unicaen.fr/certic/circe-php-client) et un [outil en ligne de commande implémenté en Go](https://git.unicaen.fr/mickael.desfrenes/circe-helper).

Une [librairie cliente équivalente en Java](https://git.unicaen.fr/certic/circe-java-client) est disponible

ainsi qu'une [librairie minimale en PHP](https://git.unicaen.fr/certic/circe-php-client) 

et un [outil en ligne de commande implémenté en Go](https://git.unicaen.fr/mickael.desfrenes/circe-helper).

## Tests

Un ensemble de tests exécutables par Pytest sont disponibles dans le fichier ```test.py```.

## Mise en production

Une façon simple de faire fonctionner Circe en production sur Linux est de maintenir le service via systemd

et de le mettre en reverse proxy derrière un serveur web.

Pour le service sous systemd, ajouter ceci dans un fichier /etc/systemd/system/circe.service, en prenant soin

de changer les chemins en fonction de votre installation, ainsi que votre utilisateur/groupe:

	[Unit]

	Description=Circe Service

	[Service]

	Type=simple

	# ici on a créé un utilisateur spécifique pour le service

	User=circe

	Group=circe

	UMask=007

	# On utilise ici le chemin complet vers le script circe installé dans le virtualenv 

	ExecStart=/home/circe/venvs/circe_env/bin/circe run

	Environment="PATH=/usr/bin:/home/circe/venvs/circe_env/bin:$PATH" 

	# Vous pouvez changer ici toutes les variables d'environnement propres à la configuration de Circe

	Environment="CIRCE_WEB_UI_CRYPT_KEY=qpoiurfIPUBeriIPU"

	Environment="CIRCE_TRANSFORMATIONS_MODULE=your_transformations"

	Environment="CIRCE_ENABLE_WEB_UI=0"

	Restart=always 

	RestartSec=0

	# Configures the time to wait before service is stopped forcefully.

	TimeoutStopSec=30

	[Install]

	WantedBy=multi-user.target

Puis, dans votre shell avec les droits root:

	systemctl daemon-reload

	systemctl enable circe

	systemctl start circe

Vous pouvez vérifier que le service est bien démarré avec la commande suivante:

	systemctl status circe

Le serveur devrait écouter en locahost (127.0.0.1) sur le port 8000 si vous n'avez pas modifié sa configuration.

Vous pouvez maintenant placer ce service derrière le serveur web de votre choix.

Pour [Caddy](https://caddyserver.com), dans votre /etc/caddy/CaddyFile:

	circe.yourhost.com {

		reverse_proxy 127.0.0.1:8000

		header -Server

	}

Pour Apache, dans la configuration de votre vhost:

	<Location />

		ProxyPass "http://127.0.0.1:8000/"

		ProxyPassReverse "http://127.0.0.1:8000/"

	</Location>

Référez-vous à la documentation de votre serveur web pour plus de détail.

 No newline at end of file