Configuration

Overview

NetBird Selfservice uses environment variables for configuration. All settings are stored in the .env file at the root of your application. This page provides a comprehensive reference for all configuration options.

Never commit your .env file to version control. It contains sensitive credentials and API tokens.

Environment Variables Reference

Application Settings

Core Laravel application configuration:

Variable	Required	Default	Description
`APP_NAME`	Yes	`"VPN Selfservice"`	Application name displayed in UI and emails
`APP_ENV`	Yes	`local`	Environment: `local`, `staging`, or `production`
`APP_KEY`	Yes	Auto-generated	Encryption key (generated by `php artisan key:generate`)
`APP_DEBUG`	Yes	`true`	Enable debug mode. Set to `false` in production
`APP_URL`	Yes	`http://localhost`	Full URL where application is accessible
`APP_LOCALE`	No	`en`	Default language
`APP_FALLBACK_LOCALE`	No	`en`	Fallback language if translation missing
`APP_FAKER_LOCALE`	No	`en_US`	Locale for fake data generation

APP_NAME="VPN Selfservice"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

Always set APP_DEBUG=false in production to prevent sensitive information leakage through error messages.

Database Configuration

Database connection settings:

Variable	Required	Default	Description
`DB_CONNECTION`	Yes	`sqlite`	Database driver: `mysql`, `mariadb`, `sqlite`, or `pgsql`
`DB_HOST`	No*	`127.0.0.1`	Database server hostname (not needed for SQLite)
`DB_PORT`	No*	`3306`	Database server port (not needed for SQLite)
`DB_DATABASE`	Yes	`laravel`	Database name or path to SQLite file
`DB_USERNAME`	No*	`root`	Database username (not needed for SQLite)
`DB_PASSWORD`	No*	-	Database password (not needed for SQLite)

Variables marked with * are only required when using MySQL, MariaDB, or PostgreSQL.

DB_CONNECTION=sqlite
# No additional configuration needed
# Database file: database/database.sqlite

Google OAuth Configuration

While the default is Google OAuth, NetBird Selfservice supports any OAuth provider compatible with Laravel Socialite.

Required for user authentication:

Variable	Required	Description
`GOOGLE_CLIENT_ID`	Yes	OAuth 2.0 Client ID from Google Cloud Console
`GOOGLE_CLIENT_SECRET`	Yes	OAuth 2.0 Client Secret from Google Cloud Console
`GOOGLE_REDIRECT_URI`	Yes	OAuth callback URL (must match Google Cloud Console configuration)

GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your_client_secret_here
GOOGLE_REDIRECT_URI=https://your-domain.test/auth/google/callback

Google OAuth Setup

Access Google Cloud Console

Navigate to Google Cloud Console and sign in with your Google account.

Create or Select Project

Create a new project or select an existing one for your NetBird Selfservice deployment.

Enable OAuth Consent Screen

Navigate to APIs & Services > OAuth consent screen
Choose Internal (for Google Workspace) or External
Fill in application name, user support email, and developer contact
Add scopes: email, profile, openid

Create OAuth Credentials

Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application as application type
Add authorized redirect URI: https://your-domain.test/auth/google/callback
Click Create

Copy Credentials

Copy the generated Client ID and Client Secret to your .env file:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.test/auth/google/callback

The GOOGLE_REDIRECT_URI must exactly match the authorized redirect URI in Google Cloud Console, including the protocol (http/https) and port number.

NetBird API Configuration

Settings for NetBird API integration:

Variable	Required	Description
`NETBIRD_API_URL`	Yes	NetBird API endpoint URL
`NETBIRD_API_TOKEN`	Yes	API access token with network management permissions
`NETBIRD_NETWORK_ID`	Yes	ID of the NetBird network to manage resources in
`NETBIRD_NETWORK_NAME`	No	Display name of your NetBird network
`NETBIRD_ADMIN_EMAIL`	Yes	Email address of the admin user (receives admin privileges)
`NETBIRD_EGRESS_IP`	Yes	Egress IP address displayed to users for reference
`NETBIRD_RESOURCE_GROUP_NAME`	Yes	Name of the NetBird group where resources are assigned
`NETBIRD_USER_GROUP_NAME`	Yes	Name of the NetBird group containing users who can access resources

# NetBird API Connection
NETBIRD_API_URL=https://api.netbird.io
NETBIRD_API_TOKEN=nb_1234567890abcdefghijklmnopqrstuvwxyz
NETBIRD_NETWORK_ID=abc123def456
NETBIRD_NETWORK_NAME="Production VPN Network"

# NetBird Settings
NETBIRD_ADMIN_EMAIL=admin@example.com
NETBIRD_EGRESS_IP=99.99.99.99
NETBIRD_RESOURCE_GROUP_NAME="Resources for Employees"
NETBIRD_USER_GROUP_NAME="Employees"

NetBird API Setup

Navigate to NetBird Dashboard and sign in to your account.

Create API Token

Go to Settings > Access Tokens
Click Create Access Token
Give it a descriptive name (e.g., “Selfservice API”)
Select appropriate permissions (network management required)
Copy the generated token immediately (it won’t be shown again)

Find Network ID

Navigate to your network in the NetBird dashboard
The Network ID is visible in the URL or network settings
Copy it to NETBIRD_NETWORK_ID in your .env file

Create Required Groups

Create two groups in NetBird:User Group (e.g., “Employees”):

Contains users who will access VPN resources
Add your team members to this group

Resource Group (e.g., “Resources for Employees”):

Resources created through Selfservice are assigned here
Should have access policies allowing the User Group to connect

Configure Access Policies

Set up NetBird access policies to allow the User Group to access the Resource Group.

Keep your NETBIRD_API_TOKEN secure. It has full access to manage your NetBird network. Never commit it to version control or expose it in logs.

Security Configuration

Security and access control settings:

Variable	Required	Description
`NETBIRD_ALLOWED_DOMAIN`	Strongly Recommended	Email domain allowed to sign in (e.g., `example.com`)
`BCRYPT_ROUNDS`	No	Number of bcrypt hashing rounds (default: 12)

# Security Settings
NETBIRD_ALLOWED_DOMAIN=example.com
BCRYPT_ROUNDS=12

Always set NETBIRD_ALLOWED_DOMAIN to restrict access to your organization’s email domain. Without this, anyone with a valid Google account could potentially sign in.

Session & Cache Configuration

Session and caching behavior:

Variable	Default	Description
`SESSION_DRIVER`	`database`	Session storage driver
`SESSION_LIFETIME`	`120`	Session lifetime in minutes
`CACHE_STORE`	`database`	Cache storage driver
`QUEUE_CONNECTION`	`database`	Queue driver for background jobs

SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
CACHE_STORE=database
QUEUE_CONNECTION=database

Logging Configuration

Application logging settings:

Variable	Default	Description
`LOG_CHANNEL`	`stack`	Logging channel
`LOG_STACK`	`single`	Stack configuration
`LOG_LEVEL`	`debug`	Minimum log level

LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

In production, set LOG_LEVEL=error to reduce log verbosity and improve performance.

Mail Configuration

Email delivery settings (optional, for notifications):

MAIL_MAILER=log
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

By default, emails are logged rather than sent. Configure a real mail driver (SMTP, Mailgun, etc.) if you need email notifications.

Configuration Best Practices

Production Checklist

Before deploying to production:

Security Hardening

Enhance security with these measures:

Domain Restriction: Always set NETBIRD_ALLOWED_DOMAIN
API Token Security: Rotate NETBIRD_API_TOKEN regularly
Admin Access: Limit NETBIRD_ADMIN_EMAIL to trusted users only
File Permissions: Ensure .env is readable only by the application user
HTTPS: Always use HTTPS in production
Database Security: Use strong database passwords and restrict network access
Session Security: Set SESSION_ENCRYPT=true if handling sensitive data

Performance Optimization

For better performance:

Use Redis for CACHE_STORE and SESSION_DRIVER in production
Configure QUEUE_CONNECTION=redis with a dedicated queue worker
Enable OPcache in PHP configuration
Use composer install --optimize-autoloader --no-dev in production
Run php artisan config:cache and php artisan route:cache

Development vs Production

Key differences between environments:

Setting	Development	Production
`APP_ENV`	`local`	`production`
`APP_DEBUG`	`true`	`false`
`DB_CONNECTION`	`sqlite`	`mysql`
`LOG_LEVEL`	`debug`	`error`
`CACHE_STORE`	`database`	`redis`
`SESSION_DRIVER`	`database`	`redis`

Verifying Configuration

After configuring your environment variables, verify the setup:

# Check configuration is loaded correctly
php artisan config:show

# Test database connection
php artisan migrate:status

# Clear configuration cache (if you made changes)
php artisan config:clear

Troubleshooting

OAuth Redirect Mismatch

If you see “redirect_uri_mismatch” error:

Verify GOOGLE_REDIRECT_URI exactly matches Google Cloud Console
Check protocol (http vs https)
Ensure port numbers match if using non-standard ports
Clear browser cache and cookies

NetBird API Errors

If NetBird API calls fail:

Verify NETBIRD_API_TOKEN is valid and not expired
Check token has appropriate permissions
Confirm NETBIRD_NETWORK_ID is correct
Test API connectivity: curl -H "Authorization: Bearer $NETBIRD_API_TOKEN" $NETBIRD_API_URL/api/networks

Domain Restriction Not Working

If users from other domains can sign in:

Verify NETBIRD_ALLOWED_DOMAIN is set in .env
Clear configuration cache: php artisan config:clear
Check for typos in the domain name
Ensure no trailing spaces in the value

Next Steps

With configuration complete, you’re ready to:

First Login

User Guide

Learn how to create and manage VPN resources

Get Started

Core Features

Guides

Security

Overview

Environment Variables Reference

Application Settings

Database Configuration

Google OAuth Configuration

Google OAuth Setup

NetBird API Configuration

NetBird API Setup

Security Configuration

Session & Cache Configuration

Logging Configuration

Mail Configuration

Configuration Best Practices

Verifying Configuration

Troubleshooting

Next Steps

First Login

User Guide

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Security

Documentation Index

​Overview

​Environment Variables Reference

​Application Settings

​Database Configuration

​Google OAuth Configuration

​Google OAuth Setup

​NetBird API Configuration

​NetBird API Setup

​Security Configuration

​Session & Cache Configuration

​Logging Configuration

​Mail Configuration

​Configuration Best Practices

​Verifying Configuration

​Troubleshooting

​Next Steps

First Login

User Guide

Build docs developers (and LLMs) love

Overview

Environment Variables Reference

Application Settings

Database Configuration

Google OAuth Configuration

Google OAuth Setup

NetBird API Configuration

NetBird API Setup

Security Configuration

Session & Cache Configuration

Logging Configuration

Mail Configuration

Configuration Best Practices

Verifying Configuration

Troubleshooting

Next Steps