Skip to content
Snippets Groups Projects
Commit 59a13abd authored by Jacek Lebioda's avatar Jacek Lebioda
Browse files

doc(readme): New readme 

Merge branch '11-update-readme' into 'master'

Closes #11

See merge request core-services/r3lab/r3-pages!10
parents 8ff5cadc f2598b66
No related branches found
Tags v0.0.9
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 28 additions and 132 deletions
README.md
+ 28
− 132
View file @ 59a13abd
![Build Status](https://gitlab.com/pages/jekyll/badges/master/build.svg)
# R3-pages
This is a repository containing source for the index pages of [http://r3lab.uni.lu/](http://r3lab.uni.lu/) and its frozen pages.
---
Note that the sites from _Websites_ menu tab, are contained in their own repositories:
* TGM-pipeline at [https://git-r3lab.uni.lu/core-services/r3lab/tgm-pipeline-doc]()
* CASian at [https://git-r3lab.uni.lu/core-services/r3lab/casian-doc](https://git-r3lab.uni.lu/core-services/r3lab/casian-doc)
* IMP at [https://git-r3lab.uni.lu/core-services/r3lab/imp-doc](https://git-r3lab.uni.lu/core-services/r3lab/imp-doc)
Example [Jekyll] website using GitLab Pages. View it live at https://pages.gitlab.io/jekyll
# Deployment
## How are the pages built?
All of these pages are built with Jekyll using Gitlab-CI (see respective `.gitlab-ci.yml` files and the instructions on [https://git-r3lab.uni.lu/core-services/jekyll-theme-lcsb-default](https://git-r3lab.uni.lu/core-services/jekyll-theme-lcsb-default)` if you need more information).
[Learn more about GitLab Pages](https://pages.gitlab.io) or read the the [official GitLab Pages documentation](https://docs.gitlab.com/ce/user/project/pages/).
## How are the pages uploaded to the VM?
There is `deploy to production` section in `.gitlab-ci.yml`, which pushes the built webpage onto the VM. Under the hood, there are details saved in [Settings ==> CI/CD ==> Variables](https://git-r3lab.uni.lu/core-services/r3lab/r3-pages/-/settings/ci_cd) section, which comprise the secret values (SSH key, the username, VM address etc.). If you create a new page which should upload the page there, don't forget to add those!
---
## How are the pages published?
At current moment, the staticpages VM is configured to expose files from `/home/r3pages/web/latest` under `r3lab.uni.lu`.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
* the index page goes into `~/web/web_$CI_TASK_ID` (e.g. `~/web/web_115885`) and then it gets soft-symlinked into `~/web/latest`.
* the other pages go into `~/web/$PROJECT_NAME_$CI_TASK_ID` (e.g. `~/web/casian-doc_115903`), and then it gets soft-symlinked into `~/web/latest/web/$PROJECT_NAME`, e.g. `~/web/latest/web/casian-doc`.
- [Getting Started](#getting-started)
- [Start by forking this repository](#start-by-forking-this-repository)
- [Start from a local Jekyll project](#start-from-a-local-jekyll-project)
- [GitLab CI](#gitlab-ci)
- [Using Jekyll locally](#using-jekyll-locally)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
- [Other examples](#other-examples)
- [Troubleshooting](#troubleshooting)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Getting Started
You can get started with GitLab Pages using Jekyll easily by either forking this repository or by uploading a new/existing Jekyll project.
Remember you need to wait for your site to build before you will be able to see your changes. You can track the build on the **Pipelines** tab.
### Start by forking this repository
1. Fork this repository.
1. **IMPORTANT:** Remove the fork relationship.
Go to **Settings (⚙)** > **Edit Project** and click the **"Remove fork relationship"** button.
1. Enable Shared Runners.
Go to **Settings (⚙)** > **Pipelines** and click the **"Enable shared Runners"** button.
1. Rename the repository to match the name you want for your site.
1. Edit your website through GitLab or clone the repository and push your changes.
### Start from a local Jekyll project
1. [Install][] Jekyll.
1. Use `jekyll new` to create a new Jekyll Project.
1. Add [this `.gitlab-ci.yml`](.gitlab-ci.yml) to the root of your project.
1. Push your repository and changes to GitLab.
## GitLab CI
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
```
image: ruby:2.5
variables:
JEKYLL_ENV: production
pages:
script:
- bundle install
- bundle exec jekyll build -d public
artifacts:
paths:
- public
only:
- master
```
## Configuration
You have some variables that you need to override in the `_config.yaml` file.
## Using Jekyll locally
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install][] Jekyll
1. Download dependencies: `bundle`
1. Build and preview: `bundle exec jekyll serve`
1. Add content
The above commands should be executed from the root directory of this project.
Read more at Jekyll's [documentation][].
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Other examples
* [jekyll-branched](https://gitlab.com/pages/jekyll-branched) demonstrates how you can keep your GitLab Pages site in one branch and your project's source code in another.
* The [jekyll-themes](https://gitlab.com/groups/jekyll-themes) group contains a collection of example projects you can fork (like this one) having different visual styles.
## Enabling and configuring pagination
The template includes `jekyll-paginate-v2` plugin by default, but it's turned off.
To use it, configure the pagination following instructions from the next paragraph, go to `pagination.md` file and change `enabled: false` to `enabled: true`, and `published: false` to `published: true`. Later, create a directory called `_posts` in the project root directory and fill it with posts.
You may also need to disable showing `index.md`, by setting `published: false` in its contents.
There are two sections in `_config.yml`, that refer to pagination: first, ` - jekyll-paginate-v2` line in plugins section, and then the configuration dictionary:
# First-time deployment
Don't forget to create the directories! (including `~/web/latest`)
```
pagination:
enabled: true # Note, that setting it to disabled does not disable it completely, as it has to be also set to false in `pagination.md` file
title: ':title - page :num of :max' # Customize the text
per_page: 8 # How many posts should be displayed on one page
permalink: '/page/:num/' # The URL to the index of pagination
limit: 0
sort_field: 'date' # How the posts should be sorted. can also be: `title` or any page attribute
sort_reverse: true
trail: # How many pages should be shown in paginator.
before: 2 # Show 2 before the current one, e.g. `< 5 6 CURRENT ...`
after: 2 # Show 2 after the current one, e.g. `... CURRENT 6 7 >`
mkdir -p ~/web/latest/web/casian-doc ~/web/latest/web/imp-doc ~/web/latest/web/tgm-pipeline
```
To disable it completely, set `enabled` to `false`, remove the aforementioned sections from the configuration, and `gem "jekyll-paginate-v2", "~> 1.7"` from `Gemfile` (from the project's root), and remove `pagination.md` file from project's root directory.
Refer to its [documentation](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md) for more detailed instructions.
# Emergency recovery
## Troubleshooting
## Elegant solution
1. SSH into the VM, and remove all the old files `cd ~/web; rm -rf *`
2. Recreate the folder structure with `mkdir -p ~/web/latest/web/casian-doc ~/web/latest/web/imp-doc ~/web/latest/web/tgm-pipeline`
3. Go into r3-pages repository, and schedule CI/CD execution with `Run pipeline` -> master
4. Go into respective pages repositories, and schedule their CI/CD execution with `Run pipeline` -> master
1. CSS is missing! That means two things:
* Either that you have wrongly set up the CSS URL in your templates, or
* your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
## Faster solution
There is a weekly backup, you might want to recover from it. The location of backups is in the `~/backups` directory.
[ci]: https://about.gitlab.com/gitlab-ci/
[Jekyll]: http://jekyllrb.com/
[install]: https://jekyllrb.com/docs/installation/
[documentation]: https://jekyllrb.com/docs/home/
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
1. SSH into the VM, and remove all the old files `cd ~/web; rm -rf *`
2. Unpack selected backup into `~/web/latest/`
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