Getting Started

This guide will walk you through setting up Zoneweaver frontend for the first time, from initial installation to configuring your first Zoneweaver API connection.

Table of contents

  1. Prerequisites
  2. Quick Start
    1. 1. Installation
      1. Option A: From Package (Recommended)
      2. Option B: From Source
    2. 2. Initial Configuration
    3. 3. First Access
    4. 4. Add Zoneweaver API
  3. Configuration Options
    1. Security Settings
    2. Email Configuration
    3. SSL/TLS Setup
  4. User Management
    1. Creating Users
    2. Role Hierarchy
  5. Zoneweaver API Integration
    1. Backend Requirements
    2. Testing Connection
  6. Troubleshooting
    1. Common Issues
    2. Log Locations
  7. Next Steps

Prerequisites

Before starting, ensure you have:

  • Node.js 18+ - Required for running the frontend server
  • A Zoneweaver API Server - The backend API that manages zones
  • Network Access - Frontend needs to communicate with backend servers
  • SSL Certificates (Recommended) - For secure HTTPS connections

Quick Start

1. Installation

# Install Zoneweaver package
pkg install zoneweaver

# Enable service
svcadm enable zoneweaver

Option B: From Source

# Clone repository
git clone https://github.com/Makr91/zoneweaver.git
cd zoneweaver

# Install dependencies
npm install
cd web && npm install && cd ..

# Build frontend
npm run build

# Start service
npm start

2. Initial Configuration

Edit the configuration file at /etc/zoneweaver/config.yaml:

server:
  hostname: localhost
  port: 3443
  ssl:
    enabled: true
    generate_ssl: true
    key: /etc/zoneweaver/ssl/key.pem
    cert: /etc/zoneweaver/ssl/cert.pem

security:
  allow_new_organizations: true
  jwt_secret: "your-secure-random-secret-here"

database:
  path: /var/lib/zoneweaver/database/zoneweaver.db

3. First Access

  1. Open your browser and navigate to https://your-server:3443
  2. Create Organization: If allow_new_organizations is enabled, you’ll see registration
  3. Register Admin User: Create your first admin account
  4. Login: Use your new credentials to access the dashboard

4. Add Zoneweaver API

After logging in:

  1. Navigate to Settings → Servers
  2. Click Add Server
  3. Configure your Zoneweaver API:
    • Hostname: Your Zoneweaver API Server address
    • Port: Usually 5001 (HTTPS) or 5000 (HTTP)
    • Protocol: HTTPS recommended
    • API Key: Your Zoneweaver API API key

Configuration Options

Security Settings

security:
  jwt_secret: "change-this-to-a-secure-random-string"
  bcrypt_rounds: 10
  sessionTimeout: 24  # Hours
  allow_new_organizations: true  # Allow new org creation

Email Configuration

mail:
  smtp_connect:
    host: smtp.example.com
    port: 587
    secure: false
  smtp_auth:
    user: "your-email@example.com"
    password: "your-email-password"
  smtp_settings:
    from: "Zoneweaver <noreply@example.com>"

SSL/TLS Setup

For production, use proper SSL certificates:

server:
  ssl:
    enabled: true
    generate_ssl: false  # Use existing certificates
    key: /path/to/private.key
    cert: /path/to/certificate.crt

User Management

Creating Users

As an admin, you can:

  1. Invite Users: Send invitation codes via email
  2. Direct Registration: Share invitation codes manually
  3. Organization Management: Control user access per organization

Role Hierarchy

  • Super Admin: Global access, can manage all organizations
  • Admin: Organization-specific admin rights
  • User: Standard user with limited permissions

Zoneweaver API Integration

Backend Requirements

Your Zoneweaver API must be:

  • Accessible: Network connectivity from frontend
  • Configured: Proper API key authentication
  • Running: Service active and responding

Testing Connection

Use the built-in connection test:

  1. Go to Settings → Servers
  2. Click Test Connection on your server
  3. Verify successful API communication

Troubleshooting

Common Issues

Cannot Access Web Interface

  • Check port 3443 is open
  • Verify SSL certificate validity
  • Check service status: svcs zoneweaver

Backend Connection Failed

  • Test network connectivity: curl https://backend:5001/api/
  • Verify API key is correct
  • Check Zoneweaver API service status

User Registration Issues

  • Ensure allow_new_organizations: true in config
  • Check email configuration for invitations
  • Verify database permissions

Log Locations

  • Frontend Service: /var/log/zoneweaver/zoneweaver.log
  • System Logs: svcs -xv zoneweaver
  • Browser Console: F12 Developer Tools

Next Steps

Once your basic setup is working:

  1. Configure Authentication - Set up proper user management
  2. User Guide - Learn the web interface
  3. Backend Integration - Advanced Zoneweaver API configuration
  4. Installation Guide - Production deployment options

Need help? Check our Support Documentation or visit the GitHub repository.