vps_pilot

VPS Pilot

VPS Pilot is a server monitoring and management platform designed for private VPS servers.
It provides real-time monitoring, alerting, project management, and (future) cron job automation — all from a single dashboard.

✨ Features

📊 Real-time Monitoring

🚨 Smart Alerting

🚀 Projects Management (Coming Soon)

Sample config.vpspilot.json:

{
  "name": "meta ads dashboard",
  "tech": ["laravel", "react", "mysql"],
  "logs": [],
  "commands": [
    { "name": "node build", "command": "npm run build" },
    { "name": "php build", "command": "composer install" }
  ],
  "backups": {
    "env_file": ".env",
    "zip_file_name": "project_backup",
    "database": {
      "connection": "DB_CONNECTION",
      "host": "DB_HOST",
      "port": "DB_PORT",
      "username": "DB_USERNAME",
      "password": "DB_PASSWORD",
      "database_name": "DB_DATABASE"
    },
    "dir": [
      "storage/app",
      "database/companies"
    ]
  }
}

⏲️ Cron Jobs Management (Planned)

🛠️ Tech Stack

Component Technology
Agent Golang
Central Server Golang
Dashboard React + Vite
Database SQLite (dual DB)
Deployment Single executable

Architecture

📦 Quick Start

Prerequisites

1. Clone the Repository

git clone https://github.com/sanda0/vps_pilot.git
cd vps_pilot

The build.sh script handles everything: installs frontend dependencies, builds the React UI, and compiles it into the Go binary.

chmod +x build.sh
./build.sh

What it does:

  1. Installs Node.js dependencies (if needed)
  2. Builds the React frontend (client/dist/)
  3. Copies the built UI into server/cmd/app/dist/
  4. Compiles the Go binary with the UI embedded

Output: server/vps_pilot

3. Configure Environment

cd server
cp .env.example .env

Then open .env and fill in your values:

# Database directory
DB_PATH=./data

# JWT settings
TOKEN_LIFESPAN=60
TOKEN_SECRET=your-secret-key-min-32-chars

# TCP server (receives metrics from agents)
TCP_SERVER_PORT=55001

# Email alerts (optional)
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM_ADDRESS=noreply@vpspilot.com

Note: TOKEN_SECRET must be at least 32 characters long.

4. Run Database Migrations & Create Superuser

Migrations run automatically on startup, but you can also run them manually:

cd server
./vps_pilot -migrate

Then create your admin account:

./vps_pilot -create-superuser

Follow the interactive prompts to set a username and password.

5. Start the Server

cd server
./vps_pilot

By default the server listens on port 8080. To use a different port:

./vps_pilot -port 9090

6. Access the Dashboard

Open your browser: http://localhost:8080

Log in with the credentials you created in step 4.

🚩 CLI Flags

All flags are passed directly to the vps_pilot binary:

Flag Default Description
-port 8080 HTTP server port
-migrate — Run database migrations and exit
-create-superuser — Create an admin user interactively and exit
-create-makefile — Generate a Makefile in server/ and exit

Examples:

# Run on a custom port
./vps_pilot -port 3000

# Only run migrations (no server started)
./vps_pilot -migrate

# Create an admin user
./vps_pilot -create-superuser

# Generate Makefile helper
./vps_pilot -create-makefile

🔧 Development Mode

For development with hot reload:

Backend (Terminal 1)

cd server
go run main.go

Or with air for hot reload:

cd server
air

Frontend (Terminal 2)

cd client
npm install   # or: bun install
npm run dev   # or: bun run dev

Access:

📋 Makefile Commands

Generate the Makefile first if you don’t have one:

cd server
./vps_pilot -create-makefile

Then use:

cd server

# Migrations
make migrate              # Run database migrations
make db-info              # Show database info
make db-reset             # Reset databases

# Building
make build                # Build server only
make build-full           # Build with embedded UI (runs ../build.sh)
make sqlc                 # Generate SQLC code

# Running
make run                  # Run server
make dev                  # Run with hot reload (requires air)

# User Management
make create-superuser     # Create admin user

# Testing
make test                 # Run tests
make test-coverage        # Run tests with coverage

# Maintenance
make backup               # Backup databases
make clean                # Clean build artifacts

⚙️ Configuration

Email Alerts

Configure in .env:

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM_ADDRESS=noreply@vpspilot.com

Slack Alerts

  1. Go to your Slack workspace → Apps → Incoming Webhooks
  2. Create a new webhook for your desired channel
  3. Copy the webhook URL and paste it in the alert configuration in the dashboard

Discord Alerts

  1. Go to your Discord server settings → Integrations → Webhooks
  2. Create a new webhook for your desired channel
  3. Copy the webhook URL and paste it in the alert configuration in the dashboard

📂 Project Structure

vps_pilot/
├── client/                  # React + Vite frontend
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── pages/           # Page components
│   │   ├── hooks/           # Custom React hooks
│   │   └── lib/             # Utilities and API client
│   └── dist/                # Built frontend (generated, gitignored)
├── server/                  # Go backend
│   ├── cmd/
│   │   ├── app/             # HTTP server + embedded UI
│   │   │   └── dist/        # Embedded UI files (generated, gitignored)
│   │   └── cli/             # CLI tools (migrations, superuser, makefile)
│   ├── internal/
│   │   ├── db/              # Database layer (SQLC + migrations)
│   │   ├── handlers/        # HTTP handlers
│   │   ├── services/        # Business logic
│   │   ├── middleware/       # HTTP middleware
│   │   ├── tcpserver/       # TCP server for agent metrics
│   │   └── utils/           # Utilities
│   ├── data/                # SQLite databases (gitignored)
│   ├── main.go              # Entry point
│   └── vps_pilot            # Compiled binary (gitignored)
├── docs/                    # Documentation
├── build.sh                 # Full build script
└── README.md

🐳 Docker Deployment (Coming Soon)

Docker Compose setup will be available in a future release.

🔐 Security Notes

🐛 Troubleshooting

Build fails:

# Check the frontend builds cleanly
cd client && npm run build

# Check the Go code compiles
cd server && go build .

Server won’t start:

# Check if port 8080 is already in use
lsof -i :8080

# Check database directory permissions
ls -la server/data/

# Verify .env exists
ls -la server/.env

UI doesn’t load after build:

# Check that dist was copied into the server
ls server/cmd/app/dist/

# If missing, rebuild
./build.sh

Metrics not showing up:

📅 Roadmap

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

🧑‍💻 Author

Made with ❤️ by Sandakelum

📜 License

This project is licensed under the MIT License.

📸 Screenshots

Dashboard

Dashboard

Monitoring

Metrics View

🔗 Links

⭐ Star this repo if you find it useful!

This site is open source. Improve this page.