docs: add NexusGuard portfolio (architecture, tech-stack, features, deployment)
This commit is contained in:
datadunia
@@ -0,0 +1,482 @@
|
||||
# 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
|
||||
|
||||
# Generate .env file
|
||||
./setup.sh
|
||||
|
||||
# Edit configuration
|
||||
nano .env
|
||||
|
||||
# Start all services
|
||||
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 setup.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 `%APPDATA%\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) | `%APPDATA%\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
|
||||
```
|
||||
Reference in New Issue
Block a user