Skip to main content

​
System Requirements

Before you begin, verify your system meets these requirements:
RequirementVersionNotes
PHP8.2+8.3.7+ recommended
ComposerLatestFor dependency management
Node.js16+For building frontend assets
npm8+Comes with Node.js
DatabaseMySQL 8.0+ / MariaDB 10.3+ / SQLite 3SQLite works for development
NetBird APIActive accountWith API token and network access
OAuth ProviderGoogle Cloud projectOr any Laravel Socialite supported provider
The composer.json specifies PHP ^8.2, but the platform configuration targets PHP 8.3.7 for optimal compatibility.

​
Installation Steps

1

Clone the Repository

Clone the NetBird Selfservice repository to your server:
git clone https://github.com/siteway/netbird-selfservice.git
cd netbird-selfservice
Or clone from your own fork if you’ve forked the repository.
2

Install PHP Dependencies

Use Composer to install all required PHP packages:
composer install
This installs:
  • Laravel Framework (^12.0)
  • Laravel Socialite (^5.24) for OAuth
  • Livewire Flux (^2.10) and Volt (^1.7.0)
  • Laravel Tinker (^2.10.1)
For production deployments, use composer install --no-dev --optimize-autoloader to skip development dependencies and optimize the autoloader.
3

Install Frontend Dependencies

Install Node.js packages for building frontend assets:
npm install
This installs Vite, Tailwind CSS 4.x, and other frontend build tools.
4

Configure Environment

Copy the example environment file and customize it:
cp .env.example .env
Edit the .env file with your configuration. See the Configuration page for detailed information about each variable.
Do not skip this step. The application will not work without proper environment configuration.
5

Generate Application Key

Generate a unique application encryption key:
php artisan key:generate
This command automatically updates the APP_KEY in your .env file. This key is used for encrypting session data and other sensitive information.
6

Set Up Database

Choose your database configuration:
# SQLite is pre-configured in .env.example
# Just ensure the database file exists
touch database/database.sqlite
SQLite is suitable for development and small deployments. For production with multiple concurrent users, use MySQL or MariaDB.
7

Run Database Migrations

Create all necessary database tables:
php artisan migrate
This creates tables for:
  • User authentication
  • Resource management
  • Activity logs
  • Sessions and cache
  • Queue jobs
Use php artisan migrate --force in production to bypass confirmation prompts.
8

Build Frontend Assets

Compile the frontend assets for production:
npm run build
For development with hot module replacement:
npm run dev
9

Start the Application

Launch the development server:
php artisan serve
Or use the comprehensive development environment:
composer run dev
This starts:
  • PHP development server (port 8000)
  • Queue worker for background jobs
  • Log viewer (Laravel Pail)
  • Vite development server with HMR
The application will be available at http://localhost:8000 by default.

​
Quick Setup Script

Alternatively, use the automated setup script defined in composer.json: 
composer run setup
This single command executes:
  1. composer install - Installs PHP dependencies
  2. Copies .env.example to .env (if .env doesn’t exist)
  3. php artisan key:generate - Generates application key
  4. php artisan migrate --force - Runs database migrations
  5. npm install - Installs Node.js dependencies
  6. npm run build - Builds frontend assets
The setup script will still require you to manually configure your .env file with OAuth credentials, NetBird API settings, and database connection (if using MySQL).

​
Verifying Installation

After installation, verify everything is working:
  1. Check Application Access: Visit http://localhost:8000 (or your configured APP_URL)
  2. Test OAuth Login: Click the login button and verify OAuth redirect works
  3. Check Database Connection: Ensure no database errors appear in logs
  4. Verify Asset Loading: Confirm CSS and JavaScript load correctly

​
Troubleshooting

If you encounter permission errors, ensure the web server has write access to:
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
Replace www-data with your web server user.
If Composer runs out of memory during installation:
COMPOSER_MEMORY_LIMIT=-1 composer install
Verify your database credentials in .env:
  • For SQLite: Ensure database/database.sqlite exists and is writable
  • For MySQL: Test connection with mysql -h DB_HOST -u DB_USERNAME -p
  • Check that the database exists: SHOW DATABASES;
If npm run build fails:
# Clear npm cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build
Verify your PHP version meets requirements:
php -v
If using multiple PHP versions, specify the correct one:
/usr/bin/php8.3 artisan serve
If port 8000 is already in use, specify a different port:
php artisan serve --port=8080

​
Next Steps

Now that NetBird Selfservice is installed, proceed to:

Configuration

Configure environment variables, OAuth providers, and NetBird API integration

OAuth Setup Guide

Set up Google OAuth credentials for user authentication

​
Production Deployment

For production deployments, consider:
  • Using a proper web server (Nginx or Apache) instead of php artisan serve
  • Configuring HTTPS with SSL certificates
  • Setting APP_ENV=production and APP_DEBUG=false
  • Using a queue worker service (systemd or supervisor)
  • Implementing proper backup strategies for your database
  • Setting up monitoring and logging solutions
  • Configuring a process manager for the queue worker
Consider using Laravel Forge, Ploi, or other deployment platforms for simplified production deployment and management.

Build docs developers (and LLMs) love

Get started for freeTalk to us