SoftEther VPN Console

A web management application for SoftEther VPN Server, built with PatternFly 6 and the SoftEther VPN Server JSON-RPC API Suite.

This is the successor to softethervpn-web-console (PatternFly 4 / React 16), ported onto the current PatternFly seed (PatternFly 6 / React 18 / TypeScript 5 / react-router 7).

Before deploying, review the support and versioning policies. The 1.0.0 release notes summarize operational changes since the 0.2 series.

Releases

GitHub releases provide separate archives for the two deployment modes:

• softethervpn-console-vX.Y.Z.tar.gz contains the integrated frontend bundle.
• softethervpn-console-managed-vX.Y.Z.tar.gz contains the managed frontend and the compiled Node gateway.

Each archive has a matching .sha256 file. Download both files into the same directory and verify an archive before extracting it:

sha256sum -c softethervpn-console-vX.Y.Z.tar.gz.sha256

The published integrated archive uses the stable /admin/manager/ URL. Extract it into the external hamcore override directory beside the vpnserver executable, then restart the server:

vpnserver_dir=/usr/local/bin
install -d "$vpnserver_dir/hamcore/wwwroot/admin/manager"
tar -xzf softethervpn-console-vX.Y.Z.tar.gz \
  -C "$vpnserver_dir/hamcore/wwwroot/admin/manager"

Open https://vpn.example.com:5555/admin/manager/ and authenticate as the server or Virtual Hub administrator. Adjust vpnserver_dir to the directory containing the installed executable.

After extracting a managed archive, install the gateway's production dependencies and start it with:

npm ci --omit=dev --prefix gateway
npm --prefix gateway start

The gateway listens on plain HTTP and should be placed behind a trusted HTTPS reverse proxy. See gateway/README.md for its configuration and TLS boundaries.

Quick-start

git clone https://github.com/Leuca/softethervpn-console
cd softethervpn-console
npm ci
npm run start:dev

During development the console connects to the VPN server configured in .env.defaults. Create a local .env file (gitignored) to point it at your server:

VPN_DEV_HOST=vpn.example.org
VPN_DEV_PORT=5555
VPN_DEV_HUB=
VPN_DEV_PASSWORD=your-admin-password

Leave VPN_DEV_HUB empty for server administration. Set it to a Virtual Hub name when connecting with that hub's administrator credentials.

Production mode is embedded in the frontend at build time and cannot be changed at runtime. Each build replaces dist/, so archive or deploy one mode before building the other.

Build an integrated frontend for the VPN server's embedded web server with:

npm run build:integrated

Build and start the managed frontend and Node gateway with:

npm ci --prefix gateway
npm run build:managed
npm --prefix gateway run build
npm --prefix gateway start

For a local managed run, npm start performs a non-minified production-mode frontend build, compiles the gateway, and starts it. The first run populates a filesystem cache; later starts reuse unchanged frontend modules. Use the regular build:managed command above for release artifacts and final validation.

The integrated artifact calls the same-origin SoftEther /api/ endpoint and does not include managed login behavior. The managed artifact requires the gateway, which handles server selection and login. See gateway/README.md for its deployment and TLS boundaries.

Password manager custom fields

The managed login form exposes stable identifiers for password managers that support custom fields:

Field	Preferred id	Fallback name
Server host	managed-login-host	host
Port	managed-login-port	port
Virtual Hub	managed-login-hub	hub

Configure those fields on the same password-manager entry as the administrator password. Prefer the id when the password manager supports it. Custom-field matching is password-manager-specific; the password itself uses the standard current-password autocomplete field.

Development scripts

# Install frontend development/build dependencies
npm ci

# Install gateway dependencies when working on managed deployments
npm ci --prefix gateway

# Start the development server
npm run start:dev

# Build and run the managed frontend and gateway locally
npm start

# Build the integrated frontend (outputs to the "dist" directory)
npm run build:integrated

# Build the integrated frontend at the published release path
npm run build:integrated:release

# Build the managed frontend and gateway
npm run build:managed
npm --prefix gateway run build

# Run the test suite
npm run test

# Run the test suite with coverage
npm run test:coverage

# Run the linter
npm run lint

# Type-check the frontend, gateway, or complete repository
npm run type-check
npm run type-check:gateway
npm run type-check:all

# Run the code formatter
npm run format

# Launch a tool to inspect the bundle size
npm run bundle-profile:analyze

Integrating the console with SoftEther VPN Server

The embedded web server exposes the console below a URL prefix rather than at the site root. Published archives use /admin/manager/. Set ASSET_PATH when building for another prefix. For example:

ASSET_PATH=/admin/default/ npm run build:integrated

Keep the trailing slash so generated asset and base URLs resolve below the configured prefix.

Development note

This project is developed with assistance from AI coding tools. All changes remain subject to maintainer review and the project's testing and CI requirements.