Nexus-Guard-Suite/docs/portfolio/deployment.md

# Deployment Guide

NexusGuard supports three deployment modes: Docker (recommended), native install, and development.

## Docker Deployment (Recommended)

### Prerequisites

- Docker 20.10+
- Docker Compose v2
- Git

### Quick Start

```bash
# Clone repository
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite

# Start all services (auto-generates .env on first run)
bash update.sh
```

### First Boot

On first run, the system automatically:
1. Pulls latest code and builds Docker containers
2. Generates Local Primary Node WireGuard keys
3. Creates database schema via migration

### Configuration

Edit `.env` in root directory:

```bash
# Database
DB_HOST=postgres
DB_PORT=5432
DB_USER=nexusguard
DB_PASSWORD=your_secure_password
DB_NAME=nexusguard

# Redis
REDIS_ADDR=redis:6379

# Security (auto-generated by update.sh)
JWT_SECRET=<hex-64-chars>
SERVER_SALT=<hex-64-chars>

# Network
NFTABLES_TABLE=nexusguard
IPAM_POOL=10.8.0.0/16

# Server
GIN_MODE=release
PORT=8080

# Dashboard
VITE_API_BASE_URL=https://api.yourdomain.com/api/v1
```

### Update Commands

```bash
bash update.sh              # Smart update (rebuild only if changes)
bash update.sh --force      # Force rebuild
bash update.sh --backup     # Backup PostgreSQL before update
bash update.sh --no-migrate # Skip database migration
```

### Makefile Commands

| Command | Description |
|---------|-------------|
| `make up` | Start all services |
| `make down` | Stop all services |
| `make logs` | Tail all service logs |
| `make dev` | Start with hot-reload |
| `make migrate` | Run database migration |
| `make reset-db` | Reset database to initial state |

### Create Admin Account

```bash
docker exec -it nexus-guard-suite-server-core-1 ./server-core \
  -create-admin -user admin -pass "YourSecurePassword123!"
```

### Service Architecture

```
┌─────────────────────────────────────────────────┐
│                  Docker Compose                  │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
│  │ nginx    │  │ server-  │  │ postgres     │ │
│  │ :80/:443 │→ │ core     │→ │ :5432        │ │
│  │          │  │ :8080    │  │              │ │
│  └──────────┘  └──────────┘  └──────────────┘ │
│       ↑              ↑                         │
│  ┌──────────┐  ┌──────────┐                   │
│  │ dashboard│  │ redis    │                   │
│  │ (static) │  │ :6379    │                   │
│  └──────────┘  └──────────┘                   │
└─────────────────────────────────────────────────┘
```

### Port Mapping

| Service | Container Port | Host Port |
|---------|----------------|-----------|
| nginx | 80 | 80 |
| nginx | 443 | 443 |
| server-core | 8080 | 8080 |
| postgres | 5432 | 5432 |
| redis | 6379 | 6379 |

### Volumes

| Volume | Purpose |
|--------|---------|
| `postgres_data` | PostgreSQL data persistence |
| `redis_data` | Redis data persistence |

---

## Native Install

For production servers without Docker.

### Prerequisites

**Debian/Ubuntu:**
```bash
sudo apt install -y golang nginx postgresql redis-server nftables wireguard-tools
```

**CentOS/Rocky:**
```bash
sudo dnf install -y golang nginx postgresql-server redis nftables wireguard-tools
```

### Build Binaries

**Server Core:**
```bash
cd apps/server-core
CGO_ENABLED=0 go build -o ../../bin/server-core .
cd ../..
```

**Dashboard UI:**
```bash
cd apps/dashboard-ui
npm install
VITE_API_BASE_URL=/api/v1 npm run build
cd ../..
```

### Run Installer

```bash
sudo bash nexusguard-install.sh
```

**Options:**
```bash
sudo bash nexusguard-install.sh --server-port 8080 --web-port 80
sudo bash nexusguard-install.sh --db-host 127.0.0.1 --db-pass mypassword
```

**What the installer does:**
1. Creates PostgreSQL database and user
2. Installs binary to `/usr/local/bin/nexusguard-server`
3. Installs dashboard to `/usr/share/nexusguard/dashboard/`
4. Creates config at `/etc/nexusguard/nexusguard.conf`
5. Runs database migration
6. Creates systemd service
7. Configures nginx

### Create Admin Account

```bash
sudo /usr/local/bin/nexusguard-server \
  -create-admin -user admin -pass "YourSecurePassword123!"
```

### Service Management

```bash
# Start
sudo systemctl start nexusguard-server

# Stop
sudo systemctl stop nexusguard-server

# Status
sudo systemctl status nexusguard-server

# Logs
sudo journalctl -u nexusguard-server -f
```

### Configuration

Edit `/etc/nexusguard/nexusguard.conf`:

```bash
# Database
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=nexusguard
DB_PASSWORD=nexusguard
DB_NAME=nexusguard

# Redis
REDIS_ADDR=127.0.0.1:6379

# Security (auto-generated)
JWT_SECRET=<hex-64-chars>
SERVER_SALT=<hex-64-chars>

# Network
NFTABLES_TABLE=nexusguard
IPAM_POOL=10.8.0.0/16

# Server
GIN_MODE=release
PORT=8080
```

### Uninstall

```bash
# Remove files only
sudo bash nexusguard-uninstall.sh

# Also drop database
sudo bash nexusguard-uninstall.sh --remove-db
```

---

## Development Mode

For local development with hot-reload.

### Prerequisites

- Go 1.25+
- Node.js 24+
- PostgreSQL
- Redis

### Setup Database

1. Create PostgreSQL database:
```sql
CREATE DATABASE nexusguard;
CREATE USER nexusguard WITH PASSWORD 'nexusguard';
GRANT ALL PRIVILEGES ON DATABASE nexusguard TO nexusguard;
```

2. Copy environment template:
```bash
cp .env.example .env
```

3. Edit `.env` with your database credentials.

### Start Backend

```bash
cd apps/server-core
go mod download
go run -tags dev .
```

The `-tags dev` flag:
- Runs AutoMigrate on startup
- Provisions local node
- Enables debug logging

### Start Frontend

```bash
cd apps/dashboard-ui
npm install
npm run dev
```

Dashboard available at `http://localhost:5173`.

### Create Admin Account

```bash
cd apps/server-core
go run -tags dev . -create-admin -user admin -pass "YourNewSecurePassword123!"
```

### Development Workflow

```
┌─────────────────────────────────────────────────────────┐
│                    Development Setup                     │
│                                                         │
│  Terminal 1: Backend                                    │
│  ┌───────────────────────────────────────────────────┐ │
│  │ $ go run -tags dev .                              │ │
│  │ [dev] AutoMigrate complete                        │ │
│  │ [dev] Local node provisioned                      │ │
│  │ [gin] Listening on :8080                          │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  Terminal 2: Frontend                                   │
│  ┌───────────────────────────────────────────────────┐ │
│  │ $ npm run dev                                     │ │
│  │                                                   │ │
│  │   VITE v8.0.0  ready in 300 ms                    │ │
│  │                                                   │ │
│  │   ➜  Local:   http://localhost:5173/              │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  Browser: http://localhost:5173                         │
│  → Dashboard UI (Vue 3 + Vite)                         │
│  → API calls proxied to :8080                          │
└─────────────────────────────────────────────────────────┘
```

---

## Agent Installation

### Linux (Automated)

```bash
# Transfer script
scp scripts/install_agent.sh user@target-machine:~

# Run installer
sudo ./install_agent.sh \
  --server-url "https://api.yourdomain.com" \
  --token "REG_TOKEN_FROM_DASHBOARD"

# Verify
sudo systemctl status sys-bridge.service
```

**Options:**
- `--binary-name "my-agent"` — Override default binary name

**What the script does:**
1. Detects OS (APT/YUM)
2. Installs dependencies (iproute2, curl)
3. Downloads correct binary for architecture
4. Creates config at `~/.config/nexusguard/nexusguard.conf`
5. Creates systemd service
6. Starts agent

### Linux (Manual)

```bash
# Download binary
sudo cp nexusguard-device-agent-linux-amd64 /usr/local/bin/sys-bridge
sudo chmod +x /usr/local/bin/sys-bridge

# Create config
mkdir -p ~/.config/nexusguard
cat > ~/.config/nexusguard/nexusguard.conf <<EOF
SERVER_URL=https://api.yourdomain.com
REG_TOKEN=YOUR_REG_TOKEN
EOF

# Create systemd service
sudo tee /etc/systemd/system/sys-bridge.service > /dev/null <<EOF
[Unit]
Description=NexusGuard Device Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/sys-bridge
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Start
sudo systemctl daemon-reload
sudo systemctl enable --now sys-bridge.service
```

### Windows

1. Build GUI binary:
```bash
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build \
  -ldflags="-s -w -H windowsgui" \
  -o nexusguard-device-agent-gui.exe .
```

2. Place `wintun.dll` next to executable

3. Run agent — config auto-created at `%ProgramData%\NexusGuard\nexusguard.conf`

4. Edit config with `SERVER_URL` and `REG_TOKEN`

5. Right-click tray icon → Connect

**Service Management:**
- Install as Service — Register Windows service
- Uninstall Service — Remove Windows service
- Start on Boot — Toggle auto-start

### Docker

```bash
docker build -t nexus-device-agent .
docker run -d \
  --name nexus-agent \
  --restart unless-stopped \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -e SERVER_URL=https://api.yourdomain.com \
  -e REG_TOKEN=YOUR_REG_TOKEN \
  nexus-device-agent
```

**Required capabilities:**
- `NET_ADMIN` — Network interface configuration
- `NET_RAW` — Raw socket access (WireGuard)

---

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Agent fails to start | Missing config | Check config file has `SERVER_URL` + `REG_TOKEN` |
| Provisioning fails | Invalid token | Generate new token from Dashboard |
| Tunnel won't create | Missing kernel module | `sudo modprobe wireguard` |
| `ip addr add` fails | Permissions | Run as root or grant `CAP_NET_ADMIN` |
| Heartbeat timeout | Network issue | `curl -I <SERVER_URL>` |

### Log Locations

| Platform | Location |
|----------|----------|
| Docker | `docker logs -f nexus-guard-suite-server-core-1` |
| Native | `sudo journalctl -u nexusguard-server -f` |
| Agent (Linux) | `~/.local/share/nexusguard/logs/` |
| Agent (Windows) | `%ProgramData%\NexusGuard\logs\` |
| Agent (macOS) | `~/Library/Logs/NexusGuard/` |

### Debug Commands

```bash
# Check WireGuard interface
sudo wg show

# Test server connectivity
curl -I https://api.yourdomain.com/api/health

# Check agent version
/usr/local/bin/sys-bridge -version

# Run agent in foreground
sudo /usr/local/bin/sys-bridge -debug
```