HelpFIT
Go to navigation

Configuration

Getting Started

To create your own website, use one of the following approaches:

  1. From a template (minimal configuration)
  2. Sample .gitlab-ci.yml
  3. Custom configuration

To configure permissions using a CTU account and roles, see .fit-pages.yml.

How It Works

The service can be divided into several parts:

  1. Source repository in GitLab
  2. Output generation in CI
  3. Website publishing
  4. Access authorization

The input is a source repository where users make the required changes. Based on a predefined action, a pipeline is triggered that generates static content (i.e., HTML, CSS, JS, images, PDFs, etc.) from the source repository into the /public directory.

To achieve this, you can use one of many static site generators (SSGs). Popular generators include Jekyll, Zola, Hugo, Next.js, and more can be found at jamstack.org. You can also use documentation generators from source code (e.g., JSDoc, YARD, Doxygen…​), (Xe)LaTeX, Asciidoctor, etc. Or simply add HTML and other static files directly to the repository without any generation step.

GitLab also provides history tracking, change approval workflows (merge requests), and more.

You can read more about static site generators, the difference between dynamic and static websites, etc., for example here or here.

architecture diagram.en
Figure 1. PagesFIT architecture.

Domains and URLs

All users automatically have access to space under the https://pages.fit domain, while FIT staff may additionally use the https://pages.fit.cvut.cz domain. [1] The specific domain is selected in the configuration.

FIT staff may also request registration of their own domain under .fit.cvut.cz through the ICT department’s helpdesk.

Any[2] GitLab repository can serve as the source for a website on one of the listed domains or on a custom domain. Repositories are mapped to *.pages.fit or pages.fit.cvut.cz according to the following scheme:

*.pages.fit
gitlab.fit.cvut.cz/<namespace>/[<subgroup>/[<subsubgroup>/]]<project-slug>/tree/<branch>/
→ https://<namespace>.pages.fit/[<subgroup>/[<subsubgroup>/]][<project-slug>/][@<branch>/]
pages.fit.cvut.cz
gitlab.fit.cvut.cz/<namespace>/[<subgroup>/[<subsubgroup>/]]<project-slug>/tree/<branch>/
→ https://pages.fit.cvut.cz/<namespace>/[<subgroup>/[<subsubgroup>/]][<project-slug>/][@<branch>/]

The following sections contain concrete mapping examples for different use cases.

The default file for a directory (when no filename is specified) is always index.html.

General Case

A repository for a website may be located in a user’s personal namespace, any group, or even a subgroup (and sub-subgroup).

Examples:
*.pages.fit

gitlab.fit.cvut.cz/flynnkev/clu → https://flynnkev.pages.fit/clu/

gitlab.fit.cvut.cz/grid/programs/tron → https://grid.pages.fit/programs/tron/

pages.fit.cvut.cz

gitlab.fit.cvut.cz/flynnkev/clu → https://pages.fit.cvut.cz/flynnkev/clu/

gitlab.fit.cvut.cz/grid/programs/tron → https://pages.fit.cvut.cz/grid/programs/tron/

Namespace Websites

If you name the repository the same as the first-level parent namespace (user or global group), one level is omitted from the website URL. This is ideal for personal websites, department websites, research group websites, etc.

Examples:
*.pages.fit

gitlab.fit.cvut.cz/flynnkev/flynnkev → https://flynnkev.pages.fit/

pages.fit.cvut.cz

gitlab.fit.cvut.cz/flynnkev/flynnkev → https://pages.fit.cvut.cz/flynnkev/

Branches

Content from branches other than master is automatically published at <site-url>/@<branch-name>/, where <site-url> is the base URL of the website (see above).

This can be used, for example, for ongoing development of changes that should only be published once completed, while still having a preview available. Simply create a new branch (optionally with a merge request), commit changes to it, and when finished, merge it into the main branch and delete it.

Different permissions can also be configured for different branches (see .fit-pages.yml), for example making the main branch public while restricting other branches to department members only.

Examples:
*.pages.fit

gitlab.fit.cvut.cz/flynnkev/clu/tree/dev → https://flynnkev.pages.fit/clue/@dev/

gitlab.fit.cvut.cz/flynnkev/flynnkev/tree/dev → https://flynnkev.pages.fit/@dev/

pages.fit.cvut.cz

gitlab.fit.cvut.cz/flynnkev/clu/tree/dev → https://pages.fit.cvut.cz/flynnkev/clue/@dev/

gitlab.fit.cvut.cz/flynnkev/flynnkev/tree/dev → https://pages.fit.cvut.cz/flynnkev/@dev/

Configuration

To create and configure a new website, follow these steps:

  1. Go to GitLab and create a new project in the desired namespace [3] (hereinafter the source repository).

    Warning:

    Newly created repositories start with a default branch named main. However, the PagesFIT service still assumes that the main repository branch is named master. You therefore need to create a branch named master and perform the following steps in that branch. We also recommend setting master as the default project branch.

  2. Navigate to Settings › Webhooks and configure the following settings:
    • URL – Choose according to the desired domain:
      • for *.pages.fit enter: https://pages.fit/hooks/deploy
      • for all others (except Courses): https://pages.fit.cvut.cz/hooks/deploy
    • Trigger: Push events, Job events, Pipeline events

    • Enable SSL verification: ✅

      webhooks.en

  3. Add a .gitlab-ci.yml file to the root directory of the project in the master branch using Web Interface. The file must contain the following deploy job. For more examples, see Templates.

    Minimum example of a .gitlab-ci.yml file that simply deploys all HTML files. For examples using various generators, see Templates.
    pages:
  stage: deploy
  image: {alpine-image-ci-latest}
  script:
    - mkdir -p public/
    # .fit-pages.yml must be in public/
    - cp .fit-pages.yml public/
    # Do whatever you need to generate static content of your web, for example:
    - cp *.html public/
  artifacts:
    paths:
      - public/
    expire_in: 1 hour

  4. Add a .fit-pages.yml file to the root directory of the project in the master branch using Web Interface and configure it as needed. For more details, see .fit-pages.yml.

    Minimum example of .fit-pages.yml
    # Uncomment if you want to deploy pages to pages.fit.cvut.cz instead of *.pages.fit.
# domain: pages.fit.cvut.cz

# Allow anyone to access site from the master branch, require authentication to
# access any other branches (e.g., /@dev/index.html).
access:
  master:
    /:
      allow: [ANONYMOUS]
  '*':
    /:
      allow: [AUTHENTICATED]
    Important:
    PagesFIT Access Rights vs GitLab

    PagesFIT access rights are completely independent of the access rights of the source repository in GitLab! This means that if you need to restrict access to the entire website or selected sections to only a specific subset of authenticated users, and prevent access by others, you must set the visibility of the source repository to Private.

  5. Adding or modifying files starts the generation process (the pipeline). The status of the pipeline, including error logs, can be monitored on the CI / CD › Pipelines page.
  6. After the pipeline completes successfully, the website is automatically published to the selected domain according to Domains and URLs.
  1. Multiple domains can be used for a single website. However, we strongly recommend that a website have only one domain. ↩
  2. There is currently a limitation to repositories (projects) up to the third level of namespace nesting; for example, /group-1/group-2/group-3/repo-name is supported, but /group-1/group-2/group-3/group-4/repo-name cannot be mapped to the shared domains. If you need this functionality, please contact the helpdesk. ↩
  3. Permissions for creating projects, configuring CI/CD, etc., are governed by GitLab permissions. For more information, see GitLab and Permissions. ↩