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. See the respective sections below for further instructions.

Prerequisites

PHP

Use the PHP version declared by LibreSign’s current composer.json platform configuration and make sure it is also supported by the target Nextcloud branch.

Do not copy a PHP version from this manual into automation. The repository manifests and CI matrix are the source of truth and change as supported Nextcloud versions move forward.

Node.js and npm

Use the Node.js and npm versions declared in LibreSign’s current package.json engines section.

Do not hard-code the versions from this manual in development tooling. The application manifest is the source of truth.

Additional dependencies

• poppler-utils

• System locale configured with UTF-8 charset

Using the VS Code Dev Container

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.

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

• Julius Härtl Nextcloud Setup

Note

If you encounter problems with these setups, please open an issue in the corresponding repository.

When using LibreCodeCoop/nextcloud-docker-development, follow that repository’s current quick-start and hostname documentation. Its shared development proxy exposes each Compose project through its own *.localhost HTTPS hostname instead of requiring a fixed application port.

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.

git clone https://github.com/LibreSign/libresign.git
cd libresign
git submodule update --init

Open a bash session in the Nextcloud container:

docker compose exec -u www-data nextcloud bash

Inside the container, go to apps-extra/libresign and run:

# Download composer dependencies
composer install

# Download JS dependencies
npm ci

# Build and watch JS changes
npm run watch

Configuring LibreSign

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”), continue to the next section to configure the root certificate.

Extra apps

LibreSign also integrates with the following Nextcloud apps:

App	Description
guests	Allows inviting guest users to sign documents.
notifications	Sends notifications about signature requests and updates.
activity	Logs activities such as signature requests and confirmations.
viewer	Enables PDF viewing inside LibreSign without leaving the app.
files_pdfviewer	Required in combination with viewer for proper PDF rendering.