This repository was archived by the owner on Sep 1, 2026. It is now read-only.
docs: add self-hosted whitelist onboarding and reverse proxy authentication guide - #1643
Open
tonicofonico wants to merge 2 commits into
Open
Conversation
Reviewer's GuideUpdates the self-hosted deployment guide to document whitelist-based user onboarding and reverse proxy authentication behavior for the admin frontend, including configuration details and security trade-offs. Flow diagram for self-hosted whitelist-based user onboardingflowchart TD
A[Admin configure whitelist in Signup Settings] --> B[Domain whitelist and/or email whitelist]
B --> C[User signs up at /signup with matching email]
C --> D[System provisions personal workspace]
D --> E[User becomes Owner of their personal workspace]
E --> F[Per-workspace 1-seat limit enforced]
Flow diagram for reverse proxy authentication and token storage behaviorflowchart TD
A[Admin deploys admin_frontend behind reverse proxy] --> B[Check for cookie desynchronization issues]
B -->|No issues| C[NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=false]
C --> D[Tokens stored in HTTP-only cookies]
D --> E[Managed by Next.js server actions]
B -->|Issues present| F[NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true]
F --> G[Tokens stored in localStorage and document.cookie]
G --> H[Apply HTTPS and security hardening on reverse proxy]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The statement that domain-whitelist users can sign up "without seat limit restrictions" could be misinterpreted; consider clarifying whether this bypasses the 1 member/owner cap entirely or only changes the onboarding flow.
- Since
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=truemoves auth token handling tolocalStorageand cookies, it may be helpful to briefly call out any security implications or recommended hardening steps (e.g., HTTP-only cookies, secure flags) for reverse proxy deployments. - To make the reverse proxy guidance more actionable, consider mentioning any required Next.js or proxy configuration (e.g., headers or cookie forwarding) that interacts with
NEXT_PUBLIC_DISABLE_SERVER_ACTIONSrather than only the environment flag.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The statement that domain-whitelist users can sign up "without seat limit restrictions" could be misinterpreted; consider clarifying whether this bypasses the 1 member/owner cap entirely or only changes the onboarding flow.
- Since `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true` moves auth token handling to `localStorage` and cookies, it may be helpful to briefly call out any security implications or recommended hardening steps (e.g., HTTP-only cookies, secure flags) for reverse proxy deployments.
- To make the reverse proxy guidance more actionable, consider mentioning any required Next.js or proxy configuration (e.g., headers or cookie forwarding) that interacts with `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS` rather than only the environment flag.
## Individual Comments
### Comment 1
<location path="doc/GUIDE.md" line_range="38-39" />
<code_context>
- `/minio`: User interface for Minio object storage.
- `/`, `/app`: AppFlowy Web.
+### Self-Hosted User Onboarding & Whitelist
+On Community Self-Hosted edition, workspace member invitations are capped at 1 member/owner per workspace. User onboarding is managed via the **Signup Settings / Whitelist** in the Admin Console (`/console/users-management?tab=settings`):
+- **Domain Whitelist**: Add authorized email domains (e.g. `yourcompany.com`). Users registering with matching emails can self-signup at `/signup` without seat limit restrictions.
+- **Email Whitelist**: Add specific external email addresses for individual collaborator access.
</code_context>
<issue_to_address>
**suggestion (typo):** Clarify grammar in the opening sentence and the "1 member/owner" phrase.
Consider adding an article: e.g., "In the Community Self-Hosted edition" or "On the Community Self-Hosted edition." Also, to avoid ambiguity and keep prose consistent, rephrase "1 member/owner per workspace" as "one member or owner per workspace" (or similar).
```suggestion
### Self-Hosted User Onboarding & Whitelist
In the Community Self-Hosted edition, workspace member invitations are capped at one member or owner per workspace. User onboarding is managed via the **Signup Settings / Whitelist** in the Admin Console (`/console/users-management?tab=settings`):
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
This was referenced Aug 1, 2026
Open
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- Consider clarifying how domain/email whitelist-based self-signup interacts with the 1-seat workspace member cap (e.g., whether signups bypass the cap entirely or are limited in some way) to avoid ambiguity for admins.
- The reverse proxy section could benefit from briefly explaining under what conditions
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=trueshould not be used (e.g., environments where client-side token handling is undesirable) to help admins make an informed choice. - In the security recommendation note, you may want to explicitly mention CSRF considerations (such as the impact of
SameSite=Laxon cross-site requests) to make the guidance more actionable for proxy configuration.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Consider clarifying how domain/email whitelist-based self-signup interacts with the 1-seat workspace member cap (e.g., whether signups bypass the cap entirely or are limited in some way) to avoid ambiguity for admins.
- The reverse proxy section could benefit from briefly explaining under what conditions `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true` should not be used (e.g., environments where client-side token handling is undesirable) to help admins make an informed choice.
- In the security recommendation note, you may want to explicitly mention CSRF considerations (such as the impact of `SameSite=Lax` on cross-site requests) to make the guidance more actionable for proxy configuration.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:20
daa744b to
d3bc95f
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The statement that domain-whitelist self-signups "bypass the 1-seat workspace member cap entirely, allowing unlimited workspace owners" could be clarified to explain precisely which roles and workspaces are affected to avoid misinterpretation of seat limits.
- In the security recommendation, consider tightening wording around cookies vs headers (e.g.,
SecureandSameSiteare cookie attributes sent viaSet-Cookie) and briefly outlining how these should be configured at the reverse proxy level in a typical Nginx/Traefik setup. - It may help to explicitly call out the trade-offs and recommended scenarios for setting
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true, including when it should remain disabled, so self-hosted admins can more confidently decide whether to rely on client-side token handling.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The statement that domain-whitelist self-signups "bypass the 1-seat workspace member cap entirely, allowing unlimited workspace owners" could be clarified to explain precisely which roles and workspaces are affected to avoid misinterpretation of seat limits.
- In the security recommendation, consider tightening wording around cookies vs headers (e.g., `Secure` and `SameSite` are cookie attributes sent via `Set-Cookie`) and briefly outlining how these should be configured at the reverse proxy level in a typical Nginx/Traefik setup.
- It may help to explicitly call out the trade-offs and recommended scenarios for setting `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true`, including when it should remain disabled, so self-hosted admins can more confidently decide whether to rely on client-side token handling.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:23
d3bc95f to
2479da9
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The sentence "workspace member invitations ... are capped at 1 member/owner per workspace" is a bit ambiguous; consider rephrasing to clearly distinguish between owners vs members and what exactly is limited (e.g., "a workspace can only have one member besides the owner").
- In the reverse proxy section, you mention tokens in both
localStorageanddocument.cookie; it would help readers if you briefly clarify which data is stored where and why, and explicitly call out the security implications of usinglocalStoragefor auth tokens.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The sentence "workspace member invitations ... are capped at 1 member/owner per workspace" is a bit ambiguous; consider rephrasing to clearly distinguish between owners vs members and what exactly is limited (e.g., "a workspace can only have one member besides the owner").
- In the reverse proxy section, you mention tokens in both `localStorage` and `document.cookie`; it would help readers if you briefly clarify which data is stored where and why, and explicitly call out the security implications of using `localStorage` for auth tokens.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:34
2479da9 to
581109b
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The “Self-Hosted User Onboarding & Whitelist” section could more explicitly walk through a typical onboarding flow (e.g., user signs up via domain whitelist → gets a personal workspace → cannot be invited into another workspace) to reduce potential confusion around how seat limits interact with whitelisted signups.
- In the “Reverse Proxy & Reverse Proxy Authentication” section, it would help to clarify more concretely how token storage differs between
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=trueandfalse(what is stored in cookies vslocalStoragein each mode), since this directly informs admins’ security posture and tradeoff decisions.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The “Self-Hosted User Onboarding & Whitelist” section could more explicitly walk through a typical onboarding flow (e.g., user signs up via domain whitelist → gets a personal workspace → cannot be invited into another workspace) to reduce potential confusion around how seat limits interact with whitelisted signups.
- In the “Reverse Proxy & Reverse Proxy Authentication” section, it would help to clarify more concretely how token storage differs between `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true` and `false` (what is stored in cookies vs `localStorage` in each mode), since this directly informs admins’ security posture and tradeoff decisions.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:47
581109b to
4e80a72
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In the "Self-Hosted User Onboarding & Whitelist" section, consider explicitly clarifying that the 1-seat limit applies per workspace and that creating multiple personal workspaces is allowed, as the current phrasing about “a workspace can have at most 1 member/owner total” might be interpreted as a global limit.
- The security recommendation note for
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=trueis quite dense; consider breaking it into a short bulleted checklist (HTTPS, proxy headers, cookie flags) to make the guidance easier for operators to follow step by step.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the "Self-Hosted User Onboarding & Whitelist" section, consider explicitly clarifying that the 1-seat limit applies per workspace and that creating multiple personal workspaces is allowed, as the current phrasing about “a workspace can have at most 1 member/owner total” might be interpreted as a global limit.
- The security recommendation note for `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true` is quite dense; consider breaking it into a short bulleted checklist (HTTPS, proxy headers, cookie flags) to make the guidance easier for operators to follow step by step.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:50
4e80a72 to
90137df
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In the whitelist onboarding section, consider briefly clarifying how this interacts with existing signup controls (e.g., disabling open signup or combining domain vs email-based whitelists) so admins understand the full flow and constraints.
- In the reverse proxy section, it would be helpful to explicitly call out that
NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=trueshould be used only when proxy-related cookie issues occur, and that it increases exposure vialocalStorageso admins can better weigh the trade-off. - The security hardening checklist references
SCHEME=https; consider adding a short note or link to whereSCHEMEis configured in your deployment setup so readers can immediately map the guidance to their configuration.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the whitelist onboarding section, consider briefly clarifying how this interacts with existing signup controls (e.g., disabling open signup or combining domain vs email-based whitelists) so admins understand the full flow and constraints.
- In the reverse proxy section, it would be helpful to explicitly call out that `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true` should be used only when proxy-related cookie issues occur, and that it increases exposure via `localStorage` so admins can better weigh the trade-off.
- The security hardening checklist references `SCHEME=https`; consider adding a short note or link to where `SCHEME` is configured in your deployment setup so readers can immediately map the guidance to their configuration.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:53
90137df to
4f59797
Compare
Author
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In the "Self-Hosted User Onboarding & Whitelist" section, consider clarifying the relationship between the per-workspace 1-seat limit and users creating multiple personal workspaces (e.g., add a short example) to avoid ambiguity about how many workspaces a single user can own.
- The guidance on
NEXT_PUBLIC_DISABLE_SERVER_ACTIONSwould benefit from explicitly stating common symptoms or error cases that indicate "proxy-related cookie desynchronization issues" so administrators know when this flag is appropriate versus when it should be left at its default. - In the security hardening checklist, you might want to mention the importance of setting a strict Content Security Policy (CSP) when tokens are stored in
localStorageto reinforce the XSS mitigation advice already given.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the "Self-Hosted User Onboarding & Whitelist" section, consider clarifying the relationship between the per-workspace 1-seat limit and users creating multiple personal workspaces (e.g., add a short example) to avoid ambiguity about how many workspaces a single user can own.
- The guidance on `NEXT_PUBLIC_DISABLE_SERVER_ACTIONS` would benefit from explicitly stating common symptoms or error cases that indicate "proxy-related cookie desynchronization issues" so administrators know when this flag is appropriate versus when it should be left at its default.
- In the security hardening checklist, you might want to mention the importance of setting a strict Content Security Policy (CSP) when tokens are stored in `localStorage` to reinforce the XSS mitigation advice already given.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
tonicofonico
force-pushed
the
docs/self-hosted-onboarding-and-proxy-guide
branch
from
August 1, 2026 16:57
4f59797 to
9121af0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Description of Changes
This PR updates
doc/GUIDE.mdto document self-hosted user onboarding via Whitelist and reverse proxy authentication settings foradmin_frontend.🔗 Related Pull Requests & Issues
NEXT_PUBLIC_DISABLE_SERVER_ACTIONSoption todocker-compose.ymlanddeploy.envfor reverse proxy authentication.🔍 Problem & Motivation
Self-hosted administrators frequently encounter confusion regarding:
admin_frontendwhen deployed behind reverse proxies (Traefik/Nginx).🛠️ Changes Included:
doc/GUIDE.md:NEXT_PUBLIC_DISABLE_SERVER_ACTIONS=true.🧪 Verification:
Summary by Sourcery
Document self-hosted user onboarding workflows and reverse proxy authentication guidance in the main deployment guide.
Documentation: