Skip to main content

Getting Started

QvaSoft Gateway is an API Gateway featuring a built-in visual admin panel for managing routes, authentication, and more.

Prerequisites​

QvaSoft Gateway is distributed as a portable, framework-dependent package. You need the .NET 10 Runtime installed on the target machine.

Download .NET 10 Runtime

Verify the runtime is installed:

dotnet --list-runtimes

You should see a line similar to:

Microsoft.AspNetCore.App 10.0.x [...]

Installation​

Option 1: Portable ZIP (Windows, Linux, macOS)​

  1. Download QvaSoftGateway.zip from the Download page
  2. Extract the ZIP file
  3. Run the gateway:
cd QvaSoftGateway
dotnet ApiGateway.dll

Option 2: Docker​

Pull the official image from Docker Hub (no .NET runtime installation needed):

docker pull asielhv/qvasoft-gateway
docker run -p 4000:4000 asielhv/qvasoft-gateway

For advanced Docker configuration (volumes, TLS, environment variables), see the Docker documentation.

First Steps​

1. Access the Admin Panel​

Open your browser and navigate to:

http://localhost:4000/admin

2. Register Your Admin Account​

On first launch, the admin panel will show a registration form. Enter:

  • Email -- will be used as your username
  • Full Name
  • Password -- must be at least 8 characters with uppercase, lowercase, and a digit

3. Log In​

After registration, you'll be automatically logged in. The dashboard shows an overview of your configured routes, Swagger endpoints, and aggregations.

4. Add Your First Route​

Navigate to Endpoints and click the + button to add a new route:

FieldExample Value
Inbound Path/api/users
Inbound MethodGET
Outbound Path/api/v1/users
Outbound Schemehttp
Outbound Hostlocalhost
Outbound Port3000

Click Save to apply the configuration.

5. Test the Route​

curl http://localhost:4000/api/users

The gateway will forward the request to http://localhost:3000/api/v1/users.

Default Ports​

PortProtocolDescription
4000HTTPGateway and Admin Panel
4001HTTPSGateway (TLS)

File Structure​

After extraction, the gateway directory contains:

QvaSoftGateway/
|-- ApiGateway.dll              # Main application
|-- appsettings.json            # Main configuration
|-- ocelot.json                 # Routes and gateway config
|-- identity.db                 # SQLite user database (auto-created)
|-- Plugins/                    # Custom delegating handler DLLs
|-- wwwroot/admin/              # Admin panel static files

Running as a systemd Service​

On Linux, create a service file to run the gateway in the background:

sudo nano /etc/systemd/system/qvasoft-gateway.service
[Unit]
Description=QvaSoft Gateway
After=network.target

[Service]
Type=notify
WorkingDirectory=/opt/qvasoft-gateway
ExecStart=/usr/bin/dotnet /opt/qvasoft-gateway/ApiGateway.dll
Restart=always
RestartSec=10
Environment=DOTNET_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable qvasoft-gateway
sudo systemctl start qvasoft-gateway

Next Steps​