improve README structure and installation instructions by yharroch · Pull Request #6988 · LibreSign/libresign

yharroch · 2026-02-21T15:09:33Z

Add Quick Links and improve section structure
Document occ libresign:install and libresign:configure:* usage
Clarify standalone dependencies in appdata directory
Improve license and security references

- Add Quick Links and improve section structure - Document occ libresign:install and libresign:configure:* usage - Clarify standalone dependencies in appdata directory - Improve license and security references Signed-off-by: yharroch <82467465+yharroch@users.noreply.github.com>

vitormattos

This is great! The README needed some love. Thanks for taking the initiative.

I feel that some parts read more like full documentation than a README, and a bit too detailed for this level. Maybe we can keep it more focused on what LibreSign is and its core principles, and move deeper explanations to the documentation repository.

I’ve added a few suggestions in the PR to start the review and show the direction I’m thinking about. Happy to iterate together.

vitormattos · 2026-02-21T15:56:11Z

README.md

+## Documentation
+
+Complete guides are available for:
+
+- 🔧 Administrators (installation, configuration, certificates)
+- 👥 Users (how to request and sign documents)
+- 🧪 Developers (architecture and API)
+
+👉 https://github.com/LibreSign/documentation


The url of documentation page:

https://docs.libresign.coop

Is the site of this respository

good for me :)

vitormattos · 2026-02-21T15:57:47Z

README.md

+### 1️⃣ Install dependencies
+Run the following command as your web server user:
+`occ libresign:install --java --pdftk --jsignpdf`
+
+This will install:
+- Java (standalone JRE)
+- PDFtk
+- JSignPdf
+
+All binaries are installed inside the Nextcloud `data/appdata_*/libresign` directory.
+No system-wide installation is required.
+
+### 2️⃣ Verify installation
+`sudo -u www-data php /path/to/nextcloud/occ libresign:configure:check`
+
+This command verifies:
+- Java availability
+- PDFtk setup
+- JSignPdf setup
+- OpenSSL configuration
+- Certificate environment
+
+### 3️⃣ Configure root certificate
+You can generate a certificate using OpenSSL or CFSSL.
+
+Example using OpenSSL:
+`sudo -u www-data php /path/to/nextcloud/occ libresign:configure:openssl --cn="Your Organization - Digital Signature" --o="Your Organization" --c="FR" --st="Region" --l="City"`
+
+Certificates are generated and stored inside the Nextcloud data directory: `nextcloud_data_dir/appdata_*/libresign`
+
+No additional server-level configuration is required.
+
+📖 For full configuration details, advanced setups, and troubleshooting:
+https://github.com/LibreSign/documentation


I think that would be best to add the install by CLI to documentation page at administration section

vitormattos · 2026-02-21T16:04:34Z

README.md

+LibreSign installs all required binaries in standalone mode inside the Nextcloud data directory.
+This design improves portability and avoids dependency conflicts with the host system.
+
+It does not require:
+
+- System-wide Java installation
+- System-wide PDFtk installation
+- External certificate authority configuration

-There are many ways to contribute, including writing code, filing issues on GitHub, helping people Overflow, helping to triage, reproduce, or fix bugs that people have filed, adding to our documentation.
-To get more details go to our [contributing guide](CONTRIBUTING.md).
+All cryptographic operations are self-contained within Nextcloud.


I believe we should avoid mentioning internal implementation details such as specific binaries or tools (e.g. Java, PDFtk). These are internal design choices and may change over time, and they are transparent to administrators installing LibreSign.

Instead, it might be better to focus this section on architectural principles: self-contained cryptography, internal CA management, privacy, and data sovereignty.

Would you mind adjusting the section to something more conceptual, for example:

Suggested change

LibreSign installs all required binaries in standalone mode inside the Nextcloud data directory.

This design improves portability and avoids dependency conflicts with the host system.

It does not require:

- System-wide Java installation

- System-wide PDFtk installation

- External certificate authority configuration

There are many ways to contribute, including writing code, filing issues on GitHub, helping people Overflow, helping to triage, reproduce, or fix bugs that people have filed, adding to our documentation.

To get more details go to our [contributing guide](CONTRIBUTING.md).

All cryptographic operations are self-contained within Nextcloud.

LibreSign runs entirely inside your Nextcloud environment.

All cryptographic operations are self-contained and executed server-side. No external services are required and no document data leaves your infrastructure.

LibreSign manages its own internal Certificate Authority (CA), ensuring full control over keys, signatures and alignment with data protection regulations.

This keeps the message strong while avoiding low-level implementation details.

What do you think?

README.md

vitormattos · 2026-02-21T16:30:31Z

README.md

+We welcome contributions!
+
+- Bug reports and feature requests: Issues tab
+- Code contributions: Pull Requests
+- Translations: Transifex https://app.transifex.com/nextcloud/nextcloud/libresign
+- Documentation improvements: https://github.com/LibreSign/documentation
+- To get more details go to our [contributing guide](CONTRIBUTING.md).
+
+[![Request a feature](https://img.shields.io/badge/Request%20a%20feature-7057ff?style=for-the-badge)](https://github.com/LibreSign/libresign/issues/new?template=feature_request.yml)
+[![Report a BUG](https://img.shields.io/badge/Report%20a%20bug-8e0000?style=for-the-badge)](https://github.com/LibreSign/libresign/issues/new?template=bug_report.yml)


I was thinking we could simplify it a bit to avoid redundancy and keep the README cleaner. Since the badges for “Request a feature” and “Report a bug” duplicate what is already described in the list, a more concise version might work better and keep the document focused and professional.

I also changed the term “Submitting Pull Requests” to “Contributing code improvements” to make it clearer for non-technical contributors.

Maybe something like this:

Suggested change

We welcome contributions!

- Bug reports and feature requests: Issues tab

- Code contributions: Pull Requests

- Translations: Transifex https://app.transifex.com/nextcloud/nextcloud/libresign

- Documentation improvements: https://github.com/LibreSign/documentation

- To get more details go to our [contributing guide](CONTRIBUTING.md).

[![Request a feature](https://img.shields.io/badge/Request%20a%20feature-7057ff?style=for-the-badge)](https://github.com/LibreSign/libresign/issues/new?template=feature_request.yml)

[![Report a BUG](https://img.shields.io/badge/Report%20a%20bug-8e0000?style=for-the-badge)](https://github.com/LibreSign/libresign/issues/new?template=bug_report.yml)

LibreSign is an open source project and welcomes contributions.

You can contribute by:

- Opening issues for bugs and feature requests

- Contributing code improvements

- Improving translations on [Transifex](https://app.transifex.com/nextcloud/nextcloud/libresign)

- Contributing to the [documentation repository](https://github.com/LibreSign/documentation)

- Supporting the project via [GitHub Sponsors](https://github.com/sponsors/LibreSign)

See our [Contributing Guide](CONTRIBUTING.md) for details.

This keeps it clear, avoids duplication, and still highlights all contribution paths, including funding as a legitimate way to support the project.

What do you think?

vitormattos · 2026-02-21T16:33:32Z

README.md

+## License
+
+LibreSign (this repository) is licensed under the **GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**.
+- 📂 All licenses: [LICENSES/](LICENSES/)
+- 📘 Also in Documentation repository: https://github.com/LibreSign/documentation/blob/main/LICENSE
+
+---
+


Suggested change

## License

LibreSign (this repository) is licensed under the **GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**.

- 📂 All licenses: [LICENSES/](LICENSES/)

- 📘 Also in Documentation repository: https://github.com/LibreSign/documentation/blob/main/LICENSE

---

Since GitHub already clearly displays the project license in the repository header and we have the LICENSE and LICENSES/ files in place, I’m not sure we need to duplicate this information in the README.

At the right sidebar:

And at the top of README:

Keeping the README focused on functional and conceptual information about the project might make it cleaner and more intentional.

Would you be okay with removing this section?

vitormattos · 2026-02-21T16:36:28Z

README.md

+## Screenshots
+
+<p align="center">
+  <img src="img/LibreSign.png" alt="LibreSign interface screenshot" width="900"/>
+</p>
+
+---



Need to update the screenshot:

Replace the screenshot at README.md by a screenshot of newest interface #5104

vitormattos · 2026-02-21T16:36:44Z

README.md

  <img src="https://contrib.rocks/image?repo=LibreSign/libresign" />
 </a>
+
+## Star History


Suggested change

## Star History

## Star history

vitormattos · 2026-02-21T16:42:28Z

README.md

+LibreSign uses certificate-based digital signatures and follows best practices for secure document validation. 
+
+For responsible disclosure and security policy, please see [SECURITY.md](SECURITY.md).


I feel the current version is a bit too generic and doesn’t reflect some of LibreSign’s actual security capabilities (like PKI and CRL management, TSA or DocMDP support). At the same time, we probably want to keep this section concise so the README doesn’t become too long.

Maybe we could slightly adjust it to be more specific while still keeping it short, something like:

Suggested change

LibreSign uses certificate-based digital signatures and follows best practices for secure document validation.

For responsible disclosure and security policy, please see [SECURITY.md](SECURITY.md).

LibreSign uses certificate-based digital signatures built on a private PKI managed within your Nextcloud environment.

It supports certificate revocation (CRL), trusted time-stamping (TSA), and document certification levels (DocMDP), ensuring integrity, authenticity and long-term validation of signed documents.

All cryptographic operations are performed server-side and remain under your infrastructure control.

For responsible disclosure and security policy, please see [SECURITY.md](SECURITY.md).

This keeps it concise but better reflects the actual security model of the project.

What do you think?

vitormattos · 2026-02-21T16:43:11Z

README.md

 ## API Documentation

-[API Documentation](https://libresign.github.io/)
+Developer manual: https://docs.libresign.coop/developer_manual/index.html


index.html is optional

Suggested change

Developer manual: https://docs.libresign.coop/developer_manual/index.html

Developer manual: https://docs.libresign.coop/developer_manual/

yharroch · 2026-02-22T18:37:35Z

Thanks for your feedback. I’m happy to help and iterate further.
Please don’t hesitate to be direct — I’m new to GitHub, and I don’t mind if some of my suggestions don’t fit.
I tried to include as much information as possible, even if some of it ends up being moved to another section or discarded.

Co-authored-by: Vitor Mattos <vitor@php.rio> Signed-off-by: yharroch <82467465+yharroch@users.noreply.github.com>

vitormattos · 2026-02-23T18:09:27Z

@yharroch, you can ask about any doubts in the comments regarding what I discussed that you didn’t understand.

github-project-automation bot added this to Roadmap Feb 21, 2026

github-project-automation bot moved this to 0. Needs triage in Roadmap Feb 21, 2026

vitormattos requested changes Feb 21, 2026

View reviewed changes

github-project-automation bot moved this from 0. Needs triage to 1. to do in Roadmap Feb 21, 2026

Update README.md

e403417

Co-authored-by: Vitor Mattos <vitor@php.rio> Signed-off-by: yharroch <82467465+yharroch@users.noreply.github.com>

		LibreSign uses certificate-based digital signatures and follows best practices for secure document validation.

		For responsible disclosure and security policy, please see [SECURITY.md](SECURITY.md).

	Developer manual: https://docs.libresign.coop/developer_manual/index.html
	Developer manual: https://docs.libresign.coop/developer_manual/

Uh oh!

Comments

Conversation

yharroch commented Feb 21, 2026

Uh oh!

vitormattos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yharroch commented Feb 22, 2026

Uh oh!

vitormattos commented Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants