🇫🇷 Français | 🇬🇧 English
Install Souverain.ovh Commentaires 0.2.1
The examples use https://example.com and /_commentaires. Replace them with your public origin and path. The archive directly contains the _commentaires folder to copy. The module works with HTML pages, static websites, or a CMS: the steps below do not depend on any particular publishing tool.
To see the result before installing it, open the live example under “Génération LaSuite”.
1. Check your hosting environment
You need:
- a public domain served over HTTPS with a valid certificate;
- PHP 8.1 or newer, the cURL extension, and working PHP sessions;
- a session storage location and temporary directory writable by PHP;
- outbound HTTPS connections and DNS resolution required by the configured networks;
- Apache with
.htaccessenabled, includingmod_headersand the authorization rules used in the provided file; - a recent browser with JavaScript, cookies, and local storage available.
The module folder and the articles must share the same public origin. https://www.example.com and https://example.com are two different origins: choose the one used by your articles and keep it consistent everywhere.
With Nginx or another web server, have the protections in .htaccess translated into equivalent server rules by the person managing the hosting environment. This file is not applied automatically outside Apache. Never publish PHP source files as plain downloadable files.
Node.js is not required to install the module: the ATProto bundle is already included.
2. Copy the folder
Extract the archive, then copy the entire _commentaires folder to the public root of the domain, using FTP/SFTP or your usual deployment tool. Depending on the hosting provider, this root may be called www, public_html, or htdocs.
PUBLIC_ROOT/
├── index.html
├── my-article/
│ └── index.html
└── _commentaires/
├── .htaccess
├── config.php
├── test.html
├── commentaires.css
├── commentaires.js
├── atproto-oauth.js
├── oauth-client-metadata.php
├── mastodon/
└── atproto/
Enable the display of hidden files in your FTP client: .htaccess must be transferred. Place the folder on the public hosting environment that executes PHP. If your articles are generated as HTML, keep the module outside that conversion process and preserve its folder during deployment.
3. Edit config.php
For a first installation, the provided file is a generic example. Open it and fill in the following values while preserving its PHP syntax:
| Key | Value to enter |
|---|---|
site_url |
HTTPS origin of the articles, without a path: https://example.com. |
base_path |
Public path of the module, without a trailing slash: /_commentaires. |
app_name |
Application name displayed during OAuth authorization. |
session_name |
Session name specific to this installation; keep the provided value if it suits your setup. |
demo_article_url |
Full public URL of a test article: https://example.com/my-article/, or an empty string '' if you do not want to configure a demo article. |
max_posts_to_search |
Maximum number of original posts to scan; 1,000 by default. |
mastodon.instance |
HTTPS origin of the instance for the account that shares your articles, on port 443. |
mastodon.username |
Username of that account, without @ or the instance name. |
bluesky.handle |
Identifier of the account that shares your articles, for example alice.bsky.social. |
bluesky.api |
Origin of the public AppView; keep https://public.api.bsky.app unless you have a specific requirement. |
bluesky.page_size |
Search page size; 100 by default. |
The Mastodon instance in the configuration is the instance of the thread owner. A visitor may sign in with an account hosted on another public instance.
The current configuration expects parameters for both networks. If no post exists on one of them, its discussion will not be available; the module does not provide a configuration switch to disable an entire protocol.
Do not enter any account password, personal token, or OAuth secret in this file. The Mastodon application is registered during sign-in; ATProto metadata is generated by oauth-client-metadata.php.
You may change base_path, for example to /discussion or /tools/discussion. Use simple ASCII path segments, without spaces, %, standalone . or .., or double slashes. Rename or move the public folder accordingly and update the stylesheet and script URLs in your integration pages. The session name must start with a letter and may contain at most 64 characters using letters, digits, _, and -.
You do not need to rebuild atproto-oauth.js when changing the domain or path. Keep test.html in the module folder.
4. Prepare the test article and its posts
- Choose an article that is publicly accessible over HTTPS.
- Copy its exact canonical URL into
demo_article_url, on the same origin assite_url. - Share that same URL in an original public post from your configured Mastodon account.
- Share it as well from your configured Bluesky account.
- Reply to each post from the corresponding network so that there is content to display.
Keep the exact same path, including the trailing slash if your site uses one. Use the article URL without tracking parameters, a URL shortener, or a local preview address. Mastodon replies and boosts are not used as root posts for this search.
Article URLs must be distinguished by their path, such as /my-article/. Links such as /?p=42 are not supported for integration. Tracking parameters such as utm_*, fbclid, and gclid are ignored, but a query string used as the article identifier is rejected to avoid mixing several conversations.
You may leave demo_article_url empty if you test directly from an integrated article page. A regular visit to test.html will then indicate that no article is configured. This does not prevent the page from handling the ATProto OAuth return flow: it may reuse the temporarily stored article URL or invite the signed-in visitor to return to the article.
5. Check the service before integration
Open these addresses in a browser:
https://example.com/_commentaires/test.html: the demo should display its interface and search for the configured article.https://example.com/_commentaires/config-public.php: a JavaScript response should definewindow.FederatedCommentsConfigwith your domain and public accounts.https://example.com/_commentaires/oauth-client-metadata.php: a JSON response should contain aclient_idpointing to this file and a redirect tohttps://example.com/_commentaires/test.html.https://example.com/_commentaires/config.php: HTTP access must be denied; its content remains available to the server-side PHP scripts.
Do not create a personal oauth-client-metadata.json file. This distribution uses configurable PHP metadata and the provided bundle.
On the demo page, first check that replies can be read. Then separately test sign-in and publishing with a Mastodon test account, followed by ATProto. These tests publish real messages to the selected network: use a thread intended for testing. After publishing, also verify the message on the original network.
The package's local checks do not replace these tests on your own domain and hosting environment.
6. Integrate the module, then publish your articles
Follow INTEGRATION.en.md. Installing the module alone does not automatically add a comments block below the articles of an existing website. The integration/article.html example provides the complete DOM structure to place in your template.
Troubleshooting first issues
| Symptom | Useful check |
|---|---|
| HTTP 500 error | PHP/Apache logs, config.php syntax, PHP version, cURL, session/temporary-directory permissions, and whether the .htaccess directives are allowed. |
| PHP code is displayed or downloaded | Stop deployment and have PHP execution enabled for this folder by the hosting provider. |
| Discussion not found | Canonical URL and trailing slash, correct account, original public post, age of the post, and max_posts_to_search. |
| One network fails | Module error message, API availability, post visibility, rate limits, and outbound connections. |
| Sign-in is refused from a local preview | Test from the public HTTPS origin; same-origin protections are expected. |
| Incorrect OAuth return | Domain and path in config.php, test.html still online, cookies/storage available, bundle from this version, and accessible PHP metadata. |
| Incorrect styling after replacing the CSS | URL actually being loaded, browser/CDN cache, and stylesheet order on the website. |
If your site applies its own Content Security Policy, it must allow the module resources and the HTTPS connections required by the APIs and OAuth providers. The headers applied to the _commentaires folder do not replace those of the article pages; do not disable protections without first identifying the rule that is blocking the request.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 |
|