chore: docs, plans archive, script updates, submodule refs
This commit is contained in:
datadunia
@@ -28,9 +28,75 @@ The first run will automatically:
|
||||
- Auto-generate the **Local Primary Node** WireGuard keys on the first boot.
|
||||
- Create the database schema via automated migration.
|
||||
|
||||
### Option B: Native (Without Docker)
|
||||
**Update Options:**
|
||||
```bash
|
||||
bash update.sh # Smart update (only rebuild if changes detected)
|
||||
bash update.sh --force # Force rebuild regardless of changes
|
||||
bash update.sh --backup # Backup PostgreSQL before update
|
||||
bash update.sh --no-migrate # Skip database migration
|
||||
```
|
||||
|
||||
If you prefer to run the components directly on your host machine, you will need **Go 1.25+**, **Node.js 24+**, **PostgreSQL**, and **Redis**.
|
||||
### Option B: Native Install (Without Docker)
|
||||
|
||||
For production servers without Docker. Requires **Go 1.25+**, **Node.js 24+**, **PostgreSQL**, **Redis**, **nginx**.
|
||||
|
||||
**Prerequisites:**
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt install -y golang nginx postgresql redis-server nftables wireguard-tools
|
||||
|
||||
# CentOS/Rocky
|
||||
sudo dnf install -y golang nginx postgresql-server redis nftables wireguard-tools
|
||||
```
|
||||
|
||||
**1. Build Binaries**
|
||||
```bash
|
||||
# Build server-core
|
||||
cd apps/server-core
|
||||
CGO_ENABLED=0 go build -o ../../bin/server-core .
|
||||
cd ../..
|
||||
|
||||
# Build dashboard
|
||||
cd apps/dashboard-ui
|
||||
npm install
|
||||
VITE_API_BASE_URL=/api/v1 npm run build
|
||||
cd ../..
|
||||
```
|
||||
|
||||
**2. 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
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- Create PostgreSQL database and user
|
||||
- Install binary to `/usr/local/bin/nexusguard-server`
|
||||
- Install dashboard to `/usr/share/nexusguard/dashboard/`
|
||||
- Create config at `/etc/nexusguard/nexusguard.conf`
|
||||
- Run database migration
|
||||
- Create systemd service
|
||||
- Configure nginx
|
||||
|
||||
**3. Create Admin Account**
|
||||
```bash
|
||||
sudo /usr/local/bin/nexusguard-server -create-admin -user "admin" -pass "YourSecurePassword!"
|
||||
```
|
||||
|
||||
**4. Uninstall**
|
||||
```bash
|
||||
sudo bash nexusguard-uninstall.sh # Remove files only
|
||||
sudo bash nexusguard-uninstall.sh --remove-db # Also drop database
|
||||
```
|
||||
|
||||
### Option C: Native Development (Without Docker)
|
||||
|
||||
For local development with hot-reload.
|
||||
|
||||
**1. Setup Database & Environment**
|
||||
Create a PostgreSQL database. Copy `.env.example` to `.env` and configure `DB_HOST`, `DB_USER`, `DB_PASSWORD`, and `DB_NAME` to point to your local database.
|
||||
@@ -57,36 +123,48 @@ cd apps/server-core
|
||||
go run -tags dev . -create-admin -user "admin" -pass "YourNewSecurePassword123!"
|
||||
```
|
||||
|
||||
### 2. Quick Reference with Makefile
|
||||
### Quick Reference with Makefile
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make up` | Start all services |
|
||||
| `make down` | Stop all services |
|
||||
| `make logs` | Tail all service logs |
|
||||
| `make dev` | Start with hot-reload (air) for development |
|
||||
| `make migrate` | Run production database migration manually |
|
||||
| `make reset-db` | **Reset database to initial state** (drops volume, recreates tables, runs migration) |
|
||||
| `make up` | Start all services (Docker) |
|
||||
| `make down` | Stop all services (Docker) |
|
||||
| `make logs` | Tail all service logs (Docker) |
|
||||
| `make dev` | Start with hot-reload (Docker) |
|
||||
| `make migrate` | Run production database migration (Docker) |
|
||||
| `make reset-db` | **Reset database to initial state** (Docker) |
|
||||
|
||||
> `make reset-db` is useful during development to wipe all data and start fresh. It stops all containers, deletes the PostgreSQL volume, recreates the tables, and runs the migration in one command.
|
||||
> `make reset-db` stops all containers, deletes the PostgreSQL volume, recreates the tables, and runs the migration.
|
||||
|
||||
### 3. Domain & Port Configuration
|
||||
If you are deploying this to production, you must edit the `.env` file generated in the root directory:
|
||||
- **Change API Port**: Modify `API_PORT=8080`.
|
||||
- **Change Web/API Domain**: Modify `VITE_API_BASE_URL` to point to your public API domain (e.g., `https://api.yourdomain.com/api/v1`).
|
||||
- **Database & Crypto**: Ensure you change the default database passwords and generate secure 256-bit Hex keys for `JWT_SECRET` and `SERVER_SALT`.
|
||||
### Domain & Port Configuration
|
||||
|
||||
### 4. Creating / Changing the Admin Account
|
||||
The system operates on a strict **Zero-Attack Surface** policy. The `/auth/register` API is locked down. To create the first Admin user (or reset their password), you must execute a command directly inside the running Docker container:
|
||||
**Docker:** Edit `.env` in root directory.
|
||||
**Native:** Edit `/etc/nexusguard/nexusguard.conf`.
|
||||
|
||||
Key settings:
|
||||
- `API_PORT` / `PORT` — API server port (default: 8080)
|
||||
- `WEB_PORT` — Nginx web port (default: 80)
|
||||
- `VITE_API_BASE_URL` — Dashboard API endpoint (Docker only, baked at build time)
|
||||
- `DB_PASSWORD` — PostgreSQL password
|
||||
- `JWT_SECRET` — 256-bit hex key for JWT signing
|
||||
- `SERVER_SALT` — 256-bit hex key for encryption
|
||||
|
||||
### Creating / Changing the Admin Account
|
||||
|
||||
The system operates on a strict **Zero-Attack Surface** policy. The `/auth/register` API is locked down. To create the first Admin user (or reset their password):
|
||||
|
||||
**Docker:**
|
||||
```bash
|
||||
docker exec -it nexus-guard-suite-server-core-1 ./server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"
|
||||
```
|
||||
*(You can use this exact same command later if you ever forget the admin password to forcefully reset it).*
|
||||
|
||||
Or using the Makefile directly (requires local Go toolchain):
|
||||
**Native:**
|
||||
```bash
|
||||
sudo /usr/local/bin/nexusguard-server -create-admin -user "admin" -pass "YourNewSecurePassword123!"
|
||||
```
|
||||
|
||||
**Development:**
|
||||
```bash
|
||||
make migrate
|
||||
go run -tags dev ./apps/server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"
|
||||
```
|
||||
|
||||
@@ -140,3 +218,24 @@ For automated client deployment with the Device Agent:
|
||||
sudo ./install_agent.sh --server-url "https://api.yourdomain.com" --token "<REG_TOKEN>"
|
||||
```
|
||||
4. The agent will securely provision its WireGuard keys via AES-256-GCM and appear as **Online** on the Dashboard.
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
```
|
||||
NexusGuard/
|
||||
├── apps/
|
||||
│ ├── server-core/ # Go/Gin API backend
|
||||
│ ├── dashboard-ui/ # Vue 3 frontend
|
||||
│ └── device-agent/ # Go client agent
|
||||
├── bin/ # Built binaries (gitignored)
|
||||
├── docker-compose.yml # Docker orchestration
|
||||
├── docker-compose.dev.yml # Docker dev (hot-reload)
|
||||
├── update.sh # Docker update script
|
||||
├── setup.sh # Docker initial setup
|
||||
├── nexusguard-install.sh # Native install script
|
||||
├── nexusguard-uninstall.sh # Native uninstall script
|
||||
├── .env.example # Environment template
|
||||
└── Makefile # Quick commands
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user