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
Pipeline #19394 passed with stages
in 1 minute and 4 seconds
![Build Status](
# R3-pages
This is a repository containing source for the index pages of []( and its frozen pages.
Note that the sites from _Websites_ menu tab, are contained in their own repositories:
* TGM-pipeline at []()
* CASian at [](
* IMP at [](
Example [Jekyll] website using GitLab Pages. View it live at
# 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 [](` if you need more information).
[Learn more about GitLab Pages]( or read the the [official GitLab Pages documentation](
## 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]( 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 ``.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
**Table of Contents** *generated with [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
JEKYLL_ENV: production
- bundle install
- bundle exec jekyll build -d public
- public
- 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 ``, 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]( demonstrates how you can keep your GitLab Pages site in one branch and your project's source code in another.
* The [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 `` 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 ``, 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`)
enabled: true # Note, that setting it to disabled does not disable it completely, as it has to be also set to false in `` 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 `` file from project's root directory.
Refer to its [documentation]( 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.
1. SSH into the VM, and remove all the old files `cd ~/web; rm -rf *`
2. Unpack selected backup into `~/web/latest/`
Supports Markdown
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