Document the NCDD-backed devcontainer workflow

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,67 @@ 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
+<https://github.com/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.
+
+For local Docker/VS Code development, the setup output prints the canonical
+HTTPS hostname exposed by NCDD's shared proxy.
+
+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://<codespace>-443.<domain>`` 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 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
+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 <https://github.com/LibreCodeCoop/nextcloud-docker-development/>`__  
-- `Julius Härtl Nextcloud Setup <https://github.com/juliushaertl/nextcloud-docker-dev/>`__  
+- `LibreCode Coop Setup <https://github.com/LibreCodeCoop/nextcloud-docker-development/>`__
+- `Julius Härtl Nextcloud Setup <https://github.com/juliushaertl/nextcloud-docker-dev/>`__
 
 .. note::
    If you encounter problems with these setups, please open an issue in the corresponding repository.
@@ -61,8 +109,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 +142,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.