Installation (per-machine / do once per user)

This page contains per-machine installation steps required once by each developer. Use the commands shown for PowerShell (pwsh) or POSIX shells (bash). Where a command differs between OSes both variants are shown.

Install UV (astral-sh/uv)

Documentation: https://docs.astral.sh/uv/getting-started/installation/

PowerShell (pwsh):

# Install via winget (Windows 10/11)
winget install --id=astral-sh.uv -e
# Verify installation
uv --version

bash (POSIX):

# Official installer (POSIX shells for macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Alternatively, you can also use apt (Debian based Linux):
# sudo apt install uv

# Alternatively, you can also use Homebrew (macOS):
# brew install uv

# Restart shell, then verify
uv --version

Install Pre-commit

Use pre-commit as a local quality check.

Terminal (pwsh / bash):

# Install pre-commit into your user uv-managed toolset
uv tool install pre-commit --with pre-commit-uv
# (Optional: if suggested by terminal output)
uv tool update-shell
# Verify installation
pre-commit --version

Install Commitizen

Use commitizen to create standardized commit messages.

Terminal (pwsh / bash):

# Install commitizen into your user uv-managed toolset
uv tool install commitizen
# (Optional: if suggested by terminal output)
uv tool update-shell
# Verify installation
pre-commit --version

Install Git Filter Repo (for publishing to GitHub)

Use git-filter-repo to remove private files and folders when publishing updates to GitHub.

Terminal (pwsh / bash):

# Install git-filter-repo into your user uv-managed toolset
uv tool install git-filter-repo
# (Optional: if suggested by terminal output)
uv tool update-shell
# Verify installation
git filter-repo --version

GitLab sign-in (self-hosted GitLab)

This repository uses a self-hosted GitLab instance. Create a Personal Access Token (PAT) in the GitLab web UI and add it to your IDE or credential store.

  • Server URL: https://gitlab.it.fhv.at

Create an SSH key pair (if you don’t have one already):

  1. Open a terminal.
  2. Run ssh-keygen -t followed by the key type and an optional comment. You may want to use an email address for the comment.
ssh-keygen -t ed25519 -C "user@email.domain"
  1. Press Enter. Output similar to the following is displayed:
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
  1. Accept the suggested filename and directory, unless you are generating a deploy key or want to save in a specific directory where you store other keys. You can also dedicate the SSH key pair to a specific host.
  2. Specify a passphrase:
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

A confirmation is displayed, including information about where your files are stored. A public and private key are generated. Add the public SSH key to your GitLab account and keep the private key secure.

Add an SSH key to your GitLab account (if you don’t have already)

To use SSH with GitLab, copy your public key to your GitLab account:

  1. Copy the contents of your public key file. You can do this manually or use a script.
  2. Sign in to GitLab.
  3. On the left sidebar, select your avatar.
  4. Select Edit profile.
  5. On the left sidebar, select SSH Keys.
  6. Select Add new key.
  7. In the Key box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, sk-ecdsa-sha2-nistp256@openssh.com, or sk-ssh-ed25519@openssh.com, and may end with a comment.
  8. In the Title box, type a description, like Work Laptop or Home Workstation.
  9. Optional. Select the Usage type of the key. It can be used either for Authentication or Signing or both. Authentication & Signing is the default value.
  10. Optional. Update Expiration date to modify the default expiration date.
    1. Administrators can view expiration dates and use them for guidance when deleting keys.
    2. GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now.
    3. GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date.
  11. Select Add key.

Add GitLab Account to IDE

VS Code: Install the “GitLab Workflow” extension and add the server and token from the command palette.

PyCharm: Menu > Git > GitLab > Manage Accounts > Add Account, set server URL and paste token.

Optional: Docker (for local CI runs)

Docker is only required if you plan to run local GitLab CI or local GitHub Actions or other jobs that depend on containers. Install Docker Desktop or your platform’s Docker engine:

Terminal (pwsh):

# Install Docker Desktop via winget (Windows 10/11)
winget install -e --id Docker.DockerDesktop
docker --version