GitLab and TU server - The TUD guide to open publishing with JupyterBook

Updated: 03 Mar 2026

There are (at least) two options for hosting your Jupyter Book through GitLab:

Using GitLab CI to deploy to an external server (e.g. TU server)
Using GitLab Pages to host the book directly on GitLab

https://gitlab.com/pages/jupyterbook

GitLab and server

GitLab and GitLab Pages

Needs

runner
linux website with apache webserver keys variables

.gitlab-ci.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
stages:
  - deploy

image: python:3.11-slim

variables:
  SSH_COMMAND: 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes'
  LOCAL_BUILD_DIR: "_build/html"
  HOST: "127.0.0.1"             # prevents running local host resulting in an error
  BASE_URL: ""                  # specify the base url, e.g. the folder from root
  
before_script:
  - apt-get update
  - apt-get install -y --no-install-recommends curl rsync openssh-client git

  # Node.js
  - curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
  - apt-get install -y --no-install-recommends nodejs
  - node --version
  - npm --version

  # Python deps
  - python -m pip install --upgrade pip
  - pip install mystmd
  - pip install -r requirements.txt

  # SSH key laden
  - eval "$(ssh-agent -s)"
  - chmod 400 "$WEBSITE_UPLOAD_KEY"
  - ssh-add "$WEBSITE_UPLOAD_KEY"

deploy:
  stage: deploy
  script:
    # builds the book
    - myst build --html 
    
    # syncs with the server
    - rsync -ravz "${LOCAL_BUILD_DIR}/" -e "${SSH_COMMAND} -i ${WEBSITE_UPLOAD_KEY}" "${DEPLOY_USER}@${DEPLOY_HOST}:${DEPLOY_PATH}/"

Program 1:.gitlab-ci.yml for TU server deployment

Example from topocondmat¶

The .gitlab-ci.yml below is a second example of how to deploy to an external server. It uses the pixi tool to manage dependencies and caching, which can speed up the build process. It also includes some additional features, such as deploying branch websites and allowing manual stopping of those branch websites.

The building of all branches is recommended as it allows to preview the changes compare to the main branch. If you are happy with the changes you can merge the branch into the main branch, which will trigger the deployment of the main website. This thus allows to fully test the functionalities of the website so that the main website is always working.

.gitlab-ci.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
default:
  image:
    name: ghcr.io/prefix-dev/pixi
  cache:
    key: "$CI_JOB_NAME"
    paths:
      - .pixi
      - _build
  before_script:
    - eval $(pixi shell-hook --shell bash)
    - pixi global install git
    - git config --global --add safe.directory $CI_PROJECT_DIR
    - pixi install
    - eval "$(pixi run ssh-agent -s)"
    - chmod 400 "$WEBSITE_UPLOAD_KEY"
    - pixi run ssh-add "$WEBSITE_UPLOAD_KEY" >/dev/null

variables:
  FF_USE_FASTZIP: "true"
  CACHE_COMPRESSION_LEVEL: "fastest"
  SSH_COMMAND: "ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"
  JUPYTER_NUM_PROCS: "10"
  HOST: "127.0.0.1"  # Needed to avoid binding to ::1.

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        BASE_URL: "/branch_${CI_COMMIT_REF_SLUG}"
    - if: '$CI_COMMIT_BRANCH == "master"'
    - when: never

build branch website:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    WEBSITE_UPLOAD_PATH: /branch_${CI_COMMIT_REF_SLUG}
  environment:
    name: branch/$CI_COMMIT_REF_SLUG
    on_stop: stop branch website
    url: https://topocondmat.org/branch_${CI_COMMIT_REF_SLUG}/
  script:
    - pixi run postprocess-html
    - pixi run rsync -ravz _build/html/ -e "$SSH_COMMAND" uploader@tnw-qn1.tudelft.net:$WEBSITE_UPLOAD_PATH

build main website:
  only:
    - master@qt/topocm
  variables:
    WEBSITE_UPLOAD_PATH: /
  environment:
    name: published
    url: https://topocondmat.org/
  script:
    - pixi run postprocess-html
    - pixi run rsync -ravz _build/html/ -e "$SSH_COMMAND" uploader@tnw-qn1.tudelft.net:$WEBSITE_UPLOAD_PATH

stop branch website:
  needs:
    - build branch website
  script:
    - mkdir -p /tmp/empty_dir
    - pixi run rsync -av --delete /tmp/empty_dir/ -e "$SSH_COMMAND" uploader@tnw-qn1.tudelft.net:$WEBSITE_UPLOAD_PATH/
  when: manual
  environment:
    name: branch/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual
  variables:
    WEBSITE_UPLOAD_PATH: /branch_${CI_COMMIT_REF_SLUG}
  allow_failure: true

Program 2:.gitlab-ci.yml for external server deployment