Skip to content

Commit 655134f

Browse files
veitveit
committed
📝 Add GitLab CI/CD examples
* GitLab Pages * npm deployment with rsync * Multi-Arch-Images with Buildah
1 parent 4283a31 commit 655134f

File tree

13 files changed

+318
-26
lines changed

13 files changed

+318
-26
lines changed

‎docs/productive/envs/uv/cicd.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ CI/CD pipelines
66
GitLab CI/CD
77
------------
88

9-
For :doc:`GitLab CI/CD pipelines </productive/git/advanced/gitlab/ci-cd>` there
10-
are various Docker images with pre-installed ``uv``: Available images
9+
For :doc:`GitLab CI/CD pipelines
10+
</productive/git/advanced/gitlab/ci-cd/index>`>` there are various Docker images
11+
with pre-installed ``uv``: Available images
1112
<https://docs.astral.sh/uv/guides/integration/docker/#available-images>`_.
1213

1314
.. code-block:: yaml

‎docs/productive/git/advanced/gitlab/ci-cd/buildah.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
.. SPDX-FileCopyrightText: 2022–2025 Veit Schiele
2+
..
3+
.. SPDX-License-Identifier: BSD-3-Clause
4+
5+
Multi-arch images with Buildah
6+
==============================
7+
8+
`Buildah <https://buildah.io>`_ allows you to create container images without
9+
the need for a full container runtime. Buildah is an open-source Linux-based
10+
tool that can create `Docker <https://www.docker.com>`_ and
11+
`Kubernetes <https://kubernetes.io>`_-compatible images. In addition, Buildah
12+
can not only create working containers from scratch, but also from an existing
13+
Dockerfile. Finally, it can be easily integrated into scripts and build
14+
pipelines.
15+
16+
First steps
17+
-----------
18+
19+
#. Set up environment variables
20+
21+
``DEPLOY_USER``
22+
Name of the account.
23+
``DEPLOY_KEY_FILE``
24+
Path to a private SSH key that is to be used for authentication against
25+
the server.
26+
``DEPLOY_HOST``
27+
Host name or IP address of the server to be deployed to.
28+
29+
#. Setting up the CI/CD pipeline
30+
31+
.. code-block:: yaml
32+
:caption: .gitlab-ci.yml
33+
:linenos:
34+
35+
stages:
36+
- build
37+
- deploy
38+
39+
build_docker:
40+
stage: build
41+
variables:
42+
DOCKER_STEM: $CI_REGISTRY_IMAGE
43+
image: quay.io/buildah/stable:v1.27
44+
script:
45+
- apk add --no-cache openssh
46+
- chmod 0600 "$DEPLOY_KEY_FILE"
47+
- ./build.sh
48+
49+
deploy_app:
50+
stage: deploy
51+
image: alpine
52+
environment:
53+
name: app
54+
deployment_tier: staging
55+
when: manual
56+
script:
57+
- apk add --no-cache openssh
58+
- chmod 0600 "$DEPLOY_KEY"
59+
- ./deploy.sh
60+
61+
#. Building the Docker container
62+
63+
.. code-block:: sh
64+
:caption: build.sh
65+
:linenos:
66+
:emphasize-lines: 2, 5, 8
67+
68+
# Registry login
69+
echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
70+
71+
# Set docker tag
72+
if [ "$CI_COMMIT_BRANCH" == main ]; then export DOCKER_TAG="latest"; else export DOCKER_TAG="${CI_COMMIT_TAG:-$CI_COMMIT_REF_SLUG}"; fi; export DOCKER_TAG_FULL="$DOCKER_STEM:$DOCKER_TAG"; echo "DOCKER_TAG_FULL=$DOCKER_TAG_FULL"
73+
74+
# Build and push
75+
buildah build --isolation chroot --storage-driver vfs --jobs 2 --platform linux/amd64,linux/arm/v7 --manifest "$DOCKER_TAG_FULL" && buildah --storage-driver vfs images && buildah manifest push --storage-driver vfs --format v2s2 --all "$DOCKER_TAG_FULL" "docker://$DOCKER_TAG_FULL"
76+
77+
Line 2
78+
logs in to the :doc:`../package-registry`.
79+
Line 5
80+
identifies the images by their branch or tag names with the exception of
81+
``main``, which is labelled with ``latest``.
82+
Line 8
83+
builds the images and deploys them with the `VFS
84+
<https://docs.docker.com/engine/storage/drivers/vfs-driver/>`_ driver.
85+
86+
#. Deploy
87+
88+
.. code-block:: sh
89+
:caption: deploy.sh
90+
:linenos:
91+
92+
# Set docker tag
93+
if [ "$CI_COMMIT_BRANCH" == main ]; then export DOCKER_TAG="latest"; else export DOCKER_TAG="${CI_COMMIT_TAG:-$CI_COMMIT_REF_SLUG}"; fi; export DOCKER_TAG_FULL="$DOCKER_STEM:$DOCKER_TAG"; echo "DOCKER_TAG_FULL=$DOCKER_TAG_FULL"
94+
95+
echo "$CI_REGISTRY $DEPLOY_USER $DEPLOY_PASSWORD MYAPP $DOCKER_TAG" | ssh -o 'BatchMode yes' -o 'StrictHostKeyChecking accept-new' -i "$DEPLOY_KEY" root@$DEPLOY_HOST

docs/productive/git/advanced/gitlab/ci-cd-pipeline.png renamed to docs/productive/git/advanced/gitlab/ci-cd/ci-cd-pipeline.png

File renamed without changes.

docs/productive/git/advanced/gitlab/ci-cd-pipeline.png.license renamed to docs/productive/git/advanced/gitlab/ci-cd/ci-cd-pipeline.png.license

File renamed without changes.

docs/productive/git/advanced/gitlab/docker.rst renamed to docs/productive/git/advanced/gitlab/ci-cd/docker.rst

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1+
.. SPDX-FileCopyrightText: 2024–2025 Veit Schiele
2+
..
3+
.. SPDX-License-Identifier: BSD-3-Clause
4+
15
Building Docker containers
26
==========================
37

4-
We use :doc:`ci-cd`, to create our Python Docker containers.
8+
We use :doc:`index`, to create our Python Docker containers.
59

610
#. First, we define the Python version in our :ref:`pyproject-toml` file of the
711
project:

docs/productive/git/advanced/gitlab/github-migration.rst renamed to docs/productive/git/advanced/gitlab/ci-cd/github-migration.rst

File renamed without changes.

docs/productive/git/advanced/gitlab/ci-cd.rst renamed to docs/productive/git/advanced/gitlab/ci-cd/index.rst

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ The three main approaches to this continuous development are:
1616
Continuous Integration
1717
runs a series of scripts sequentially or in parallel that your application
1818
automatically builds and tests, for example after each ``git pull`` in a
19-
:doc:`feature branch <../../workflows/feature-branches>`. This is to make it
20-
less likely that you will introduce bugs into your application.
19+
:doc:`feature branch <../../../workflows/feature-branches>`. This is to make
20+
it less likely that you will introduce bugs into your application.
2121

2222
If the checks work as expected, you can make a :doc:`merge request
23-
<merge-requests>`; if the checks fail, you can revert the changes if
23+
<../merge-requests>`; if the checks fail, you can revert the changes if
2424
necessary.
2525

2626
.. seealso::
@@ -151,7 +151,7 @@ Show pipelines
151151

152152
You can find the current and historical pipeline runs on the
153153
:menuselection:`CI/CD --> Pipelines` page of your project. You can also access
154-
pipelines for a :doc:`merge request <merge-requests>` by navigating to their
154+
pipelines for a :doc:`merge request <../merge-requests>` by navigating to their
155155
:guilabel:`Pipelines` tab. Select a pipeline to open the *Pipeline Details* page
156156
and view the jobs that have been run for that pipeline. From here you can cancel
157157
a running pipeline, retry *jobs* in a failed pipeline or delete a pipeline.
@@ -170,3 +170,12 @@ a running pipeline, retry *jobs* in a failed pipeline or delete a pipeline.
170170
<https://docs.gitlab.com/ee/ci/variables/index.html>`_
171171
* `GitLab Docs: Predefined variables reference
172172
<https://docs.gitlab.com/ee/ci/variables/predefined_variables.html>`_
173+
174+
.. toctree::
175+
:hidden:
176+
177+
pages
178+
npm
179+
docker
180+
buildah
181+
github-migration

‎docs/productive/git/advanced/gitlab/ci-cd/npm.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. SPDX-FileCopyrightText: 2025 Veit Schiele
2+
..
3+
.. SPDX-License-Identifier: BSD-3-Clause
4+
5+
npm deployment with rsync
6+
=========================
7+
8+
`npm <https://www.npmjs.com>`_ is a package manager for the JavaScript runtime
9+
environment `Node.js <https://nodejs.org/en/>`_, and `rsync
10+
<https://rsync.samba.org>`_ can be used to synchronise the data with the remote
11+
server.
12+
13+
First steps
14+
-----------
15+
16+
#. Set up environment variables
17+
18+
``DEPLOY_DIR``
19+
Directory on the remote server to which data is to be distributed..
20+
``DEPLOY_HOST``
21+
Host name or IP address of the server to be deployed to.
22+
``DEPLOY_KEY_FILE``
23+
Path to a private SSH key that is to be used for authentication against
24+
the server.
25+
``DEPLOY_USER``
26+
Name of the SSH account.
27+
``KNOWN_HOSTS_FILE``
28+
Path to a file with predefined :file:`known_hosts` entries with which
29+
the connection is to be checked.
30+
31+
#. Setting up the CI/CD pipeline
32+
33+
.. code-block:: yaml
34+
:caption: .gitlab-ci.yml
35+
:emphasize-lines: 13, 14, 15
36+
37+
stages:
38+
- deploy
39+
40+
deploy-static-assets:
41+
stage: deploy
42+
rules:
43+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
44+
environment:
45+
name: prod
46+
deployment_tier: production
47+
image: node:alpine
48+
script:
49+
- apk add --no-cache git nodejs npm openssh-client-default rsync
50+
- chmod 0600 "$DEPLOY_KEY_FILE"
51+
- ./deploy.sh
52+
53+
Line 13
54+
installs the packages required for building and uploading
55+
Line 14
56+
changes the access authorisations for the ssh key
57+
Line 15
58+
calls the :file:`deploy.sh` file
59+
60+
#. Moves the static files to the server
61+
62+
.. code-block:: sh
63+
:caption: deploy.sh
64+
:linenos:
65+
:emphasize-lines: 7-13, 18, 19, 24, 25-31
66+
67+
#!/bin/sh
68+
set -e
69+
70+
# Deploy static assets to a server via rsync.
71+
72+
# Create SSH config.
73+
cat >deploy.ssh_config <<-END
74+
Host deploy
75+
HostName $DEPLOY_HOST
76+
User $DEPLOY_USER
77+
IdentityFile $DEPLOY_KEY_FILE
78+
UserKnownHostsFile $KNOWN_HOSTS_FILE
79+
END
80+
81+
82+
# Build the JavaScript application & related files.
83+
cd vite-app
84+
npm ci
85+
npx vite build
86+
87+
# Deploy the application and GeoJSON data.
88+
rsync \
89+
-rtlv \
90+
--rsh 'ssh -F ../deploy.ssh_config' \
91+
--rsync-path "mkdir -p \"$DEPLOY_DIR\" && rsync" \
92+
../data/cusy.geojson \
93+
cusy.html \
94+
dist/cusy-map.css \
95+
dist/cusy-map.js \
96+
dist/cusy-map.js.map \
97+
"deploy:$DEPLOY_DIR"
98+
99+
Line 7–13
100+
creates the ssh configuration file.
101+
102+
Line 18
103+
installs the dependencies of the project from the
104+
:file:`vite-app/package.json` file.
105+
106+
.. seealso::
107+
`npm-ci <https://docs.npmjs.com/cli/v9/commands/npm-ci>`_
108+
109+
Line 19
110+
creates the `vite <https://vite.dev>`_ project for production.
111+
112+
Line 24
113+
moves the ssh configuration to the server.
114+
115+
Lines 25–31
116+
moves the application and GeoJSON data to the server.

‎docs/productive/git/advanced/gitlab/ci-cd/pages.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. SPDX-FileCopyrightText: 2025 Veit Schiele
2+
..
3+
.. SPDX-License-Identifier: BSD-3-Clause
4+
5+
GitLab Pages
6+
============
7+
8+
With GitLab Pages, static websites can be published directly from a repository
9+
in GitLab.
10+
11+
These websites are automatically deployed with :doc:`index` pipelines and
12+
support static website generators such as
13+
:doc:`python-basics:document/sphinx/index` `Hugo <https://gohugo.io>`_, `Jekyll
14+
<https://jekyllrb.com>`_ or `Gatsby <https://www.gatsbyjs.com>`_. They can be
15+
connected to custom domains and SSL/TLS certificates.
16+
17+
First steps
18+
-----------
19+
20+
#. First create a :file:`.gitlab-ci.yml` file, for
21+
:doc:`python-basics:document/sphinx/index` for example with the following
22+
content:
23+
24+
.. code-block:: yaml
25+
:caption: gitlab-ci.yml
26+
:linenos:
27+
:emphasize-lines: 6, 15, 18
28+
29+
image: python:latest
30+
31+
stages:
32+
- deploy
33+
34+
pages:
35+
stage: deploy
36+
rules:
37+
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
38+
before_script:
39+
- python -m pip install furo sphinxext-opengraph sphinx-copybutton sphinx_inline_tabs
40+
script:
41+
- cd docs && make html
42+
after_script:
43+
- mv docs/_build/html/ ./public/
44+
artifacts:
45+
paths:
46+
- public
47+
48+
Line 6
49+
GitLab recognises from the job name ``pages`` that you want to provide a
50+
GitLab Pages website.
51+
Lines 15, 18
52+
GitLab always makes your website available from a specific folder called
53+
:file:`public` in your repository.
54+
55+
#. GitLab Pages provides default domain names based on your account or group
56+
name and project. Predictable URLs are generated from these. For the cusy
57+
GitLab instance, this is ``pages.cusy.io``. If your project is accessible at
58+
:samp:`https://ce.cusy.io/{GROUPNAME}/{PROJECTNAME}`, then the associated
59+
GitLab Pages are accessible at
60+
:samp:`https://{GROUPNAME}.pages.cusy.io/{PROJECTNAME}`.
61+
62+
.. seealso::
63+
GitLab Pages also supports custom domains. You can find more information
64+
at `GitLab Pages custom domains
65+
<https://docs.gitlab.com/user/project/pages/custom_domains_ssl_tls_certification/>`_.

‎docs/productive/git/advanced/gitlab/index.rst‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ as well as a Wiki and Snippets. The GitLab Community Edition (CE) is developed
1313
as open source software under the MIT licence and can be installed on-premises.
1414

1515
The GitLab CI tools enable automated builds and deployments without the need for
16-
external integrations, for example building a Docker container with the Python
17-
version of the project.
16+
external integrations, for example :doc:`building a Docker container with the
17+
Python version of the project <ci-cd/docker>`.
1818

1919
If a PaaS solution such as `Kubernetes
2020
<https://en.wikipedia.org/wiki/Kubernetes>`_ is already in use, GitLab-CI/CD can
@@ -34,7 +34,5 @@ integrated, for example with Asana, Jira, Microsoft Teams, Slack, etc.
3434

3535
roles-permissions
3636
merge-requests
37-
ci-cd
38-
docker
39-
github-migration
37+
ci-cd/index
4038
package-registry

0 commit comments

Comments
 (0)