From d6f104d2a2d162a0f7f77efd6487a33cd83f6db9 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sun, 4 Oct 2026 23:38:46 +0000 Subject: [PATCH 1/4] docs: document the NCDD devcontainer workflow Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../development-environment/setup.rst | 64 +++++++++++++++---- 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/developer_manual/getting-started/development-environment/setup.rst b/developer_manual/getting-started/development-environment/setup.rst index c9653ad..c89fb12 100644 --- a/developer_manual/getting-started/development-environment/setup.rst +++ b/developer_manual/getting-started/development-environment/setup.rst @@ -4,7 +4,7 @@ Setup .. note:: If the project does not have an issue for what you want to work on, please create one first. -If you would like to start contributing code, you may wish to begin with our list of good first issues. +If you would like to start contributing code, you may wish to begin with our list of good first issues. See the respective sections below for further instructions. Prerequisites @@ -33,19 +33,54 @@ application manifest is the source of truth. Additional dependencies +++++++++++++++++++++++ -- ``poppler-utils`` -- System locale configured with UTF-8 charset +- ``poppler-utils`` +- System locale configured with UTF-8 charset -Setting up Nextcloud --------------------- +Using the VS Code Dev Container +------------------------------- -This project depends on Nextcloud. To start writing code, you need a working Nextcloud environment. -We recommend using Docker, but you may use another method if you prefer. +LibreSign's repository contains a Dev Container configuration for contributors +who use VS Code Dev Containers or a compatible implementation. + +The Dev Container is a thin adapter over +`LibreCodeCoop/nextcloud-docker-development +`__ (NCDD). +LibreSign does not maintain a second independent Nextcloud, database, nginx, +Mailpit or Redis topology for this workflow. + +Open the LibreSign repository in VS Code and choose **Reopen in Container**. +During initialization the adapter prepares the pinned NCDD revision used by the +current LibreSign branch. The LibreSign checkout is mounted as +``/var/www/html/apps-extra/libresign`` and LibreSign-specific setup runs after +Nextcloud becomes ready. + +The runtime defaults and supported overrides are defined in LibreSign's current +``.devcontainer`` files. Do not copy their PHP, Nextcloud or database versions +into this manual. + +For an isolated worktree, open that worktree itself in VS Code. Its Dev +Container uses its own Compose project and runtime state, so multiple worktrees +can coexist without fixed application or database host ports. + +The setup output prints the HTTPS hostname for the environment. NCDD exposes +the corresponding Mailpit endpoint through the same shared development proxy. + +When closing or rebuilding an environment, use the Dev Container lifecycle or +project-scoped Compose commands. Do not stop every Docker container on the host +or remove every Docker volume. + +Setting up Nextcloud manually +----------------------------- + +This project depends on Nextcloud. If you are not using the Dev Container, you +need a working Nextcloud environment. + +We recommend using Docker, but you may use another method if you prefer. Suggested setups: -- `LibreCode Coop Setup `__ -- `Julius Härtl Nextcloud Setup `__ +- `LibreCode Coop Setup `__ +- `Julius Härtl Nextcloud Setup `__ .. note:: If you encounter problems with these setups, please open an issue in the corresponding repository. @@ -61,8 +96,9 @@ If the environment does not become ready, use its documented diagnostics and ``docker compose ps``/logs rather than assuming a fixed container name or URL. -Once Nextcloud is running, go to the setup folder and locate ``volumes/nextcloud/apps-extra``. -Clone the LibreSign repository into this folder . +Once Nextcloud is running, go to the setup folder and locate +``volumes/nextcloud/apps-extra``. Clone the LibreSign repository into this +folder. .. code-block:: bash @@ -93,11 +129,11 @@ Inside the container, go to ``apps-extra/libresign`` and run: Configuring LibreSign --------------------- -After setting up the environment and installing LibreSign, open +After setting up the environment and installing LibreSign, open ``Administration Settings > LibreSign`` in Nextcloud and: -- Click the **Download binaries** button. -- Once all items show status **successful** (except “root certificate not configured”), +- Click the **Download binaries** button. +- Once all items show status **successful** (except “root certificate not configured”), continue to the next section to configure the root certificate. From bc12af1b9ec6b80d5654cfb1a9a4eb5357678b04 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sun, 4 Oct 2026 23:52:54 +0000 Subject: [PATCH 2/4] docs: clarify canonical proxy access Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../getting-started/development-environment/setup.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/developer_manual/getting-started/development-environment/setup.rst b/developer_manual/getting-started/development-environment/setup.rst index c89fb12..079ec63 100644 --- a/developer_manual/getting-started/development-environment/setup.rst +++ b/developer_manual/getting-started/development-environment/setup.rst @@ -62,8 +62,13 @@ For an isolated worktree, open that worktree itself in VS Code. Its Dev Container uses its own Compose project and runtime state, so multiple worktrees can coexist without fixed application or database host ports. -The setup output prints the HTTPS hostname for the environment. NCDD exposes -the corresponding Mailpit endpoint through the same shared development proxy. +The setup output prints the canonical HTTPS hostname for the environment. +Nextcloud must be accessed through NCDD's shared proxy using that hostname; +do not bypass it by forwarding the nginx HTTP port directly, because NCDD +configures Nextcloud's trusted domain and overwrite host for the proxy URL. + +Mailpit may be forwarded directly by the Dev Container and is also available +through NCDD's shared development proxy. When closing or rebuilding an environment, use the Dev Container lifecycle or project-scoped Compose commands. Do not stop every Docker container on the host From 4e41a1269faa23f1b3ff076205ebbdff56645edb Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sun, 4 Oct 2026 23:58:29 +0000 Subject: [PATCH 3/4] docs: explain Codespaces browser access Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../development-environment/setup.rst | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/developer_manual/getting-started/development-environment/setup.rst b/developer_manual/getting-started/development-environment/setup.rst index 079ec63..82b002c 100644 --- a/developer_manual/getting-started/development-environment/setup.rst +++ b/developer_manual/getting-started/development-environment/setup.rst @@ -62,13 +62,19 @@ For an isolated worktree, open that worktree itself in VS Code. Its Dev Container uses its own Compose project and runtime state, so multiple worktrees can coexist without fixed application or database host ports. -The setup output prints the canonical HTTPS hostname for the environment. -Nextcloud must be accessed through NCDD's shared proxy using that hostname; -do not bypass it by forwarding the nginx HTTP port directly, because NCDD -configures Nextcloud's trusted domain and overwrite host for the proxy URL. - -Mailpit may be forwarded directly by the Dev Container and is also available -through NCDD's shared development proxy. +For local Docker/VS Code development, the setup output prints the canonical +HTTPS hostname exposed by NCDD's shared proxy. + +GitHub Codespaces uses a different access path because its browser URLs are +based on forwarded ports. The LibreSign adapter detects Codespaces, asks NCDD +to publish that worker's nginx on a dedicated loopback port and configures +Nextcloud's public hostname from ``CODESPACE_NAME`` and +``GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN``. GitHub then exposes that port +through the corresponding ``https://-.`` URL. + +This keeps Nextcloud's trusted domain and overwrite host aligned with the URL +the browser actually uses instead of forwarding nginx under an unrelated +hostname. When closing or rebuilding an environment, use the Dev Container lifecycle or project-scoped Compose commands. Do not stop every Docker container on the host From 1be1ae1dffaddfa8c397bc0c2c7d9a236b7c56f8 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Mon, 5 Oct 2026 00:56:14 +0000 Subject: [PATCH 4/4] docs: align Codespaces access with the shared proxy Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../development-environment/setup.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/developer_manual/getting-started/development-environment/setup.rst b/developer_manual/getting-started/development-environment/setup.rst index 82b002c..2aa6fff 100644 --- a/developer_manual/getting-started/development-environment/setup.rst +++ b/developer_manual/getting-started/development-environment/setup.rst @@ -65,16 +65,18 @@ can coexist without fixed application or database host ports. For local Docker/VS Code development, the setup output prints the canonical HTTPS hostname exposed by NCDD's shared proxy. -GitHub Codespaces uses a different access path because its browser URLs are -based on forwarded ports. The LibreSign adapter detects Codespaces, asks NCDD -to publish that worker's nginx on a dedicated loopback port and configures -Nextcloud's public hostname from ``CODESPACE_NAME`` and -``GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN``. GitHub then exposes that port -through the corresponding ``https://-.`` URL. +GitHub Codespaces uses the same shared NCDD proxy. The Dev Container forwards +``host.docker.internal:443``, which is the Docker host port owned by that +proxy, and configures Nextcloud's public hostname from ``CODESPACE_NAME`` +and ``GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN``. GitHub exposes forwarded +port 443 through the corresponding +``https://-443.`` URL. + +Mailpit is forwarded directly from its Compose service on port 8025. This keeps Nextcloud's trusted domain and overwrite host aligned with the URL -the browser actually uses instead of forwarding nginx under an unrelated -hostname. +the browser actually uses while preserving the proxy as the single HTTP entry +point for Nextcloud. When closing or rebuilding an environment, use the Dev Container lifecycle or project-scoped Compose commands. Do not stop every Docker container on the host