n0brain-inst

Professional web server component installer for Debian systems.

n0brain-inst compiles and installs production-ready web server components from source or packages, giving you full control over versions and compilation options.

Features

• nginx Ultimate Proxy - Custom-compiled with 15+ modules for maximum performance and security
• PHP 8.0-8.3 - With FPM and common extensions from sury.org packages
• ffmpeg - Full codec suite: x264, x265, VP9, AV1, hardware acceleration
• CUDA - NVIDIA toolkit for GPU-accelerated video encoding
• nginx-vod - Kaltura VOD module for professional video streaming
• Interactive TUI - Modern terminal UI with single-key navigation and live progress
• ISO Builder - Create custom Debian installation ISOs with intelligent user import
• CLI automation - Full command-line support for CI/CD pipelines

---

nginx Module Reference

The nginx build includes these production-ready modules:

Performance Modules

Module	Description
ngx_brotli	Modern compression, 20-30% better than gzip. Serves .br files automatically.
ngx_cache_purge	Purge cached content via URL. Supports wildcards for bulk invalidation.
headers-more	Add, set, or clear any HTTP header. Essential for security headers.
nginx-http-concat	Concatenate multiple files into one response. Reduces HTTP requests.

Security Modules

Module	Description
ModSecurity v3	Industry-standard WAF with OWASP Core Rule Set. Protects against SQLi, XSS, RCE.
lua-nginx-module	Embed Lua scripts for custom auth, rate limiting, and request processing.
http_realip	Get real client IP behind proxies/CDNs via X-Forwarded-For header.
http_secure_link	Generate secure, expiring URLs. Prevents hotlinking and unauthorized access.

Scripting & Integration

Module	Description
LuaJIT 2.1	High-performance Lua JIT compiler. Powers lua-nginx-module.
lua-resty-redis	Non-blocking Redis client for Lua. Session storage, caching, queues.
lua-resty-upstream-healthcheck	Active health checking for upstream servers. Auto-removes failed backends.
form-input-nginx	Parse POST form data directly in nginx. Useful for Lua processing.

Streaming Modules

Module	Description
nginx-vod-module	Professional video streaming: HLS, DASH, thumbnails, DRM. (Optional)
http_mp4	Pseudo-streaming for MP4/M4V. Enables seek without full download.
http_flv	FLV streaming support. Legacy but still used.

Protocol Support

Module	Description
http_v2	HTTP/2 multiplexing, header compression, server push.
stream	TCP/UDP load balancing and proxying. For databases, mail, etc.
http_ssl	TLS 1.2/1.3 with OpenSSL 3.4. OCSP stapling, session tickets.
stream_ssl_preread	Route TLS connections by SNI without terminating SSL.

Utility Modules

Module	Description
http_geoip	GeoIP-based routing and access control. Block countries, route by region.
http_stub_status	Basic nginx metrics. Connections, requests, status.
http_auth_request	Subrequest authentication. Integrate with external auth services.
iconv-nginx	Character encoding conversion. UTF-8, ISO-8859-1, etc.
nginx-http-user-agent	Parse User-Agent strings. Detect bots, browsers, devices.

Configuration Snippets

Pre-configured snippets are installed to /etc/nginx/snippets/:

/etc/nginx/snippets/
├── ssl-params.conf      # TLS best practices (TLS 1.2+, strong ciphers)
├── proxy-params.conf    # Reverse proxy headers and buffers
├── cache-purge.conf     # Cache purge location block
└── rate-limit.conf      # Rate limiting examples

Configuration Examples

ModSecurity WAF

ModSecurity is installed with OWASP Core Rule Set but disabled by default:

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;

    # Enable WAF for this site
    modsecurity on;

    # Test WAF (should be blocked):
    # curl "https://example.com/?id=1' OR '1'='1"
}

WAF logs: /var/log/nginx/modsec_audit.log

Switch from detection to blocking: Edit /etc/nginx/modsecurity/modsecurity.conf:

SecRuleEngine On    # Change from DetectionOnly

Brotli Compression

Brotli is enabled globally. Pre-compress static files for best performance:

# Pre-compress files (one-time)
brotli -Z style.css -o style.css.br
brotli -Z app.js -o app.js.br

# nginx automatically serves .br files when available

Per-location override:

location /api/ {
    brotli_comp_level 4;    # Lower level for dynamic content
}

Cache Purge

Clear cached content via HTTP request:

# Add to nginx.conf http block:
proxy_cache_path /var/cache/nginx/proxy levels=1:2
                 keys_zone=my_cache:10m max_size=1g inactive=60m;

# In server block:
location /purge/ {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$request_uri;
}

location /api/ {
    proxy_pass http://backend;
    proxy_cache my_cache;
    proxy_cache_valid 200 10m;
    add_header X-Cache-Status $upstream_cache_status;
}

Purge: curl http://localhost/purge/api/endpoint

Lua Scripting

Basic example:

location /lua-test {
    default_type text/plain;
    content_by_lua_block {
        ngx.say("Hello from LuaJIT!")
        ngx.say("URI: " .. ngx.var.uri)
        ngx.say("Client: " .. ngx.var.remote_addr)
    }
}

Custom authentication:

location /protected/ {
    access_by_lua_block {
        local token = ngx.req.get_headers()["Authorization"]
        if not token or token ~= "Bearer secret123" then
            ngx.status = 401
            ngx.say("Unauthorized")
            return ngx.exit(401)
        end
    }
    # ... rest of config
}

Rate limiting with Redis:

location /api/ {
    access_by_lua_block {
        local redis = require "resty.redis"
        local red = redis:new()
        red:connect("127.0.0.1", 6379)
        local key = "rate:" .. ngx.var.remote_addr
        local count = red:incr(key)
        if count == 1 then red:expire(key, 60) end
        if count > 100 then
            ngx.status = 429
            ngx.say("Rate limit exceeded")
            return ngx.exit(429)
        end
    }
}

Upstream Health Checks

Add to nginx.conf:

upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

lua_shared_dict healthcheck 1m;

init_worker_by_lua_block {
    local hc = require "resty.upstream.healthcheck"
    hc.spawn_checker {
        shm = "healthcheck",
        upstream = "backend",
        type = "http",
        http_req = "GET /health HTTP/1.0\r\nHost: backend\r\n\r\n",
        interval = 3000,
        timeout = 1000,
        fall = 3,
        rise = 2,
    }
}

Health status endpoint:

location /upstream-status {
    allow 127.0.0.1;
    deny all;
    content_by_lua_block {
        local hc = require "resty.upstream.healthcheck"
        ngx.print(hc.status_page())
    }
}

Secure Links (Expiring URLs)

location /downloads/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr mysecret";

    if ($secure_link = "") { return 403; }
    if ($secure_link = "0") { return 410; }  # Expired
}

Generate link in PHP:

$expires = time() + 3600;  // 1 hour
$uri = '/downloads/file.zip';
$secret = 'mysecret';
$ip = $_SERVER['REMOTE_ADDR'];
$md5 = base64_encode(md5($expires . $uri . $ip . $secret, true));
$md5 = strtr($md5, '+/', '-_');
$url = $uri . "?md5=" . rtrim($md5, '=') . "&expires=" . $expires;

---

ISO Builder - Intelligent Deployment

Create production-ready Debian installation ISOs with your exact user configuration cloned from the current system.

Key Features

Feature	Description
User Import	Scan and import users from /home with SSH keys and permissions
Multi-Column Toggle	Interactive UI to set Import/Sudo/Root per user
Root User Selection	Designate one user as root (receives root privileges)
SSH-Only Mode	Optional: Disable password auth completely, key-only access
Deploy Keys	Auto-generate GitHub deploy keys for private repo access
Multi-Target Deploy	Local path, SSH/SCP to remote, or NFS mount

User Import Menu

Select users to import:

       Import    Sudo    Root   User
       ────────  ──────  ──────  ────────────────────
❯      [✓]       [✓]     [○]     musa (2 keys)
        ✓         ○       ○      admin (1 key)
        ✓         ✓       ★      deploy (3 keys)

←/→ column, ↑/↓ row, Space toggle, Enter confirm, Ctrl+C exit

• Import - Include user in ISO (toggle multiple)
• Sudo - Grant sudo privileges (toggle multiple)
• Root - Make this user root (only one, marked with ★)

Security Modes

Mode	Password Auth	SSH Auth	Use Case
SSH-Only	Disabled	Key-only	Production servers, maximum security
Password + SSH	Enabled	Key + Password	Development, recovery access needed

Quick Start

# Launch ISO Builder
sudo ./install --iso-builder

# Or from interactive menu
sudo ./install
# → Select "ISO Builder"

Deployment Options

• Local Path - Copy to Proxmox ISO storage (/var/lib/vz/template/iso/)
• SSH/SCP - Upload to remote server with key or password auth
• NFS Mount - Auto-mount NFS share and copy ISO

---

Quick Start

# Clone the repository
git clone https://github.com/tommypowerz/n0brain-inst.git
cd n0brain-inst

# Interactive mode (launches TUI menu)
sudo ./install

# Or use CLI mode
sudo ./install --with-nginx --with-php 8.3

Requirements

Requirement	Version
Operating System	Debian 10 (Buster), 11 (Bullseye), 12 (Bookworm), or 13 (Trixie)
Python	3.9+ (3.13 compatible, auto-creates virtual environment)
Privileges	Root (sudo)
Disk Space	~2GB for full installation

Installation Methods

Interactive Mode (TUI)

Launch without arguments to use the Rich-based terminal interface:

sudo ./install

The menu offers preset configurations with arrow key navigation:

• Full Stack - nginx + PHP + site directories + SSL
• Nginx Only - nginx with all modules
• PHP Only - PHP-FPM from sury.org packages
• FFmpeg - Complete video encoding suite
• CUDA - GPU acceleration for video processing
• Video Streaming - nginx + VOD module + ffmpeg
• ISO Builder - Create custom Debian installation ISOs

CLI Mode

# Full web server with PHP and SSL
sudo ./install --with-nginx --with-php 8.3 --with-home --with-ssl

# Video streaming server
sudo ./install --with-nginx --with-vod --with-ffmpeg

# PHP development server
sudo ./install --with-nginx --with-php 8.3 --with-home

# CUDA for hardware encoding
sudo ./install --with-cuda

# ISO Builder for custom Debian ISOs
sudo ./install --iso-builder

# Quiet mode for automation
sudo ./install --with-nginx --with-php 8.3 -q --non-interactive

CLI Reference

Component Flags

Flag	Description
--with-nginx	Compile nginx from source with all modules
--with-php VERSION	Install PHP (8.0, 8.1, 8.2, 8.3)
--with-ffmpeg	Compile ffmpeg with codec suite
--with-cuda	Install NVIDIA CUDA toolkit
--with-vod	Include nginx VOD module (requires --with-nginx)
--iso-builder	Launch ISO Builder for custom Debian ISOs

Configuration Flags

Flag	Description
--with-home	Create site directory structure and nginx config
--with-ssl	Generate self-signed SSL certificate (requires --with-home)
-p, --prefix PATH	Build directory (default: ./build)
--clean	Clean build directory before starting

Output Control

Flag	Description
-q, --quiet	Suppress INFO messages, show only warnings/errors
-d, --debug	Enable debug logging with full command output
--show-log	Stream build output to console in real-time
-i, --interactive	Force interactive TUI mode
--non-interactive	Never prompt for input (CI/automation)

Management

Flag	Description
--list-installed	Show installed components
--uninstall COMPONENT	Uninstall component (nginx, php, ffmpeg, cuda, all)
--keep-configs	Keep configuration files during uninstall
--purge	Remove all components and configurations

Installation Locations

After installation, components are installed to these locations:

nginx

Type	Location
Binary	/usr/sbin/nginx
Configuration	/etc/nginx/
Sites	/etc/nginx/sites-available/, /etc/nginx/sites-enabled/
Snippets	/etc/nginx/snippets/
ModSecurity	/etc/nginx/modsecurity/
Logs	/var/log/nginx/
Cache	/var/cache/nginx/
Service	/etc/systemd/system/nginx.service

Libraries

Library	Location
LuaJIT	/usr/local/lib/libluajit-5.1.so*
Lua modules	/usr/local/share/lua/5.1/
ModSecurity	/usr/local/lib/libmodsecurity.so*

Build & Packages

Type	Location
Build directory	./build/ (configurable via --prefix)
Deployment packages	./packages/ (after "Create deployment package")
Installation manifests	/var/lib/n0brain-inst/installed/
Build logs	./logs/

Site Directories (with --with-home)

Type	Location
Document root	/var/www/<site-name>/public_html/
Site logs	/var/www/<site-name>/logs/
Site config	/etc/nginx/sites-available/<site-name>

Managing Installations

# List installed components
sudo ./install --list-installed

# Uninstall nginx, keep configs
sudo ./install --uninstall nginx --keep-configs

# Complete removal including configs
sudo ./install --uninstall nginx --purge

Configuration

Configuration files are in config/:

versions.yaml

nginx:
  version: "1.28.0"

openssl:
  version: "openssl-3.4.3"

lua:
  version: "v2.1-20251022"
  nginx_module: "v0.10.29"

modsecurity:
  version: "v3.0.13"

php:
  default_version: "8.3"
  supported_versions: ["8.0", "8.1", "8.2", "8.3"]

ffmpeg:
  x264: "stable"
  x265: "3.6"
  libvpx: "v1.15.2"
  aom: "v3.13.1"

defaults.yaml

paths:
  manifest_dir: "/var/lib/n0brain-inst/installed"

ssl:
  organization: "3lite Software GmbH"
  days_valid: 365

Project Structure

n0brain-inst/
├── install                  # Main entry point (auto-creates venv)
├── requirements.txt         # Python dependencies
├── config/                  # YAML configuration
│   ├── versions.yaml        # Software versions
│   ├── packages.yaml        # Debian package lists
│   ├── defaults.yaml        # Default settings
│   └── iso_builder.yaml     # ISO builder configuration
├── recipes/                 # Installation recipes
│   ├── nginx.yaml
│   ├── php.yaml
│   ├── ffmpeg.yaml
│   ├── cuda.yaml
│   └── homedir.yaml
├── templates/               # Jinja2 config templates
│   ├── nginx/
│   ├── systemd/
│   ├── preseed/             # Debian preseed configs
│   └── bootstrap/           # Bootstrap scripts
├── logs/                    # Build and execution logs
└── src/            # Python package
    ├── __init__.py
    ├── cli.py               # N0brainInstCLI - argument parsing
    ├── menu.py              # N0brainInstMenu - Rich TUI with live progress
    ├── iso_builder.py       # ISOBuilder - Debian ISO customization
    ├── config.py            # Configuration loader
    ├── logger.py            # N0brainInstLogger - colored output
    ├── system.py            # OS detection utilities
    ├── uninstall.py         # Uninstall system with manifests
    └── executor/            # Recipe execution engine
        ├── context.py       # Execution context
        ├── recipe.py        # Recipe parser
        └── steps.py         # Step handlers

Troubleshooting

nginx service is masked

If nginx was previously installed from Debian packages:

sudo systemctl unmask nginx.service
sudo systemctl restart nginx

FFmpeg libraries missing after reboot

Install development libraries:

sudo apt install -y libx264-dev libx265-dev libvpx-dev
sudo systemctl restart nginx

CUDA not working

Reboot is required after CUDA installation for drivers to load properly.

Build logs

Check the logs/ directory for detailed build output:

• src_YYYYMMDD_HHMMSS.log - Main execution log
• <recipe>_YYYYMMDD_HHMMSS.build.log - Per-recipe build output

Additional Setup

Let's Encrypt SSL

sudo apt install snapd
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx

# Add to crontab for auto-renewal
1 3 * * * /snap/bin/certbot renew --post-hook 'service nginx restart'

MySQL + phpMyAdmin

# Install MySQL
wget https://dev.mysql.com/get/mysql-apt-config_0.8.26-1_all.deb
sudo apt install ./mysql-apt-config_0.8.26-1_all.deb
sudo apt update && sudo apt install mysql-server

# Install phpMyAdmin
wget https://files.phpmyadmin.net/phpMyAdmin/5.2.1/phpMyAdmin-5.2.1-all-languages.zip
unzip phpMyAdmin-5.2.1-all-languages.zip
sudo mv phpMyAdmin-5.2.1-all-languages /usr/share/phpmyadmin

Documentation

Full documentation is available in the docs/ directory:

• Getting Started
• User Guide
• Developer Guide
• API Reference

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

---

Maintained by 3lite Software GmbH