From 376a25946a5f4bb922b0d9bcdb93b32769c3f123 Mon Sep 17 00:00:00 2001 From: Denys Vuika Date: Fri, 3 Jul 2026 13:32:28 +0100 Subject: [PATCH] chore: install gnupg2 for GPG agent forwarding and update devcontainer configuration --- .devcontainer/Dockerfile | 3 +- .devcontainer/README.md | 79 ++++++++++++++++++++++++++++ .devcontainer/devcontainer-lock.json | 9 ++++ .devcontainer/devcontainer.json | 4 +- docs/dev-containers.md | 62 ++++++++++++++-------- 5 files changed, 134 insertions(+), 23 deletions(-) create mode 100644 .devcontainer/README.md create mode 100644 .devcontainer/devcontainer-lock.json diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index a68165c00e..2c3947e9ab 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -9,8 +9,9 @@ ENV PNPM_HOME=/home/node/.local/share/pnpm ENV PATH=${PNPM_HOME}:${PATH} # Install Chromium for Karma/ChromeHeadless test execution inside the container. +# gnupg2 is required so VS Code can forward the host gpg-agent for signed commits. RUN apt-get update \ - && apt-get install -y --no-install-recommends chromium \ + && apt-get install -y --no-install-recommends chromium gnupg2 \ && rm -rf /var/lib/apt/lists/* # Configure Corepack-managed pnpm globally at image build time. diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 0000000000..dad0b2d295 --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,79 @@ +# Dev Container + +Quick start for developing `alfresco-ng2-components` inside the VS Code Dev Container. +For the full guide (Nx targets, daemon, troubleshooting, base-image updates) see +[docs/dev-containers.md](../docs/dev-containers.md). + +## Prerequisites + +- Docker Desktop running +- VS Code with the **Dev Containers** extension (`ms-vscode-remote.remote-containers`) + +## Getting Started + +1. Open the repository in VS Code. +2. Run **Dev Containers: Reopen in Container** from the Command Palette (or accept the prompt). +3. Wait for the post-create step (`pnpm install --frozen-lockfile`) to finish. +4. Use the integrated terminal as usual, e.g. `pn nx test core`. + +Rebuild (**Dev Containers: Rebuild Container**) after changing +[`Dockerfile`](./Dockerfile) or [`devcontainer.json`](./devcontainer.json). + +## What's Included + +- Node base image (digest-pinned) with Corepack-activated **pnpm** +- **Chromium** for Karma / `ChromeHeadless` tests (`CHROME_BIN` is preset) +- **GitHub CLI** (`gh`) via the `github-cli` dev container feature +- **gnupg2** so the host `gpg-agent` can be forwarded for signed commits +- Persistent pnpm store volume and warm Nx daemon (`NX_DAEMON=true`) + +## GitHub CLI + +`gh` is preinstalled. Authenticate once per container: + +```bash +gh auth login +``` + +Or export a token instead: `export GH_TOKEN=`. + +## Signed Commits With Host Credentials + +The VS Code Dev Containers extension handles this automatically — your private +keys never enter the container, only the agent socket is forwarded: + +- Your host **`.gitconfig`** (including `user.signingkey` and `commit.gpgsign`) + is copied into the container. +- Your host **`gpg-agent`** is forwarded (this is why `gnupg2` is installed), and + your GPG **public** keys are imported into the container. +- Your host **SSH agent** is forwarded, so `git push` over SSH uses your host keys. + +### One-time host setup + +Make sure signing is configured on the **host** (this is what gets copied in): + +```bash +git config --global user.signingkey +git config --global commit.gpgsign true +``` + +Then, inside the container, verify the key is visible before committing: + +```bash +gpg --list-secret-keys +git commit -S -m "your message" # -S optional if commit.gpgsign is true +git push +``` + +### If signing fails + +- Getting `error: gpg failed to sign the data` / `no secret key`? The agent + forwarding didn't attach — **Rebuild Container** or reload the VS Code window. +- Confirm `gnupg2` is present: `gpg --version`. +- The automatic gitconfig / GPG / SSH forwarding is a feature of the **VS Code + Dev Containers extension**. If you run this config via the plain + `@devcontainers/cli`, you must mount `~/.gnupg`, `~/.gitconfig`, and the agent + sockets yourself. + +See [docs/dev-containers.md](../docs/dev-containers.md#git-operations-and-signing) +for alternative signing strategies (host-only signing, CI-enforced signing). diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.json new file mode 100644 index 0000000000..cdd61126b1 --- /dev/null +++ b/.devcontainer/devcontainer-lock.json @@ -0,0 +1,9 @@ +{ + "features": { + "ghcr.io/devcontainers/features/github-cli:1": { + "version": "1.1.0", + "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671", + "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671" + } + } +} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index dc6b6940f9..eb36397bdb 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,7 +12,9 @@ }, // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, + "features": { + "ghcr.io/devcontainers/features/github-cli:1": {} + }, "remoteUser": "node", "containerUser": "node", diff --git a/docs/dev-containers.md b/docs/dev-containers.md index 3e45682f90..98c01ce072 100644 --- a/docs/dev-containers.md +++ b/docs/dev-containers.md @@ -50,33 +50,53 @@ When running Nx commands, VS Code may show a notification about a port being ope ## Git Operations and Signing -You can use Git inside the container, outside the container, or split responsibilities for better key safety. +The container is set up so you can do all Git work — including signed commits and +pushes — inside it, using your host credentials and settings. Your private keys +never enter the container: only the agent socket is forwarded. -Recommended secure default: +### Option A: Commit and Sign in Container (Recommended) -1. Build, test, and edit code inside the container. -2. Create signed commits outside the container on the host machine. +The VS Code Dev Containers extension wires this up automatically: -This reduces exposure of signing keys to container processes while keeping day-to-day development reproducible. +- Your host `.gitconfig` (including `user.signingkey` and `commit.gpgsign`) is + copied into the container. +- Your host `gpg-agent` is forwarded (this is why `gnupg2` is installed in the + image), and your GPG public keys are imported into the container. +- Your host SSH agent is forwarded, so `git push` over SSH uses your host keys. -### Option A: Sign Commits on Host (Recommended) +One-time host setup (this is what gets copied in): + +```bash +git config --global user.signingkey +git config --global commit.gpgsign true +``` + +Then work entirely inside the container: + +```bash +gpg --list-secret-keys # verify the forwarded key is visible +git commit -S -m "your message" # -S optional when commit.gpgsign is true +git push +``` + +If signing fails with `gpg failed to sign the data` / `no secret key`, the agent +forwarding did not attach — rebuild the container or reload the VS Code window. + +> Note: the automatic gitconfig / GPG / SSH forwarding is a feature of the VS Code +> Dev Containers extension. If you run this configuration via the plain +> `@devcontainers/cli`, mount `~/.gnupg`, `~/.gitconfig`, and the agent sockets +> yourself, or fall back to Option B. + +### Option B: Sign Commits on Host + +For the strongest key isolation, keep signing on the host: - Keep private signing keys only on the host. - Do normal development in the container. -- Stage and commit from a host terminal in the same repository checkout. -- Run signed commit commands on host (for example, `git commit -S ...`). +- Stage and commit from a host terminal in the same repository checkout + (for example, `git commit -S ...`). -Good fit when your policy requires strong key isolation. - -### Option B: Commit and Sign in Container (With Care) - -If your team prefers full in-container Git operations, use one of these approaches: - -- Forward SSH agent into the container and use SSH signing. -- Forward GPG agent/socket into the container instead of copying private keys. -- Avoid storing raw private keys directly in container filesystems. - -This keeps workflows convenient, but still requires careful host and container trust settings. +Good fit when your policy forbids forwarding signing agents into containers. ### Option C: Unsigned Commits in Container, Signed Merge in CI/Host @@ -88,8 +108,8 @@ This can simplify local setup for contributors while preserving integrity checks ### Practical Daily Pattern 1. Code, lint, and test in the container. -2. Review and commit on host with signing enabled. -3. Push from host (or container) based on your credential policy. +2. Commit and sign in the container using the forwarded host keys. +3. Push from the container (SSH agent or `gh` credentials are forwarded). 4. Keep branch protection checks active (status checks, review, signature policy if used). ## Updating Base Image Safely