Commit 586ae319 authored by Luc Didry's avatar Luc Didry

Ajout de la doc pour les Gitlab Pages

parent b8ad6d37
image: debian
pages:
script:
- apt-get update
- apt-get install -y nodejs-legacy npm
- npm install gitbook-cli -g
- gitbook init
- gitbook install
- gitbook build
- cp -r _book/ public/
artifacts:
paths:
- public
only:
- gitlab-pages
......@@ -53,6 +53,13 @@
<p><b>Lufi</b></p>
</a>
</div>
<div class="col-md-3 col-sm-6">
<a href="gitlab/index.html" class="btn btn-lg btn-block btn-default">
<p><i class="fa fa-2x fa-git"></p>
<p><b class="violet">Frama</b><b class="vert">git</b></p>
<p><b>Gitlab</b></p>
</a>
</div>
<div class="col-md-3 col-sm-6">
<a href="lstu/index.html" class="btn btn-lg btn-block btn-default">
<p><i class="fa fa-2x fa-link"></p>
......
......@@ -118,6 +118,9 @@
* [Framadrop / Lufi](lufi/README.md)
* [Framagit / Gitlab](gitlab/README.md)
* [Comment utiliser les Gitlab Pages ?](gitlab/gitlab-pages.md)
* [Framalink / Lstu](lstu/README.md)
* [Framalistes / Sympa](sympa/README.md)
......
# Framagit
Framagit est la forge logicielle de Framasoft reposant sur le logiciel [Gitlab](https://gitlab.com).
Elle est ouverte à tous, dans la limite de 42 projets par personne.
Les projets peuvent être publics ou privés.
Avec Gitlab, nous proposons aussi de l'intégration continue avec [GitlabCI](https://docs.gitlab.com/ce/ci/README.html) et l'hébergement de pages statiques avec [Gitlab Pages](https://docs.gitlab.com/ce/user/project/pages/index.html) (voir notre [documentation](gitlab-pages.md))
# Comment utiliser les Gitlab Pages
Les Gitlab Pages permettent à qui possède un compte sur <https://framagit.org> (qui utilise [Gitlab][1]) de publier un site statique sur notre infrastructure, soit en sous-domaine de frama.io (par exemple : <https://luc.frama.io>) soit avec un domaine rien qu'à vous.
Les Gitlab Pages remplacent (avantageusement) [FsPages][2] que nous proposions auparavant.
Tout d'abord, voici le lien de la documentation officielle des Gitlab Pages : <https://docs.gitlab.com/ce/user/project/pages/index.html>.
## Comment ça marche ?
Les Gitlab Pages utilisent Gitlab CI, le système d'intégration continue de Gitlab, pour générer des sites statiques à l'aide de générateurs tels [Hugo][3] ou [Pelican][4] (vous pouvez en utiliser bien d'autres ou aucun).
À chaque *push*, Gitlab CI va démarrer un conteneur docker (que vous aurez préalablement choisi), exécuter un script (que vous aurez écrit) et récupérera un dossier `public` pour le publier.
## Avantages par rapport à FsPages
Premièrement, vous n'avez nul besoin d'installer un générateur de site statique sur votre ordinateur pour publier via les Gitlab Pages, contrairement à FsPages (à moins que vous ne fassiez tout à la main). À noter cependant que la plupart des générateurs possèdent une commande vous permettant de créer facilement l'arborescence idoine. Mais une fois le système mis en place, vous n'aurez plus besoin du générateur 🙂
Vous n'aurez même plus besoin de rien puisque vous pourrez modifier directement vos fichiers sources dans l'interface web de Gitlab et laisser Gitlab Pages regénérer votre site (mais bon, ça, ça nécessite que vous ayez déjà mis en place tout le système).
Deuxièmement, vous pouvez utiliser le nom de domaine que vous voulez ! Vous n'êtes plus obligés de vous contenter de https://votre_user.frama.io. Et vous pourrez aussi déposer un certificat afin que votre site avec votre nom de domaine personnel soit joignable en HTTPS.
## Exemple d'un site généré avec Hugo
### Prise en main d'Hugo
Pour plus de détails, rendez-vous sur <https://gohugo.io/overview/quickstart/>
* installez Hugo sur votre ordinateur : rendez-vous sur <https://github.com/spf13/hugo/releases>, téléchargez l'installeur correspondant à votre système d'exploitation et lancez-le
* si vous avez déjà un dépôt git, rendez-vous dans son dossier, sinon créez-en un sur <https://framagit.org/projects/new>, clonez-le et allez dans son dossier
* créez un nouveau site avec Hugo : `hugo new site mon_site; cd mon_site`
* éditez le fichier `config.toml`
* ajoutez un [thème][5] dans le dossier `themes`
* créez du contenu pour votre site : `hugo new post/toto.md`
* éditez `content/post/toto.md`
* regardez ce que ça donne en lançant `hugo server --theme=hugo_theme_robust --buildDrafts` puis en vous rendant sur <http://localhost:1313/>
* si vous êtes satisfait du résultat, éditez `content/post/toto.md` et passez `draft à false`
* pour éviter de devoir passer l'argument `--theme=hugo_theme_robust` à hugo à chaque fois, ajoutez `theme = "hugo_theme_robust"` à votre fichier `config.toml`
### Publication via les Gitlab Pages
Pour plus de détails, rendez-vous sur <https://gohugo.io/tutorials/hosting-on-gitlab/>
```
echo "/public/" >> .gitignore
echo "/themes/" >> .gitignore
vi .gitlab-ci.yml
```
Ajoutez ceci à votre fichier `.gitlab-ci.yml` (attention ! Si vous avez déjà de l'intégration continue en place, il peut être opportun soit d'utiliser votre image classique et d'y installer hugo (comme sur, par exemple, <https://gitlab.com/pages/hugo>) soit de faire une branche dédiée).
```
image: publysher/hugo
pages:
script:
- hugo
artifacts:
paths:
- public
only:
- master
```
Puis :
```
git add --all
git commit -m "Publication de mon super site"
git push
```
Et voilà ! Votre site devrait être accessible à l'adresse https://votre_user.frama.io/votre_depot ou directement à https://votre_user.frama.io/ si votre dépôt s'appelle votre_user.frama.io.
Rendez-vous sur <https://framagit.org/votre_user/votre_depot/pages> si vous souhaitez que votre site soit accessible avec le nom de domaine de votre choix.
### Passer de FsPages aux Gitlab Pages
Si vous utilisiez Fspages, il est très simple d'adapter votre dépôt git pour qu'il utilise désormais Gitlab Pages. En effet, FsPages ne permettait que de publier des dossiers contenant des pages HTML déjà préparées, et les Gitlab Pages permettent de faire la même chose.
* supprimez le webhook qui servait pour FsPages (sur <https://framagit.org/votre_user/votre_projet/settings/integrations>), il s'agit du webhook à l'adresse semblable à http://127.0.0.1:4246
* copiez le fichier .gitlab-ci.yml de <https://gitlab.com/pages/plain-html> dans votre dépôt git
* modifiez ce fichier :
* si le dossier à publier ne s'appelle pas `public`, à la place de `echo 'Nothing to do...'`, mettez `mv votre_dossier public`
* au lieu de `master` tout en bas, indiquez `fs-pages` (sauf si vous voulez vous débarrasser de la branche fs-pages, auquel cas il vous faut copier le contenu de la branche fs-pages dans la branche master)
* supprimez le fichier `.fs-pages.json`
* commitez et pushez 🙂
Si vous souhaitez que votre dépôt git fournisse la racine de votre site (i.e. qu'il ne soit pas publié dans un sous-dossier de https://votre_user.frama.io), il suffit de renommer votre dépôt en votre_user.frama.io (exemple : <https://framagit.org/luc/luc.frama.io>) via la page https://framagit.org/votre_user/votre_projet/edit
## Rediriger vers la version HTTPS
Malheureusement, contrairement à notre installation de FsPages, les sites ne sont pas redirigés vers la version HTTPS s'il en existe une (pas même pour les sous-domaines de frama.io, qui bénéficient automatiquement d'une version HTTPS). Un [ticket][6] est cependant ouvert chez Gitlab à ce sujet.
En attendant, pour pallier ce problème, vous pouvez inclure ce petit bout de javascript dans vos pages HTML :
```
<script>
var loc = window.location.href+'';
if (loc.indexOf('http://')==0){
window.location.href = loc.replace('http://','https://');
}
</script>
```
## Utiliser Let's Encrypt
L'utilisation de certificats [Let's Encrypt][7] n'est pas [aisée][8] mais un [ticket][9] est ouvert chez Gitlab pour intégrer directement Let's Encrypt aux Gitlab Pages.
[1]: https://framacloud.org/cultiver-son-jardin/installation-de-gitlab-et-mattermost/
[2]: https://framagit.org/luc/fs-pages
[3]: https://gohugo.io/
[4]: https://blog.getpelican.com/
[5]: https://themes.gohugo.io/
[6]: https://gitlab.com/gitlab-org/gitlab-ce/issues/28857
[7]: https://letsencrypt.org/
[8]: https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/
[9]: https://gitlab.com/gitlab-org/gitlab-ce/issues/28996
manueldumo @ 4db2dcf4
Subproject commit 4db2dcf4e37708593dddc07a165294bc7c6bb59b
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment