🌐 NeutronVPN

NeutronVPN is a secure, high-performance VPN solution built with WireGuard, a Django backend (with REST API), and an Electron + React client. It provides encrypted tunnels, dynamic client management, real-time stats, and remote server management via SSH.

---

Table of Contents

• 📌 Features
• 🛠️ Tech Stack
• 📁 Folder Structure
• ⚡ Quick Start
• 📦 Installation
  • PostgreSQL
  • Backend
  • Frontend (Electron + React)
  • Docker (optional)
• 🚀 Usage
• 🔧 Configuration & Env
• 🖼️ Screenshots / Demo
• 🧭 Troubleshooting & FAQ
• 🤝 Contributing
• 🛡️ Security
• 📜 License & Acknowledgements

---

✨ Features

• 🔒 WireGuard-based VPN for fast and secure connections
• ⚙️ Dynamic client management with automatic IP assignment
• 📊 Real-time interface & public IP display, plus speed metrics
• 🚀 Connection speed monitoring and health checks
• 💻 Cross-platform Electron + React client with a modern UI
• 🔐 SSH-based server management (Paramiko) for adding/removing peers
• 🔁 Easy deployment options: local, Docker, or cloud droplets/EC2

---

🛠️ Tech Stack

• Backend: Django + Django REST Framework
• Frontend: React (Next.js) + Electron for desktop client
• Database: PostgreSQL
• VPN: WireGuard
• Server Management: SSH (Paramiko)
• CI / CD: (optional) GitHub Actions

---

📁 Folder Structure

.
└── NeutronVPN-linux/
    ├── backend
    ├── frontend
    ├── server (hosting files for DigitalOcean / AWS EC2)/
    │   ├── keys
    │   └── scripts/
    │       ├── start.sh
    │       └── stop.sh
    ├── .gitignore
    ├── install.sh
    ├── start.sh
    └── README.md

---

⚡ Quick Start (local development)

1. Clone repo and start backend:

   git clone <repo-url>
   cd NeutronVPN-linux/backend
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   cp .env.example .env
   # configure .env, then
   python manage.py migrate
   python manage.py runserver

2. Start frontend (Electron):

   cd ../frontend
   chmod +x ../../install.sh
   ../../install.sh
   ./start.sh

---

📦 Installation

PostgreSQL

Follow distribution-specific steps (Ubuntu / Fedora) — see original script blocks and ensure DB and user are created.

(Refer to the existing README for full commands; keep credentials secure.)

Backend

1. Create virtualenv, install requirements.
2. Configure .env (DB, SSH, SERVER_INTERFACE_NAME).
3. Run migrations and start server.

Frontend (Electron + React)

1. Run install script in repo root:

   chmod +x ./install.sh
   ./install.sh

2. Launch client:

   ./start.sh

Docker (optional)

A Docker setup can simplify deployment. Example (add Dockerfiles / docker-compose):

• Build containers for backend, frontend, and postgres.
• Use docker-compose with environment variables and volumes.

(Consider adding an official docker-compose.yaml in repo root.)

---

🚀 Usage

• Users connect to VPN servers via the Electron client.
• Client displays:
  • Interface IP (VPN)
  • Public IP
  • Connection speed
  • Security status
• Admins manage peers through Django REST API or server-side scripts (SSH).

Example WireGuard client config snippet (generated by backend):

[Interface]
PrivateKey = <client-private-key>
Address = 10.6.0.2/32
DNS = 1.1.1.1

[Peer]
PublicKey = <server-public-key>
Endpoint = your-server:51820
AllowedIPs = 0.0.0.0/0, ::/0

---

🔧 Configuration & Env

Backend (.env)

DB_NAME=neutronvpn
DB_USER=postgres
DB_PASSWORD=<pass>
DB_HOST=localhost
DB_PORT=5432

SSH_USER=root
SSH_PORT=22
SERVER_INTERFACE_NAME=wg0

SSH_KEY="-----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----"
SSH_KEY_PASSPHRASE=<hidden>

Frontend

NEXT_PUBLIC_API_URL=http://127.0.0.1:8000/api/

Keep secrets out of version control and rotate keys as needed.

---

🖼️ Screenshots / Demo

• Desktop client mockup:

---

🧭 Troubleshooting & FAQ

• Backend won’t start: check .env, DB connection, and migrations.
• WireGuard errors: ensure kernel module is loaded and interface name matches SERVER_INTERFACE_NAME.
• SSH remote commands failing: verify SSH_KEY and permissions; test with ssh -i path root@server.

Common commands:

• Check WireGuard status: sudo wg show
• View logs: journalctl -u --no-pager

---

🤝 Contributing

Contributions welcome — please:

1. Fork the repo
2. Create a feature branch
3. Open a PR with description and tests/screenshots
4. Respect code style and add changelog entry if appropriate

See CONTRIBUTING.md and CODE_OF_CONDUCT.md (add these files if not present).

---

🛡️ Security

Report vulnerabilities privately to the maintainers via the repository's security policy or email. Do not open public issues for security-sensitive information.

---

🔭 Roadmap

Planned improvements:

• Built-in auto-updates for Electron client
• Mobile clients (iOS/Android)
• Web dashboard for admin controls
• Improved CI/CD and Docker images

---

📜 License & Acknowledgements

MIT License — see LICENSE file.

Thanks to the open source projects that power NeutronVPN: WireGuard, Django, Electron, Next.js, PostgreSQL.

---

If you'd like, I can:

• Add a docker-compose example
• Create CONTRIBUTING.md and CODE_OF_CONDUCT.md templates
• Generate a release-ready systemd unit for the backend