Skip to content

docs: add warnings about IP address and self-signed certificate limitations#7693

Open
tjaadvd wants to merge 1 commit intonextcloud:mainfrom
tjaadvd:improve-docs-warning
Open

docs: add warnings about IP address and self-signed certificate limitations#7693
tjaadvd wants to merge 1 commit intonextcloud:mainfrom
tjaadvd:improve-docs-warning

Conversation

@tjaadvd
Copy link
Copy Markdown

@tjaadvd tjaadvd commented Mar 5, 2026

Many users attempt to run Nextcloud AIO on a local network using an IP address or a self-signed certificate, only to discover this is unsupported after going through the setup process. I personally tried this too, even though i (quickly) read the README and Local-instance pages.

This PR makes the limitation more visible upfront so others won't make the same mistake.

Changes

  • local-instance.md: Added a [!WARNING] callout at the top of the page clearly stating that AIO requires a real domain name and a valid TLS certificate, and that IP addresses and self-signed certificates are not supported.
  • readme.md: Added a [!WARNING] callout in the "How to use this?" section directing local-only users to local-instance.md before proceeding with setup.

Motivation

The existing documentation mentions these limitations, but only in passing within a longer paragraph. Users who skim the docs (or jump straight to the setup steps) miss this entirely. The new callouts ensure the constraint is visible before any setup steps are taken.

@szaimen szaimen added 3. to review Waiting for reviews documentation Improvements or additions to documentation labels Mar 6, 2026
@szaimen szaimen added this to the next milestone Mar 6, 2026
@szaimen szaimen self-requested a review March 9, 2026 21:23
Copy link
Copy Markdown
Member

@pabzm pabzm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the contribution!

I like the idea but would like to ask you for two text changes. Thanks!

Comment thread local-instance.md
# Local instance

> [!WARNING]
> AIO requires a **real domain name** and a **valid TLS certificate** to function correctly.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. "real domain name" is not very precise, our requirement is "publicly resolveable domain" (or hostname). That's not as catchy, if you can think of another wording, please let me know. But please replace "real".
  2. Technically a self-signed certificate is also valid. You (probably) correctly mean a publicly verifiable certificate (issued by a well-known, public certificate authority), so please change the phrase accordingly.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi,

I'm having trouble coming up with the correct text. What do you think about this?

# Local instance

> [!WARNING]
> AIO requires a **publicly resolvable domain** and a **publicly verifiable certificate** (issued by a well-known, public certification authority).

Comment thread local-instance.md

> [!WARNING]
> AIO requires a **real domain name** and a **valid TLS certificate** to function correctly.
> Accessing Nextcloud via a plain IP address or a self-signed certificate is **not supported**.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a local CA is also unsupported.

Copy link
Copy Markdown
Author

@tjaadvd tjaadvd Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about this?

Accessing Nextcloud via a **plain IP address**, a **self-signed certificate**, or a **certificate from a local certificate authority (CA)** is **not supported**.

@szaimen szaimen added 2. developing Work in progress and removed 3. to review Waiting for reviews labels Mar 19, 2026
@szaimen szaimen modified the milestones: v12.9.0, next Mar 23, 2026
@szaimen szaimen modified the milestones: v12.9.1, next, v12.9.2 Apr 2, 2026
@szaimen szaimen modified the milestones: v13.0.0, next Apr 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

2. developing Work in progress documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants