SVI/netbird
1
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2026-06-11 01:41:55 -04:00
Code Issues 3.0k Packages Projects Releases 10 Wiki Activity

Incomplete & insufficient **Advanced Setup** documentation for NetBird (self-hosting) #2385

New Issue
Open
opened 2025-11-20 07:09:01 -05:00 by saavagebueno · 1 comment
saavagebueno commented 2025-11-20 07:09:01 -05:00
Owner
Copy Link

Originally created by @onelrian on GitHub (Oct 17, 2025).

I spent one week deploying NetBird’s self-hosted control plane using Caddy as a reverse proxy and Keycloak as the identity provider.

Problem Statement

The Advanced Setup documentation lacks crucial implementation details and omits many integration nuances making custom deployments (e.g. Caddy + Keycloak) difficult, inflexible, and error prone.

Key Pain Points

  • Architecture & networking ambiguity
    It’s unclear how the NetBird components (management, signal, relay / coturn, dashboard, Keycloak) should interact. Required ports, proxying rules, and internal service routing are not well explained.

  • OIDC / Keycloak integration gaps
    The documentation fails to fully specify Keycloak configuration (realm setup, redirect URIs, trusted headers, environment variables, scopes, etc.). Small misconfigurations lead to invisible failures.

  • Reverse proxy / TLS / HTTPS pitfalls
    Using Caddy (or any reverse proxy) introduces complexities: SSL termination, correct forwarding of X-Forwarded-* headers, routing internal vs external endpoints, WebSocket and gRPC proxying. These are barely covered, and many flows break (redirects, metadata discovery, dashboard callbacks).

  • Lack of troubleshooting & example logs
    When errors happen e.g. gRPC authentication errors, broken pipes, “public key” fetch failures the docs offer no error samples, root cause analysis, or suggested fixes, making debugging laborious.

Impact

Because the documentation lacks the depth needed for custom setups, deploying a self-hosted NetBird with more advanced components takes excessive time, is fragile, and often fails in non-obvious ways. This undermines flexibility and confidence in reliability.

Originally created by @onelrian on GitHub (Oct 17, 2025). I spent **one week** deploying NetBird’s self-hosted control plane using **Caddy** as a reverse proxy and **Keycloak** as the identity provider. ### **Problem Statement** The *Advanced Setup* documentation lacks crucial implementation details and omits many integration nuances making custom deployments (e.g. Caddy + Keycloak) **difficult, inflexible, and error prone**. ### **Key Pain Points** * **Architecture & networking ambiguity** It’s unclear how the NetBird components (management, signal, relay / coturn, dashboard, Keycloak) should interact. Required ports, proxying rules, and internal service routing are not well explained. * **OIDC / Keycloak integration gaps** The documentation fails to fully specify Keycloak configuration (realm setup, redirect URIs, trusted headers, environment variables, scopes, etc.). Small misconfigurations lead to invisible failures. * **Reverse proxy / TLS / HTTPS pitfalls** Using Caddy (or any reverse proxy) introduces complexities: SSL termination, correct forwarding of `X-Forwarded-*` headers, routing internal vs external endpoints, WebSocket and gRPC proxying. These are barely covered, and many flows break (redirects, metadata discovery, dashboard callbacks). * **Lack of troubleshooting & example logs** When errors happen e.g. gRPC authentication errors, broken pipes, “public key” fetch failures the docs offer no error samples, root cause analysis, or suggested fixes, making debugging laborious. ### **Impact** Because the documentation lacks the depth needed for custom setups, deploying a self-hosted NetBird with more advanced components takes excessive time, is fragile, and often fails in non-obvious ways. This undermines flexibility and confidence in reliability.
saavagebueno commented 2025-11-20 07:09:02 -05:00
Author
Owner
Copy Link

@mitchplze commented on GitHub (Oct 21, 2025):

Not sure if you saw this section of the docs, which covers what paths/ports need to be forwarded where.

Though in general I concur, there is a lot of improvements that can be made to docs, especially for self-hosting.

@mitchplze commented on GitHub (Oct 21, 2025): Not sure if you saw [this section](https://docs.netbird.io/selfhosted/selfhosted-guide#configuration-for-your-reverse-proxy) of the docs, which covers what paths/ports need to be forwarded where. Though in general I concur, there is a lot of improvements that can be made to docs, especially for self-hosting.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
2021 Q4
2022 Q1
2022 Q1
accessibility
acl
agent
agent
Android
Android
api
authentik
automation
azure
battery-usage
bug
cache
client
client-ui
cloud
cloud-only
cloudflare
community
compatibility
config-idp
config-issue
connection
contribution
coturn
cross-vpn
dashboard
data-usage
distribution
dns
docker
documentation
duplicate
enhancement
enhancement
event-stream
feature-request
freebsd
getting-started
go
good first issue
gui
help wanted
home-assistant
idp
inconsistency
integration
integrations
ios
ipv6
jwt
k8s
keycloak
linux
login
macos
management-service
missing-docs
mobile
moved-internal
needs-review
netbird-ui
networking
new-platform
nginx
notification
okta
openwrt
packaging
peer-management
peer-management
peer-management
performance
postgres
posture-checks
psk
pull-request
Mirrored from GitHub Pull Request
 question
refactor
relay
release
rfc
routes
security
security-related
self-hosting
server
signal
sleep-issue
ssh
ssl
status
store
synology
system-compatibility-issue
test-suite
third-party-integration
triage
triage-needed
troubleshooting
UX
waiting-feedback
windows
wontfix
zitadel
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
saavagebueno
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: SVI/netbird#2385
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?