sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 15:36:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

split docs into different groups and start landing page

Browse Source
This commit is contained in:
Pascal Fischer
2023-05-05 11:22:34 +02:00
parent 5e05625d00
commit 2b65de30e4
20 changed files with 1266 additions and 713 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
src/components/Button.jsx
View File

@@ -17,16 +17,13 @@ function ArrowIcon(props) {
const variantStyles = {
primary:
'rounded-full bg-zinc-900 py-1 px-3 text-white hover:bg-zinc-700 dark:bg-orange-400/10 dark:text-orange-400 dark:ring-1 dark:ring-inset dark:ring-orange-400/20 dark:hover:bg-orange-400/10 dark:hover:text-orange-300 dark:hover:ring-orange-300',
// 'rounded-full bg-zinc-900 py-1 px-3 text-white hover:bg-zinc-700 dark:bg-emerald-400/10 dark:text-emerald-400 dark:ring-1 dark:ring-inset dark:ring-emerald-400/20 dark:hover:bg-emerald-400/10 dark:hover:text-emerald-300 dark:hover:ring-emerald-300',
secondary:
'rounded-full bg-zinc-100 py-1 px-3 text-zinc-900 hover:bg-zinc-200 dark:bg-zinc-800/40 dark:text-zinc-400 dark:ring-1 dark:ring-inset dark:ring-zinc-800 dark:hover:bg-zinc-800 dark:hover:text-zinc-300',
filled:
'rounded-full bg-zinc-900 py-1 px-3 text-white hover:bg-zinc-700 dark:bg-orange-500 dark:text-white dark:hover:bg-orange-400',
// 'rounded-full bg-zinc-900 py-1 px-3 text-white hover:bg-zinc-700 dark:bg-emerald-500 dark:text-white dark:hover:bg-emerald-400',
outline:
'rounded-full py-1 px-3 text-zinc-700 ring-1 ring-inset ring-zinc-900/10 hover:bg-zinc-900/2.5 hover:text-zinc-900 dark:text-zinc-400 dark:ring-white/10 dark:hover:bg-white/5 dark:hover:text-white',
text: 'text-orange-500 hover:text-orange-600 dark:text-orange-400 dark:hover:text-orange-500',
// text: 'text-emerald-500 hover:text-emerald-600 dark:text-emerald-400 dark:hover:text-emerald-500',
}
export function Button({

167
src/components/Clients.jsx Normal file
View File

@@ -0,0 +1,167 @@
import Link from 'next/link'
import { motion, useMotionTemplate, useMotionValue } from 'framer-motion'
import { GridPattern } from '@/components/GridPattern'
import { Heading } from '@/components/Heading'
import { ChatBubbleIcon } from '@/components/icons/ChatBubbleIcon'
import { EnvelopeIcon } from '@/components/icons/EnvelopeIcon'
import { UserIcon } from '@/components/icons/UserIcon'
import { UsersIcon } from '@/components/icons/UsersIcon'
const clients = [
{
href: '/docs/client-installation#linux',
name: 'Linux',
description:
'Learn how to install the NetBird client on Linux devices.',
icon: UserIcon,
pattern: {
y: 16,
squares: [
[0, 1],
[1, 3],
],
},
},
{
href: '/docs/client-installation#mac-os',
name: 'MacOS',
description:
'Learn how to install the NetBird client on MacOS devices.',
icon: ChatBubbleIcon,
pattern: {
y: -6,
squares: [
[-1, 2],
[1, 3],
],
},
},
{
href: '/docs/client-installation#windows',
name: 'Windows',
description:
'Learn how to install the NetBird client on Windows devices.',
icon: EnvelopeIcon,
pattern: {
y: 32,
squares: [
[0, 2],
[1, 4],
],
},
},
{
href: '/docs/client-installation#android',
name: 'Android',
description:
'Learn how to install the NetBird client on Android devices.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/docs/client-installation#ios',
name: 'iOS',
description:
'Learn how to install the NetBird client on OS devices.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
]
function ClientIcon({ icon: Icon }) {
return (
<div className="flex h-7 w-7 items-center justify-center rounded-full bg-zinc-900/5 ring-1 ring-zinc-900/25 backdrop-blur-[2px] transition duration-300 group-hover:bg-white/50 group-hover:ring-zinc-900/25 dark:bg-white/7.5 dark:ring-white/15 dark:group-hover:bg-orange-300/10 dark:group-hover:ring-orange-400">
<Icon className="h-5 w-5 fill-zinc-700/10 stroke-zinc-700 transition-colors duration-300 group-hover:stroke-zinc-900 dark:fill-white/10 dark:stroke-zinc-400 dark:group-hover:fill-orange-300/10 dark:group-hover:stroke-orange-400" />
</div>
)
}
function ClientPattern({ mouseX, mouseY, ...gridProps }) {
let maskImage = useMotionTemplate`radial-gradient(180px at ${mouseX}px ${mouseY}px, white, transparent)`
let style = { maskImage, WebkitMaskImage: maskImage }
return (
<div className="pointer-events-none">
<div className="absolute inset-0 rounded-2xl transition duration-300 [mask-image:linear-gradient(white,transparent)] group-hover:opacity-50">
<GridPattern
width={72}
height={56}
x="50%"
className="absolute inset-x-0 inset-y-[-30%] h-[160%] w-full skew-y-[-18deg] fill-black/[0.02] stroke-black/5 dark:fill-white/1 dark:stroke-white/2.5"
{...gridProps}
/>
</div>
<motion.div
className="absolute inset-0 rounded-2xl bg-gradient-to-r from-[#D7EDEA] to-[#F4FBDF] opacity-0 transition duration-300 group-hover:opacity-100 dark:from-[#202D2E] dark:to-[#303428]"
style={style}
/>
<motion.div
className="absolute inset-0 rounded-2xl opacity-0 mix-blend-overlay transition duration-300 group-hover:opacity-100"
style={style}
>
<GridPattern
width={72}
height={56}
x="50%"
className="absolute inset-x-0 inset-y-[-30%] h-[160%] w-full skew-y-[-18deg] fill-black/50 stroke-black/70 dark:fill-white/2.5 dark:stroke-white/10"
{...gridProps}
/>
</motion.div>
</div>
)
}
function Client({ client }) {
let mouseX = useMotionValue(0)
let mouseY = useMotionValue(0)
function onMouseMove({ currentTarget, clientX, clientY }) {
let { left, top } = currentTarget.getBoundingClientRect()
mouseX.set(clientX - left)
mouseY.set(clientY - top)
}
return (
<div
key={client.href}
onMouseMove={onMouseMove}
className="group relative flex rounded-2xl bg-zinc-50 transition-shadow hover:shadow-md hover:shadow-zinc-900/5 dark:bg-white/2.5 dark:hover:shadow-black/5"
>
<ClientPattern {...client.pattern} mouseX={mouseX} mouseY={mouseY} />
<div className="absolute inset-0 rounded-2xl ring-1 ring-inset ring-zinc-900/7.5 group-hover:ring-zinc-900/10 dark:ring-white/10 dark:group-hover:ring-white/20" />
<div className="relative rounded-2xl px-4 pb-4 pt-16">
<h3 className="mt-4 text-sm font-semibold leading-7 text-zinc-900 dark:text-white">
<Link href={client.href}>
<span className="absolute inset-0 rounded-2xl" />
{client.name}
</Link>
</h3>
<p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
{client.description}
</p>
</div>
</div>
)
}
export function Clients() {
return (
<div className="my-16 xl:max-w-none">
<Heading level={2} id="clients">
Clients
</Heading>
<div className="not-prose mt-4 grid grid-cols-1 gap-8 border-t border-zinc-900/5 pt-10 dark:border-white/5 sm:grid-cols-2 xl:grid-cols-4">
{clients.map((client) => (
<Client key={client.href} client={client} />
))}
</div>
</div>
)
}

2
src/components/Code.jsx
View File

@@ -64,7 +64,6 @@ function CopyButton({ code }) {
'group/button absolute right-4 top-3.5 overflow-hidden rounded-full py-1 pl-2 pr-3 text-2xs font-medium opacity-0 backdrop-blur transition focus:opacity-100 group-hover:opacity-100',
copied
? 'bg-orange-400/10 ring-1 ring-inset ring-orange-400/20'
// ? 'bg-emerald-400/10 ring-1 ring-inset ring-emerald-400/20'
: 'bg-white/5 hover:bg-white/7.5 dark:bg-white/2.5 dark:hover:bg-white/5'
)}
onClick={() => {
@@ -156,7 +155,6 @@ function CodeGroupHeader({ title, children, selectedIndex }) {
className={clsx(
'border-b py-3 transition focus:[&:not(:focus-visible)]:outline-none',
childIndex === selectedIndex
// ? 'border-emerald-500 text-emerald-400'
? 'border-orange-500 text-orange-400'
: 'border-transparent text-zinc-400 hover:text-zinc-300'
)}

2
src/components/Footer.jsx
View File

@@ -57,9 +57,7 @@ const FeedbackThanks = forwardRef(function FeedbackThanks(_props, ref) {
className="absolute inset-0 flex justify-center md:justify-start"
>
<div className="flex items-center gap-3 rounded-full bg-orange-50/50 py-1 pl-1.5 pr-3 text-sm text-orange-900 ring-1 ring-inset ring-orange-500/20 dark:bg-orange-500/5 dark:text-orange-200 dark:ring-orange-500/30">
{/*<div className="flex items-center gap-3 rounded-full bg-emerald-50/50 py-1 pl-1.5 pr-3 text-sm text-emerald-900 ring-1 ring-inset ring-emerald-500/20 dark:bg-emerald-500/5 dark:text-emerald-200 dark:ring-emerald-500/30">*/}
<CheckIcon className="h-5 w-5 flex-none fill-orange-500 stroke-white dark:fill-orange-200/20 dark:stroke-orange-200" />
{/*<CheckIcon className="h-5 w-5 flex-none fill-emerald-500 stroke-white dark:fill-emerald-200/20 dark:stroke-emerald-200" />*/}
Thanks for your feedback!
</div>
</div>

54
src/components/How-To-Guides.jsx Normal file
View File

@@ -0,0 +1,54 @@
import { Button } from '@/components/Button'
import { Heading } from '@/components/Heading'
const howToGuides = [
{
href: '/docs/getting-started',
name: 'Getting Started',
description: 'Learn how to start using NetBird.',
},
{
href: '/docs/managing-your-network',
name: 'Managing your Network',
description: 'Learn everything you need to know about managing your network.',
},
{
href: '/docs/examples',
name: 'Examples',
description:
'Read some examples of how to use NetBird.',
},
{
href: '/docs/cli',
name: 'CLI',
description:
'Learn how to use the CLI of the NetBird client.',
},
]
export function HowToGuides() {
return (
<div className="my-16 xl:max-w-none">
<Heading level={2} id="guides">
How-To Guides
</Heading>
<div className="not-prose mt-4 grid grid-cols-1 gap-8 border-t border-zinc-900/5 pt-10 dark:border-white/5 sm:grid-cols-2 xl:grid-cols-4">
{howToGuides.map((guide) => (
<div key={guide.href}>
<h3 className="text-sm font-semibold text-zinc-900 dark:text-white">
{guide.name}
</h3>
<p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
{guide.description}
</p>
<p className="mt-4">
<Button href={guide.href} variant="text" arrow="right">
Read more
</Button>
</p>
</div>
))}
</div>
</div>
)
}

191
src/components/Navigation.jsx
View File

@@ -97,7 +97,6 @@ function ActivePageMarker({ group, pathname }) {
<motion.div
layout
className="absolute left-2 h-6 w-px bg-orange-500"
// className="absolute left-2 h-6 w-px bg-emerald-500"
initial={{ opacity: 0 }}
animate={{ opacity: 1, transition: { delay: 0.2 } }}
exit={{ opacity: 0 }}
@@ -186,181 +185,33 @@ function NavigationGroup({ group, className }) {
export const docsNavigation = [
{
title: 'Guides',
title: 'About NetBird',
links: [
{ title: 'Introduction', href: '/docs/introduction' },
{ title: 'How Netbird Works', href: '/docs/how-netbird-works' },
{ title: 'How-to Guides', href: '/docs/how-to-guides' },
{ title: 'Getting Started', href: '/docs/getting-started' },
{ title: 'Integrations', href: '/docs/integrations' },
{ title: 'Examples', href: '/docs/examples' },
{ title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
{ title: 'Reference', href: '/docs/reference' },
{ title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
{ title: 'How Netbird Works', href: '/docs/how-netbird-works' },
{ title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
{ title: 'Other', href: '/docs/other' },
{ title: 'FAQ', href: '/docs/faq' },
],
},
// {
// title: 'Introduction',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'How Netbird Works',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'How-to Guides',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'Getting Started',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'Integrations',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'NetBird vs. Traditional VPN',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'Reference',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'Why Wireguard with NetBird?',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'Other',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
// {
// title: 'FAQ',
// links: [
// { title: 'Introduction', href: '/docs/introduction' },
// { title: 'How Netbird Works', href: '/docs/how-netbird-works' },
// { title: 'How-to Guides', href: '/docs/how-to-guides' },
// { title: 'Getting Started', href: '/docs/getting-started' },
// { title: 'Integrations', href: '/docs/integrations' },
// { title: 'Examples', href: '/docs/examples' },
// { title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
// { title: 'Reference', href: '/docs/reference' },
// { title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
// { title: 'Other', href: '/docs/other' },
// { title: 'FAQ', href: '/docs/faq' },
// ],
// },
{
title: 'How-to Guides',
links: [
{ title: 'Getting Started', href: '/docs/getting-started' },
{ title: 'Client Installation', href: '/docs/client-installation' },
{ title: 'Managing your Network', href: '/docs/managing-your-network' },
{ title: 'Examples', href: '/docs/examples' },
{ title: 'CLI', href: '/docs/cli' },
],
},
{
title: 'Self-Hosted',
links: [
{ title: 'Installation Guide', href: '/docs/selfhosted-guide' },
{ title: 'Identity Providers', href: '/docs/identity-providers' },
],
},
]
export const apiNavigation = [

81
src/components/Resources.jsx
View File

@@ -10,8 +10,8 @@ import { UsersIcon } from '@/components/icons/UsersIcon'
const resources = [
{
href: '/contacts',
name: 'Contacts',
href: '/accounts',
name: 'Accounts',
description:
'Learn about the contact model and how to create, retrieve, update, delete, and list contacts.',
icon: UserIcon,
@@ -24,8 +24,8 @@ const resources = [
},
},
{
href: '/conversations',
name: 'Conversations',
href: '/users',
name: 'Users',
description:
'Learn about the conversation model and how to create, retrieve, update, delete, and list conversations.',
icon: ChatBubbleIcon,
@@ -38,8 +38,8 @@ const resources = [
},
},
{
href: '/messages',
name: 'Messages',
href: '/peers',
name: 'Peers',
description:
'Learn about the message model and how to create, retrieve, update, delete, and list messages.',
icon: EnvelopeIcon,
@@ -51,6 +51,17 @@ const resources = [
],
},
},
{
href: '/setup-keys',
name: 'Setup Keys',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/groups',
name: 'Groups',
@@ -62,14 +73,67 @@ const resources = [
squares: [[0, 1]],
},
},
{
href: '/rules',
name: 'rules',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/policies',
name: 'Policies',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/routes',
name: 'Routes',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/dns',
name: 'DNS',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
{
href: '/events',
name: 'Events',
description:
'Learn about the group model and how to create, retrieve, update, delete, and list groups.',
icon: UsersIcon,
pattern: {
y: 22,
squares: [[0, 1]],
},
},
]
function ResourceIcon({ icon: Icon }) {
return (
<div className="flex h-7 w-7 items-center justify-center rounded-full bg-zinc-900/5 ring-1 ring-zinc-900/25 backdrop-blur-[2px] transition duration-300 group-hover:bg-white/50 group-hover:ring-zinc-900/25 dark:bg-white/7.5 dark:ring-white/15 dark:group-hover:bg-orange-300/10 dark:group-hover:ring-orange-400">
{/*<div className="flex h-7 w-7 items-center justify-center rounded-full bg-zinc-900/5 ring-1 ring-zinc-900/25 backdrop-blur-[2px] transition duration-300 group-hover:bg-white/50 group-hover:ring-zinc-900/25 dark:bg-white/7.5 dark:ring-white/15 dark:group-hover:bg-emerald-300/10 dark:group-hover:ring-emerald-400">*/}
<Icon className="h-5 w-5 fill-zinc-700/10 stroke-zinc-700 transition-colors duration-300 group-hover:stroke-zinc-900 dark:fill-white/10 dark:stroke-zinc-400 dark:group-hover:fill-orange-300/10 dark:group-hover:stroke-orange-400" />
{/*<Icon className="h-5 w-5 fill-zinc-700/10 stroke-zinc-700 transition-colors duration-300 group-hover:stroke-zinc-900 dark:fill-white/10 dark:stroke-zinc-400 dark:group-hover:fill-emerald-300/10 dark:group-hover:stroke-emerald-400" />*/}
</div>
)
}
@@ -128,7 +192,6 @@ function Resource({ resource }) {
<ResourcePattern {...resource.pattern} mouseX={mouseX} mouseY={mouseY} />
<div className="absolute inset-0 rounded-2xl ring-1 ring-inset ring-zinc-900/7.5 group-hover:ring-zinc-900/10 dark:ring-white/10 dark:group-hover:ring-white/20" />
<div className="relative rounded-2xl px-4 pb-4 pt-16">
<ResourceIcon icon={resource.icon} />
<h3 className="mt-4 text-sm font-semibold leading-7 text-zinc-900 dark:text-white">
<Link href={resource.href}>
<span className="absolute inset-0 rounded-2xl" />

2
src/components/Search.jsx
View File

@@ -171,7 +171,6 @@ function SearchResult({ result, resultIndex, autocomplete, collection }) {
id={`${id}-title`}
aria-hidden="true"
className="text-sm font-medium text-zinc-900 group-aria-selected:text-orange-500 dark:text-white"
// className="text-sm font-medium text-zinc-900 group-aria-selected:text-emerald-500 dark:text-white"
dangerouslySetInnerHTML={{ __html: titleHtml }}
/>
{hierarchyHtml.length > 0 && (
@@ -266,7 +265,6 @@ const SearchInput = forwardRef(function SearchInput(
{autocompleteState.status === 'stalled' && (
<div className="absolute inset-y-0 right-3 flex items-center">
<LoadingIcon className="h-5 w-5 animate-spin stroke-zinc-200 text-zinc-900 dark:stroke-zinc-800 dark:text-orange-400" />
{/*<LoadingIcon className="h-5 w-5 animate-spin stroke-zinc-200 text-zinc-900 dark:stroke-zinc-800 dark:text-emerald-400" />*/}
</div>
)}
</div>

19
src/pages/docs/reference.mdx → src/pages/docs/cli.mdx
View File

@@ -1,10 +1,9 @@
import {HeroPattern} from "@/components/HeroPattern";
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
<HeroPattern />
export const title = 'Reference'
## NetBird commands
# NetBird CLI
The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect
your computer or server to the NetBirt network as a peer. But it can also be used as a client to control the daemon service.
@@ -19,9 +18,9 @@ netbird [command] [subcommand] [flags]
* `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop`
* `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up`
:::info Help
To see detailed command information, use the flag `--help` after each command
:::
<Note>
To see detailed command information, use the flag `--help` after each command
</Note>
### Global flags
`netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service.
@@ -77,9 +76,9 @@ if you want to run in the foreground, you can use "console" as the value for `--
```shell
sudo netbird up --log-file console
```
:::info
On Windows, you may need to run the command from an elevated terminal session.
:::
<Note>
On Windows, you may need to run the command from an elevated terminal session.
</Note>
In case you need to use a setup key, use the `--setup-key` flag :
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
@@ -264,7 +263,7 @@ Interface type: Kernel
Peers count: 2/3 Connected
```
<Note>
The peer with IP `100.119.85.4` wasn't returned because it was not connected
The peer with IP `100.119.85.4` wasn't returned because it was not connected
</Note>
#### ssh

278
src/pages/docs/client-installation.mdx Normal file
View File

@@ -0,0 +1,278 @@
import {HeroPattern} from "@/components/HeroPattern";
<HeroPattern />
export const title = 'Client Installation'
## Linux
**APT/Debian**
1. Add the repository:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
```
2. Update APT's cache
```bash
sudo apt-get update
```
3. Install the package
```bash
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
```
**RPM/Red hat**
1. Add the repository:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Install the package
```bash
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install netbird-ui
```
**Fedora**
1. Create the repository file:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Import the file
```bash
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
```
3. Install the package
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install netbird-ui
```
**NixOS 22.11+/unstable**
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration
```bash
sudo nixos-rebuild switch
```
## MacOS
**Homebrew install**
1. Download and install homebrew at https://brew.sh/
2. If wiretrustee was previously installed with homebrew, you will need to run:
```bash
# Stop and uninstall daemon service:
sudo wiretrustee service stop
sudo wiretrustee service uninstall
# unlik the app
brew unlink wiretrustee
```
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
3. Install the client
```bash
# for CLI only
brew install netbirdio/tap/netbird
# for GUI package
brew install --cask netbirdio/tap/netbird-ui
```
4. If you installed CLI only, you need to install and start the client daemon service:
```bash
sudo netbird service install
sudo netbird service start
```
## Windows
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
3. Proceed with the installation steps
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
> To uninstall the client and service, you can use Add/Remove programs
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
Recommended way is to add NetBird in firewall settings:
1. Go to "Control panel".
2. Select "Windows Defender Firewall".
3. Select "Advanced settings".
4. Select "Outbound Rules" -> "New rule".
5. In the new rule select "Program" and click "Next".
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
7. Select "Allow the connection" and click "Next".
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
10. Disconnect and connect to NetBird.
### Binary Install
**Installation from binary (CLI only)**
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```
<Note>
You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released verion.
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU archtecture
</Note>
3. Decompress
```bash
tar xcf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
```
After that you may need to add /usr/bin in your PATH environment variable:
````bash
export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
sudo netbird service install
sudo netbird service start
```
### Running NetBird with SSO Login
#### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
#### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Check connection status:
```bash
netbird status
```
### Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/overview/setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/overview/setup-keys)).
For all systems:
```bash
netbird up --setup-key <SETUP KEY>
```
For **Docker**, you can run with the following command:
```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
```
> TAG > 0.6.0 version
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
On **macOS** :
````bash
sudo ifconfig utun100
````
On **Linux**:
```bash
ip addr show wt0
```
On **Windows**:
```bash
netsh interface ip show config name="wt0"
```
### Running NetBird in Docker
Set the ```NB_SETUP_KEY``` environment variable and run the command.
<Note>
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
</Note>
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
```
See [Docker example](examples/netbird-docker.md) for details.
### Troubleshooting
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
which is ```https://api.wiretrustee.com:33073```.
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
to override it you can do the following:
```bash
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
```
To override it see the solution #1 above.

455
src/pages/docs/getting-started.mdx
View File

@@ -2,9 +2,7 @@ import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/comp
<HeroPattern />
export const title = 'Getting Started'
## Quickstart Guide
# Getting Started
Step-by-step video guide on YouTube:
@@ -74,454 +72,3 @@ ping 100.64.0.1
- Follow us [on Twitter](https://twitter.com/netbird)
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)
## Installation
### Linux
**APT/Debian**
1. Add the repository:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
```
2. Update APT's cache
```bash
sudo apt-get update
```
3. Install the package
```bash
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
```
**RPM/Red hat**
1. Add the repository:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Install the package
```bash
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install netbird-ui
```
**Fedora**
1. Create the repository file:
```bash
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Import the file
```bash
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
```
3. Install the package
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install netbird-ui
```
**NixOS 22.11+/unstable**
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration
```bash
sudo nixos-rebuild switch
```
### macOS
**Homebrew install**
1. Download and install homebrew at https://brew.sh/
2. If wiretrustee was previously installed with homebrew, you will need to run:
```bash
# Stop and uninstall daemon service:
sudo wiretrustee service stop
sudo wiretrustee service uninstall
# unlik the app
brew unlink wiretrustee
```
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
3. Install the client
```bash
# for CLI only
brew install netbirdio/tap/netbird
# for GUI package
brew install --cask netbirdio/tap/netbird-ui
```
4. If you installed CLI only, you need to install and start the client daemon service:
```bash
sudo netbird service install
sudo netbird service start
```
### Windows
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
3. Proceed with the installation steps
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
> To uninstall the client and service, you can use Add/Remove programs
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
Recommended way is to add NetBird in firewall settings:
1. Go to "Control panel".
2. Select "Windows Defender Firewall".
3. Select "Advanced settings".
4. Select "Outbound Rules" -> "New rule".
5. In the new rule select "Program" and click "Next".
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
7. Select "Allow the connection" and click "Next".
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
10. Disconnect and connect to NetBird.
### Binary Install
**Installation from binary (CLI only)**
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```
<Note>
You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released verion.
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU archtecture
</Note>
3. Decompress
```bash
tar xcf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
```
After that you may need to add /usr/bin in your PATH environment variable:
````bash
export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
sudo netbird service install
sudo netbird service start
```
### Running NetBird with SSO Login
#### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
#### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
</p>
Check connection status:
```bash
netbird status
```
### Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/overview/setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/overview/setup-keys)).
For all systems:
```bash
netbird up --setup-key <SETUP KEY>
```
For **Docker**, you can run with the following command:
```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
```
> TAG > 0.6.0 version
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
On **macOS** :
````bash
sudo ifconfig utun100
````
On **Linux**:
```bash
ip addr show wt0
```
On **Windows**:
```bash
netsh interface ip show config name="wt0"
```
### Running NetBird in Docker
Set the ```NB_SETUP_KEY``` environment variable and run the command.
<Note>
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
</Note>
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
```
See [Docker example](examples/netbird-docker.md) for details.
### Troubleshooting
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
which is ```https://api.wiretrustee.com:33073```.
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
to override it you can do the following:
```bash
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
```
To override it see the solution #1 above.
## Self-hosting Guide
NetBird is open-source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide).
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
<Note>
It might be a good idea to try NetBird before self-hosting.
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
</Note>
### Requirements
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
- Any Linux OS.
- Docker Compose installed (see [Install Docker Compose](https://docs.docker.com/compose/install/)).
- Domain name pointing to the public IP address of your server.
- Open TCP ports ```80, 443, 33073, 10000``` (Dashboard HTTP & HTTPS, Management gRCP & HTTP APIs, Signal gRPC API respectively) on your server.
- Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, `UDP 3478`, and range of ports, `UDP 49152-65535`, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
- Maybe a cup of coffee or tea :)
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
### Step 1: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
### Step 2: Prepare configuration files
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
```bash
## example file, you can copy this file to setup.env and update its values
##
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
NETBIRD_AUTH_AUDIENCE=""
# e.g. netbird-client
NETBIRD_AUTH_CLIENT_ID=""
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
<Note>
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
</Note>
<Note>
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
</Note>
### Step 3: Configure Identity Provider
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
Pick the one that suits your needs, follow the steps, and continue with this guide:
- Continue with [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service).
- Continue with [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
### Step 4: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
### Step 5: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
### Step 6: Run docker compose:
```bash
docker-compose up -d
```
### Step 7: Check docker logs (Optional)
```bash
docker-compose logs signal
docker-compose logs management
docker-compose logs coturn
docker-compose logs dashboard
```
### Advanced: Running netbird behind an existing reverse-proxy
If you want to run netbird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).
<Note>
Not all reverse-proxies are supported as netbird uses *gRPC* for various components.
</Note>
#### Configuration for netbird
In `setup.env`:
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port
Optional:
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server
<Note>
The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
</Note>
Now you can continue with [Step 3](#step-3-configure-identity-provider).
#### Configuration for your reverse-proxy
Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.
The following endpoints have to be setup:
Endpoint | Protocol | Target service and internal-port
------------------------------- | --------- | --------------------------------
/ | HTTP | dashboard:80
/signalexchange.SignalExchange/ | gRPC | signal:80
/api | HTTP | management:443
/management.ManagementService/ | gRPC | management:443
Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.
<Note>
You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
</Note>
### Get in touch
Feel free to ping us on [Slack](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) if you have any questions
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) :pray:
- Follow us [on Twitter](https://twitter.com/netbird)

465
src/pages/docs/identity-providers.mdx Normal file
View File

@@ -0,0 +1,465 @@
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
<HeroPattern />
# Identity Providers
There are a few Identity Provider options that you can choose to run a self-hosted version NetBird.
<Note>
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
</Note>
## Auth0
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/).
Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications.
It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP)
instance on your own.
<Note>
If you prefer to have full control over authentication and authorization of your NetBird network, there are good
self-hosted alternatives to the managed Auth0 service like [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
</Note>
### Step 1: Create Auth0 account
To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
There are five properties of the **`setup.env`** file that we will configure in this guide:
- `NETBIRD_AUTH_CLIENT_ID`
- `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`
- `NETBIRD_USE_AUTH0`
- `NETBIRD_AUTH_AUDIENCE`
- `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` (Optional)
### Step 2: Create and configure Auth0 application
This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).
- Follow the steps in the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0)
up until "Install the Auth0 React SDK".
- Use **`https://YOUR DOMAIN`** as: `Allowed Callback URLs`, `Allowed Logout URLs`, `Allowed Web Origins`, `Allowed Origins (CORS)`
<Note>
Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
</Note>
- Use **`Client ID`** to set ```NETBIRD_AUTH_CLIENT_ID``` property in the `setup.env` file.
- Use **`Domain`** to configure ```NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT``` property in the `setup.env` file like so:
```
https://<DOMAIN>/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
### Step 3: Create and configure Auth0 API
This Auth0 API will be used to access NetBird Management Service API.
- Follow the steps in the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api).
- Use API **`Identifier`** to set ```NETBIRD_AUTH_AUDIENCE``` property in the `setup.env` file.
- Set ```NETBIRD_USE_AUTH0``` to `true`in the `setup.env` file.
### Step 4: Enable Interactive SSO Login (Optional)
The [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login) allows for machine
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/overview/setup-keys)
and is optional.
You can enable it by following these steps:
- Log in to your Auth0 account https://manage.auth0.com/
- Go to `Applications` (left-hand menu)
- Click `Create Application` button (top right)
- Fill in the form with the following values:
- Name: `Interactive Login`
- Application type: `Native`
- Click `Create`
![](/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png)
- Click `Settings` tab
- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
![](/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png)
- Scroll down to the `Advanced Settings` section
- Enable **`Device Code`**
- Click `Save Changes`
![](/img/integrations/identity-providers/self-hosted/auth0-grant-types.png)
### Step 4: Continue with the self-hosting guide
You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
## Keycloak
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/).
Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.
<Note>
If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
[Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0).
</Note>
The following guide is an adapted version of the original
[Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide from the official website.
### Expected Result
After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines
to your network using the [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login)
over Keycloak.
![](/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif)
### Step 1: Check your Keycloak Instance
For this guide, you need a fully configured Keycloak instance running with SSL.
We assume that your Keycloak instance is available at **`https://YOUR-KEYCLOAK-HOST-AND_PORT`**.
Feel free to change the port if you have configured Keycloak with a different one.
Most of the OIDC software requires SSL for production use.
We encourage you to comply with this requirement to make the world more secure 😊.
### Step 2: Create a realm
To create a realm you need to:
- Open the Keycloak Admin Console
- Hover the mouse over the dropdown in the top-left corner where it says `Master`, then click on `Create Realm`
- Fill in the form with the following values:
- Realm name: `netbird`
- Click `Create`
-
![](/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png)
### Step 3: Create a user
In this step we will create a NetBird administrator user.
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Users` (left-hand menu)
- Click `Create new user`
- Fill in the form with the following values:
- Username: `netbird`
- Click `Create`
![](/img/integrations/identity-providers/self-hosted/keycloak-create-user.png)
The user will need an initial password set to be able to log in. To do this:
- Click `Credentials` tab
- Click `Set password` button
- Fill in the password form with a password
- Set the `Temporary` field to `Off` to prevent having to update password on first login
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/keycloak-set-password.png)
### Step 4: Create a NetBird client
In this step we will create NetBird application client and register with the Keycloak instance.
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Clients`
- Click `Create client` button
- Fill in the form with the following values and click Next:
- Client Type: `OpenID Connect`
- Client ID: `netbird-client`
- Your newly client `netbird-client` will be used later to set `NETBIRD_AUTH_CLIENT_ID` in the `setup.env`
![](/img/integrations/identity-providers/self-hosted/keycloak-create-client.png)
- Check the checkboxes as on the screenshot below and click Save
![](/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png)
### Step 5: Adjust NetBird client access settings
In this step we will configure NetBird application client access with the NetBird URLs.
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Clients`
- Choose `netbird-client` from the list
- Go to `Access Settings` section
- Fill in the fields with the following values:
- Root URL: `https://YOUR DOMAIN/` (this is the NetBird Dashboard root URL)
- Valid redirect URIs: `https://YOUR DOMAIN/*`
- Valid post logout redirect URIs: `https://YOUR DOMAIN/*`
- Web origins: `+`
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png)
### Step 6: Create a NetBird client scope
In this step, we will create and configure the NetBird client audience for Keycloak to add it to the generated JWT tokens.
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Client scopes` (left-hand menu)
- Click `Create client scope` button
- Fill in the form with the following values:
- Name: `api`
- Type: `Default`
- Protocol: `OpenID Connect`
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png)
- While in the newly created Client Scope, switch to the `Mappers` tab
- Click `Configure a new mapper`
- Choose the `Audience` mapping
![](/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png)
- Fill in the form with the following values:
- Name: `Audience for NetBird Management API`
- Included Client Audience: `netbird-client`
- Add to access token: `On`
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png)
### Step 7: Add client scope to NetBird client
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Clients`
- Choose `netbird-client` from the list
- Switch to `Client scopes` tab
- Click `Add client scope` button
- Choose `api`
- Click `Add` choosing `Default`
- The value `netbird-client` will be used as audience
![](/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png)
### Step 8: Create a NetBird-Backend client
In this step we will create NetBird backend client and register with the Keycloak instance.
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Clients`
- Click `Create client` button
- Fill in the form with the following values and click Next:
- Client Type: `OpenID Connect`
- Client ID: `netbird-backend`
- Your newly client `netbird-backend` will be used later to set `KeycloakClientCredentials` in the `management.json`
![](/img/integrations/identity-providers/self-hosted/keycloak-create-backend-client.png)
- Check the checkboxes as on the screenshot below and click Save
![](/img/integrations/identity-providers/self-hosted/keycloak-backend-client-auth.png)
The client will need secret to authenticate. To do this:
- Click `Credentials` tab
- Copy `client secret` will be used later to set `ClientSecret` in the `management.json`
![](/img/integrations/identity-providers/self-hosted/keycloak-backend-client-credentials.png)
### Step 9: Add manage-users role to netbird-backend
- Open the Keycloak Admin Console
- Make sure, that the selected realm is `Netbird`
- Click `Clients`
- Choose `netbird-backend` from the list
- Switch to `Service accounts roles` tab
- Click `Assign roles` button
- Select `Filter by clients` and search for `manage-users`
![](/img/integrations/identity-providers/self-hosted/keycloak-service-account-role.png)
- Check the role checkbox and click assign
![](/img/integrations/identity-providers/self-hosted/keycloak-add-role.png)
Your authority OIDC configuration will be available under:
```
https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
- NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configuration`.
- NETBIRD_AUTH_CLIENT_ID=`netbird-client`
- NETBIRD_AUTH_AUDIENCE=`netbird-client`
- NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`. Optional,
it enables the [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login) (Oauth 2.0 Device Authorization Flow)
- You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
- Set property `IdpManagerConfig` in the `management.json` file with:
<Note>
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
</Note>
```json
{
"ManagerType": "keycloak",
"KeycloakClientCredentials": {
"ClientID": "netbird-backend",
"ClientSecret": "<netbird-backend-client-secret>",
"GrantType": "client_credentials",
"TokenEndpoint": "https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/protocol/openid-connect/token",
"AdminEndpoint": "https://<YOUR-KEYCLOAK-HOST-AND-PORT>/admin/realms/netbird"
}
}
```
<Note>
Make sure that your Keycloak instance use HTTPS. Otherwise, the setup won't work.
</Note>
## Azure AD
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications.
It is a 3rd party managed service and can't be self-hosted.
<Note>
If you prefer to have full control over authentication and authorization of your NetBird network, there are good
self-hosted alternatives to the managed Auth0 service like [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
</Note>
Before you start creating and configuring an Azure AD application, ensure that you have the following:
- An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/.
- User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.
### 1. Create and configure Azure AD application
In this step, we will create and configure Netbird application in azure AD.
- Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
- Click `App Registrations` in the left menu then click on the `+ New registration` button to create a new application.
- Fill in the form with the following values and click Register
- Name: `Netbird`
- Account Types: `Accounts in this organizational directory only (Default Directory only - Single tenant)`
- Redirect URI: select `Single-page application (SPA)` and URI as `https://<yournetbirddomain.com>/silent-auth`
![](/img/integrations/identity-providers/self-hosted/azure-new-application.png)
### 2. Platform configurations
- Click `Authentication` on the left side menu
- Under the `Single-page application` Section, add another URI `https://<yournetbirddomain.com>/auth`
![](/img/integrations/identity-providers/self-hosted/azure-spa-uri-setup.png)
- Scroll down and setup other options as on the screenshot below and click Save
![](/img/integrations/identity-providers/self-hosted/azure-flows-setup.png)
### 3. Create a NetBird application scope
- Click `Expose an API` on the left menu
- Under `Application ID URI` click `Set` and then `Save`
- Click `+ Add a Scope`
- Fill in the form with the following values and click `Add scope`
- Scope name: `api`
![](/img/integrations/identity-providers/self-hosted/azure-add-scope.png)
- Under `Authorized client Applications`, click on `+ add a client application` and enter the following:
- Fill in the form with the following values and click `Add application`
- Client ID: same as your Application ID URI minus the `api://`
![](/img/integrations/identity-providers/self-hosted/azure-add-application-scope.png)
### 4. Add API permissions
- Add `Netbird` permissions
- Click `API permissions` on the left menu
- Click `Add a permission`
- Click `My APIs` tab, and select `Netbird`. Next check `api` permission checkbox and click `Add permissions`.
![](/img/integrations/identity-providers/self-hosted/azure-netbird-api-permisssions.png)
- Add `Delagated permissions` to Microsoft Graph
- Click `Add a permission`
- Click `Microsoft Graph` and then click `Delagated permissions` tab and check all permissions under the `OpenId permissions` section and click `Add permissions`
![](/img/integrations/identity-providers/self-hosted/azure-openid-permissions.png)
- Add `Application permissions` to Microsoft Graph
- Click `Add a permission`
- Click `Microsoft Graph` and then click `Application permissions` tab
- Search for `User.ReadWrite.All` and under `User` sections and check `User.ReadWrite.All` checkbox section
![](/img/integrations/identity-providers/self-hosted/azure-user-permissions.png)
- Search for `Application.ReadWrite.All` and under `Application` sections and check `Application.ReadWrite.All` checkbox section and click `Add permissions`
![](/img/integrations/identity-providers/self-hosted/azure-applications-permissions.png)
- Click `Grant admin conset for Default Directory` and click `Yes`
![](/img/integrations/identity-providers/self-hosted/azure-grant-admin-conset.png)
### 4. Update token version
- Click `Manifest` on left menu
- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2`
- Click `Save`
### 5. Generate client secret
- Click `Certificates & secrets` on left menu
- Click `New client secret`
- Fill in the form with the following values and click `Add`
- Description: `Netbird`
- Copy `Value` and save it as it can be viewed only once after creation.
![](/img/integrations/identity-providers/self-hosted/azure-client-secret.png)
Your authority OIDC configuration will be available under:
```
https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
```json
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<application_id>"
NETBIRD_AUTH_AUDIENCE="<application_id>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<application_id>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_AUTH_USER_ID_CLAIM="oid"
```
- You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
- Set property `IdpManagerConfig` in the `management.json` file with:
<Note>
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
</Note>
```json
{
"ManagerType": "azure",
"AzureClientCredentials": {
"ClientID": "<application_id>",
"ClientSecret": "<client_secret>",
"GrantType": "client_credentials",
"ObjectID": "<object_id>",
"TokenEndpoint": "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token",
"GraphAPIEndpoint": "https://graph.microsoft.com/v1.0"
}
}
```
- Modify the value of the `AUTH_SUPPORTED_SCOPES` environment variable for the dashboard service in the docker-compose.yml file to `openid profile email offline_access api://<application_id>/api`.

2
src/pages/docs/integrations.mdx
View File

@@ -1,2 +0,0 @@
export const description =
'This guide will.'

20
src/pages/docs/introduction.mdx
View File

@@ -1,20 +0,0 @@
export const description =
'On this page, we’ll introduce NetBird.'
# Introduction
NetBird is a simple and fast alternative to corporate VPNs built on top of [WireGuard®](https://www.wireguard.com/) making it easy to create secure private networks for your organization or home.
NetBird can connect machines running anywhere in just a few clicks.
It requires near zero configuration effort leaving behind the hassle of opening ports, complex firewall rules, vpn gateways, and so forth.
:::tip open-source
NetBird is an **open-source** project.
Check it out on GitHub: **[https://github.com/netbirdio/netbird](https://github.com/netbirdio/netbird)**
:::
There is no centralized VPN server with NetBird - your computers, devices, machines, and servers connect to each other directly over a fast encrypted tunnel.
It literally takes less than 5 minutes to deploy a secure peer-to-peer VPN with NetBird. Check our [Quick Start Guide](/getting-started/quickstart) to get started.

47
src/pages/docs/introductions.mdx
View File

@@ -1,39 +1,32 @@
import { Guides } from '@/components/Guides'
import { Resources } from '@/components/Resources'
import { HeroPattern } from '@/components/HeroPattern'
export const description =
'Learn everything there is to know about the Protocol API and integrate Protocol into your product.'
import { Clients } from '@/components/Clients'
import {Note} from "@/components/mdx"
import {HowToGuides} from "@/components/How-To-Guides";
export const sections = [
{ title: 'Guides', id: 'guides' },
{ title: 'Resources', id: 'resources' },
]
export const description =
'Learn everything there is to know about NetBird.'
<HeroPattern />
# NetBirds Super Awesome Docs Landing Page
# NetBird Documentation
Use the Protocol API to access contacts, conversations, group messages, and more and seamlessly integrate your product into the workflows of dozens of devoted Protocol users. {{ className: 'lead' }}
NetBird is a simple and fast alternative to corporate VPNs built on top of [WireGuard®](https://www.wireguard.com/) making it easy to create secure private networks for your organization or home.
It requires near zero configuration effort leaving behind the hassle of opening ports, complex firewall rules, vpn gateways, and so forth. {{ className: 'lead' }}
<Note>
NetBird is an **open-source** project.
</Note>
There is no centralized VPN server with NetBird - your computers, devices, machines, and servers connect to each other directly over a fast encrypted tunnel.
NetBird can connect machines running anywhere in just a few clicks.
It literally takes less than 5 minutes to deploy a secure peer-to-peer VPN with NetBird. {{ className: 'lead' }}
<div className="not-prose mb-16 mt-6 flex gap-3">
<Button href="/quickstart" arrow="right" children="Quickstart" />
<Button href="/sdks" variant="outline" children="Explore SDKs" />
<Button href="/docs/getting-started" arrow="right" children="Getting started" />
<Button href="https://github.com/netbirdio/netbird" variant="outline" children="Explore Github" />
</div>
## Getting started {{ anchor: false }}
<HowToGuides />
To get started, create a new application in your [developer settings](#), then read about how to make requests for the resources you need to access using our HTTP APIs or dedicated client SDKs. When your integration is ready to go live, publish it to our [integrations directory](#) to reach the Protocol community. {{ className: 'lead' }}
<div className="not-prose">
<Button
href="/sdks"
variant="text"
arrow="right"
children="Get your API key"
/>
</div>
<Guides />
<Resources />
<Clients />

0
src/pages/docs/how-to-guides.mdx → src/pages/docs/managing-your-network.mdx
View File

176
src/pages/docs/selfhosted-guide.mdx Normal file
View File

@@ -0,0 +1,176 @@
# Self-hosting Guide
NetBird is open-source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide).
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
<Note>
It might be a good idea to try NetBird before self-hosting.
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
</Note>
### Requirements
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
- Any Linux OS.
- Docker Compose installed (see [Install Docker Compose](https://docs.docker.com/compose/install/)).
- Domain name pointing to the public IP address of your server.
- Open TCP ports ```80, 443, 33073, 10000``` (Dashboard HTTP & HTTPS, Management gRCP & HTTP APIs, Signal gRPC API respectively) on your server.
- Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, `UDP 3478`, and range of ports, `UDP 49152-65535`, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
- Maybe a cup of coffee or tea :)
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
### Step 1: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
### Step 2: Prepare configuration files
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
```bash
## example file, you can copy this file to setup.env and update its values
##
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
NETBIRD_AUTH_AUDIENCE=""
# e.g. netbird-client
NETBIRD_AUTH_CLIENT_ID=""
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
<Note>
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
</Note>
<Note>
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
</Note>
### Step 3: Configure Identity Provider
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
Pick the one that suits your needs, follow the steps, and continue with this guide:
- Continue with [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service).
- Continue with [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
### Step 4: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
### Step 5: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
### Step 6: Run docker compose:
```bash
docker-compose up -d
```
### Step 7: Check docker logs (Optional)
```bash
docker-compose logs signal
docker-compose logs management
docker-compose logs coturn
docker-compose logs dashboard
```
### Advanced: Running netbird behind an existing reverse-proxy
If you want to run netbird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).
<Note>
Not all reverse-proxies are supported as netbird uses *gRPC* for various components.
</Note>
#### Configuration for netbird
In `setup.env`:
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port
Optional:
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server
<Note>
The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
</Note>
Now you can continue with [Step 3](#step-3-configure-identity-provider).
#### Configuration for your reverse-proxy
Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.
The following endpoints have to be setup:
Endpoint | Protocol | Target service and internal-port
------------------------------- | --------- | --------------------------------
/ | HTTP | dashboard:80
/signalexchange.SignalExchange/ | gRPC | signal:80
/api | HTTP | management:443
/management.ManagementService/ | gRPC | management:443
Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.
<Note>
You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
</Note>
### Get in touch
Feel free to ping us on [Slack](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) if you have any questions
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) :pray:
- Follow us [on Twitter](https://twitter.com/netbird)

6
src/pages/introductions.mdx
View File

@@ -3,7 +3,7 @@ import { Resources } from '@/components/Resources'
import { HeroPattern } from '@/components/HeroPattern'
export const description =
'Learn everything there is to know about the Protocol API and integrate Protocol into your product.'
'Learn everything there is to know about the NetBird Public API.'
export const sections = [
{ title: 'Guides', id: 'guides' },
@@ -12,9 +12,9 @@ export const sections = [
<HeroPattern />
# NetBirds Super Awesome API Landing Page
# NetBird API
Use the Protocol API to access contacts, conversations, group messages, and more and seamlessly integrate your product into the workflows of dozens of devoted Protocol users. {{ className: 'lead' }}
Use the NetBird Public API to manage users, peers, network rules and more from inside your application or scripts to automate the setup of your mesh network. {{ className: 'lead' }}
<div className="not-prose mb-16 mt-6 flex gap-3">
<Button href="/quickstart" arrow="right" children="Quickstart" />

3
src/styles/tailwind.css
View File

@@ -1,15 +1,12 @@
:root {
--shiki-color-text: theme('colors.white');
--shiki-token-constant: theme('colors.orange.300');
/*--shiki-token-constant: theme('colors.emerald.300');*/
--shiki-token-string: theme('colors.orange.300');
/*--shiki-token-string: theme('colors.emerald.300');*/
--shiki-token-comment: theme('colors.zinc.500');
--shiki-token-keyword: theme('colors.sky.300');
--shiki-token-parameter: theme('colors.pink.300');
--shiki-token-function: theme('colors.violet.300');
--shiki-token-string-expression: theme('colors.orange.300');
/*--shiki-token-string-expression: theme('colors.emerald.300');*/
--shiki-token-punctuation: theme('colors.zinc.200');
}