# Créer son instance

Une fois la volonté de créer son instance validée et les premiers éléments graphiques rassemblées ([clique ici](/fr/gettingstarted/prerequisites) pour en savoir plus), il est temps de créer son instance.

?> Ces étapes doivent être réalisées par un·e développeur·euse à l'aise avec l'invite de commande et `git`. Il est nécessaire de disposer de `npm` et d'être sous un environnement Linux.

**Ce qu'on doit créer**

Aktivisda est un site internet statique, cela signifie qu'il n'y a en particulier pas de base de données. Toutes les données sont stockées dans une **arborescence de dossiers et de fichiers** : aktivisda s'attend à trouver chaque élément à un endroit précis.
Il est ensuite recommandé de stocker ces données **dans un projet Gitlab** (nécessaire pour utiliser _backtivisda_).

Pour rendre accessible Aktivisda, il y a besoin de configurer un **serveur web**. Et pour faire fonctionner backtivisda, il y a besoin d'utiliser de créer un **serveur dédié au traitement d'images** (ou d'en utiliser un existant). Deux étapes restantes sont la mise en place d'un runner Gitlab pour l'intégration continue et une instance Matomo pour évaluer la fréquentation du site.


## 1. Arborescence de fichiers

Pour créer l'arborescence de fichiers, il est recommandé d'utiliser le générateur [yeoman](https://yeoman.io/) dans un dossier vide.

1. Créer le dossier qui contiendra les données de votre instance Aktivisda et s'y rendre (remplacer `<moninstance` par le nom de votre instance)
```terminal
mkdir <moninstance>
cd <moninstance>
```

2. Récupérer le code source de Aktivisda avec `git` et l'enregistrer dans un dossier `aktivisda-core`. Cela vous permettra d’accéder au générateur et de pouvoir lancer ou compiler Aktivisda localement sur votre ordinateur.
```terminal
git clone https://framagit.org/aktivisda/aktivisda.git aktivisda-core
```

3. Installer `yeoman` puis le générateur
```terminal
npm install -g yo
cd aktivisda-core/generator-aktivisda
npm install
npm link
```

4. Se rendre à la racine de notre projet (le dossier `<moninstance>`) puis y lancer le générateur, suivre les différentes étapes
```terminal
yo aktivisda
```
**🥳 Félicitations ! Vous disposez alors de la base d'une instance Aktivisda !**

5. Tester localement Aktivisda. Depuis le dossier `<moninstance>`, exécuter :
```terminal
npm install
npm run serve:aktivisda
```
**Note** : cette opération crée des liens symboliques sur votre ordinateur à travers un script shell. Il est nécessaire d'être dans un environnement Linux.

Comme indiqué dans le terminal, vous pouvez visualiser votre instance Aktvisda à l’url [localhost:8080](http://localhost:8080).
Cette instance est encore une coquille vide, sans élément graphique ☹️ (voir ticket [#190](https://framagit.org/aktivisda/aktivisda/-/issues/190) pour ajouter des logos et images de base).

Pour ajouter des éléments, voir la [documentation](/fr/admin). Pour pouvoir commencer à ajouter des éléments _via_ backtivisda, il est nécessaire de réaliser les étapes 2 (Projet Gitlab) et 3 (serveur backtivisda).

## 2. Projet Gitlab

**Pourquoi Gitlab ?**

Sauvegarder les données dans un projet Gitlab a pour avantages :
* faciliter la collaboration à plusieurs grâce à la force de `git`.
* disposer de toutes les fonctionnalités d'un projet gitlab, en particulier l'intégration continue et la gestion des tickets ;

En plus, l'API de Gitlab est utilisée pour permettre à Backtivisda de fonctionner.

?> Des réflexions sont en cours peur permettre une alternative de stockage à Gitlab,voir ticket [#181](https://framagit.org/aktivisda/aktivisda/-/issues/181).

1. Créer un projet sur n'importe quelle instance Gitlab :
    * La visibilité du projet peut-être privée, interne ou publique ;
    * L'instance Gitlab doit être accessible sur internet (ou tout du moins accessible par le navigateur web de l'utilisateur qui ouvrira backtivisda)
    * Il est possible d'utiliser [Framagit](https://framagit.org), instance proposée par l'association [Framasoft](https://framasoft.org) et où est également hébergée le code source de Aktivisda.
    * Ne pas initialiser avec un `readme`
2. Suivre les instructions qui apparaissent à l'écran et en particulier _« Push an existing folder »_, une fois dans notre projet, exécuter :
```terminal
git init --initial-branch=main
git remote add origin git@framagit.org:aktivisda/climaximo.git
```
3. S'assurer qu'il n'y a pas de modifications locales qu'on ne souhaiterait pas commiter, je pense en particulier à des dossiers de travail. Les fichiers de travail peuvent être sauvegardés dans le dossier `_private` qui est ignoré par `git` par défaut (_cf._ le fichier `.gitignore`)

4. S'il n’y a pas de modifications locales à ne pas commiter, tout commiter :
```terminal
git add .
git commit -m "Initial commit"
git push --set-upstream origin main
```

5. Pour pouvoir utiliser backtivisda il faut aller mettre à jour les variables suivantes dans le fichier `.env.backtivisda` (l'identifiant du projet est disponible dans l'interface Gitlab)
```
VUE_APP_GITLAB_PROJECT_ID=xxxxx
VUE_APP_GITLAB_URL="https://framagit.org"
VUE_APP_GITLAB_REPO_URL=/xxx/xxx
```

**🥳 Félicitations ! Plus qu'une étape avant de pouvoir utiliser Backtivisda !**

## 3. Serveur backtivisda

!> Il semblerait que des changements récents dans une dépendance ait caissé le serveur (voir ticket [#191](https://framagit.org/aktivisda/aktivisda/-/issues/191)).

Pour fonctionner, backtivisda a besoin de se connecter à un serveur de manipulation d'images : compression, redimensionnement, vectorisation, etc.

> Vous ne souhaitez pas mettre en place votre propre serveur ? Écrire à [dev@aktivisda.earth](mailto:dev@aktivisda.earth) pour utiliser le serveur communautaire.

### Authentification

Il existe un mécanisme d'authentification pour limiter l'accès de votre serveur de traitement d'image. Pour l'initialiser :

1. Se rendre dans le dossier `server` du projet aktivisda
2. Générer un `secrets` avec python3
```terminal
python3 -c "import secrets; print(secrets.token_hex())"
```
3. Copier-coller la valeur dans le fichier `.env`
4. Ajouter dans le fichier `.env` une variable `USERS` qui contient la liste des usernames autorisés à utiliser votre instance, chacun séparé par une virgule.
```txt
USERS="admin,admin2"
```
5. Créer un token d'authentification pour chaque utilisateur renseigné préalablement :
```terminal
python3 scripts/generate_token.py admin
python3 scripts/generate_token.py admin2
```
Copier-coller ces valeurs et les garder précieusement (il sera toujours possible de les regénérer)

### Exécution

Tout le code du serveur est présent dans le dossier `server` de Aktivisda. Il y a notamment un `dockerfile`.

* Compiler l'image docker
```terminal
sudo docker build -t aktivisdaserver:latest .
```

* Lancer l'image docker
```terminal
sudo docker run -p 4000:4000 -t aktivisdaserver:latest
```

**Note** : il faut paramétrer Nginx (et probablement apache2) pour accepter les chargements d'images _un peu lourdes_. Il est conseillé d'ajouter dans la configuration Nginx :
```
client_max_body_size 10M;
```

Si vous vous rendez sur [localhost:400](https://localhost:4000) vous devriez voir écrit « hello world ». Si tel est le cas, 🥳 bravo !

### Paramétrer backtivisda

Vous pouvez désormais mettre à jour la variable VUE_APP_SERVER_URL dans le fichier `.env.backtivisda` :
```
VUE_APP_SERVER_URL="https://server.aktivisda.earth"
```
👉 Vous pouvez alors utiliser [backtivisda](/fr/admin/backtivisda) !

## 4. Serveur web

?> Perdu·e à cette étape ? Ne pas hésiter à écrire à [dev@aktivisda.earth](mailto:dev@aktivisda.earth) pour demander à ce que cette section soit étoffée. Et si **au contraire** vous savez exactement quoi faire, ne pas hésiter à compléter ces instructions.

Il y a besoin de paramétrer un serveur web, par exemple avec Nginx, et de créer un utilisateur avec accès ssh pour le chargement du contenu de aktivisda.

### Nginx

Pour permettre à l'utilisateur·ice d'accéder à toutes les pages de Aktivisda, il est nécessaire d'être vigilant·e à paramétrer Nginx pour lui dire de renvoyer `index.html` s'il ne trouve pas de fichier html correspondant. Il faut pour cela ajouter `/index.html` à l'instruction `try_files`.

```txt
location / {

    # Path to source
    alias /var/www/<your project>/www/;

    # Default indexes and catch-all
    index index.html;
    try_files $uri $uri/ /index.html;

    # Prevent useless logs
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }
    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

    # Deny access to hidden files and directories
    location ~ ^/(.+/|)\.(?!well-known\/) {
        deny all;
    }
}

```
## 5. Intégration continue

Par défaut, un fichier `.gitlab-ci.yml` est présent dans le projet. Celui-là appelle le fichier `common.gitlab-ci.yml` présent dans Aktivisda.

De cette manière, il n'y a pas à se soucier de mettre à jour l'intégration continue.

Il y a deux étapes dans l'intégraton continue :
1. La compilation de aktivisda et de backtivisda en utilisant la dernière version de aktivisda
2. L'envoi en FTP du site sur le serveur


### Runner gitlab

Pour réaliser les étapes d'intégration continue, il est nécessaire de disposer d'un runner gitlab plutôt puissant.
(**Todo: documentation à compléter**)

### Paramétrisation

!> ⚠️ Attention à bien définir les variables comme _protected_.

Pour faire fonctionner l'envoi en FTP, il faut créer quatre CI/CD variables dans le projet Gitlab :
* `FTP_HOST` avec l'url (ou l'adresse IP) vers le serveur. Par ex. `aktivisda.earth`
* `FTP_PORT` avec le numéro de port `ssh` (utilisé pour se connecter en `SFTP`). _A priori_ `22` sauf paramétrisation particulière (mais conseillée)
* `FTP_PASSWORD` et `FTP_USER` les identifiants pour se connecter

### Fonctionner sans intégration continue

Il est toujours possible de déployer Aktivisda sans mettre en place une intégration continue. Pour cela, il est nécessaire de mettre sur pieds un environnement de développement puis de réaliser les commandes :

```terminal
npm run build:aktivisda
npm run build:backtivisda
```

Puis de déplacer le contenu du dossier `dist` sur le serveur distant.

_En cas de difficultés, se référer au fichier `common.gitlab-ci.yml` pour savoir quelles sont les commandes à jour._

## 6. Matomo

_(à venir)_