Documentation

Configuration

The main configuration file is proxystack.json in the ProxyStack root folder.

Structure

{
  "settings": {
    "httpPort": 80,
    "httpsPort": 443,
    "serverAdmin": "admin@localhost",
    "environment": "development"
  },
  "sites": [...],
  "apps": [...],
  "security": {...},
  "sentinel": {...}
}

Settings File

GUI-specific settings are stored separately in proxystack.settings.json:

{
  "autoStartApache": true,
  "alertsEnabled": true,
  "slackWebhook": "https://hooks.slack.com/services/...",
  "alertEmail": "alerts@example.com"
}

Environment Profiles

Store profiles in profiles/ folder:

• profiles/proxystack.development.json
• profiles/proxystack.staging.json
• profiles/proxystack.production.json

Switch profiles from the Security tab using the Environment dropdown.

Site Configuration

Reverse Proxy Site

{
  "domain": "app.example.com",
  "proxy": {
    "target": "http://localhost:3000",
    "timeout": 60,
    "websocket": true
  },
  "ssl": {
    "enabled": true,
    "cert": "certs/app.example.com-crt.pem",
    "key": "certs/app.example.com-key.pem"
  },
  "redirectHttpToHttps": true
}

Static Site with SPA Fallback

{
  "domain": "static.example.com",
  "documentRoot": "sites/my-react-app/build",
  "spaFallback": true,
  "ssl": { "enabled": true, "cert": "...", "key": "..." }
}

Hybrid Site (Static + Proxy Routes)

{
  "domain": "hybrid.example.com",
  "documentRoot": "sites/frontend",
  "spaFallback": true,
  "proxyRoutes": [
    { "path": "/api", "target": "http://localhost:8000" },
    { "path": "/ws", "target": "ws://localhost:8001", "websocket": true }
  ],
  "ssl": { "enabled": true, "cert": "...", "key": "..." }
}

Site Fields

App Configuration

{
  "apps": [
    {
      "name": "My API",
      "command": "npm run dev",
      "workingDirectory": "apps/my-api",
      "port": 3000,
      "autoStart": true,
      "autoRestart": true,
      "subProcesses": [
        {
          "name": "Supabase",
          "command": "npx supabase start",
          "workingDirectory": null,
          "port": 54321,
          "autoStart": true
        }
      ]
    }
  ]
}

Sub-Processes

All commands are launched with echo y | piped to stdin and npm_config_yes=true set in the environment to auto-accept prompts. Sub-processes start before the main command and are killed together when the app is stopped.

SSL & Certificates

Let's Encrypt (Free Certificates)

1. Go to Certs tab
2. Click "Let's Encrypt"
3. Enter your domain and email
4. ProxyStack stops Apache, runs win-acme for HTTP-01 validation, then restarts Apache
5. Certificate files are saved to certs/

Self-Signed Certificates

Use the "Generate Self-Signed" option in the Certs tab. ProxyStack uses the bundled OpenSSL to create a certificate and key pair. Useful for local development.

Auto-Detection

When a site has SSL enabled but empty cert/key paths, ProxyStack automatically scans certs/ for matching files based on the domain name. Supported naming patterns:

• Cert: {domain}-crt.pem, {domain}-cert.pem, {domain}.crt, {domain}-fullchain.pem
• Key: {domain}-key.pem, {domain}.key, {domain}-privkey.pem
• Chain: {domain}-chain.pem, {domain}-chain-only.pem

Docker Integration

The Docker tab provides comprehensive container management (requires Docker Desktop).

Container Management

• View all containers (running and stopped) with status, ports, and image info
• Start, stop, restart, and remove containers
• View container logs with real-time streaming
• Inspect container details (full JSON configuration)
• Execute commands in running containers

Image Management

• Pull Docker images with progress indicators
• List local images with size and tag info
• Remove unused images

Docker Compose

• Compose Up/Down for multi-service deployments
• Select any docker-compose.yml file

Container Templates

One-click deploy for common services: NGINX, Apache, Caddy, PostgreSQL, MySQL, MongoDB, Redis, Node.js, Python, Go, Adminer, pgAdmin.

Resource Monitoring

Real-time CPU usage, memory consumption, network I/O, and disk usage per container.

Portable PostgreSQL

ProxyStack can manage a portable PostgreSQL instance without Docker.

First Time Setup

1. Click "Start PostgreSQL" in the Docker tab
2. If not installed, you'll be prompted to download (~300 MB)
3. PostgreSQL extracts to postgres/ automatically
4. Database initializes on first run

Paths

Database Console

Go to Advanced tab → Database Console. Enter connection details and execute SQL queries directly from the GUI.

Security Features

{
  "security": {
    "enableHSTS": true,
    "enableXFrameOptions": true,
    "enableXContentTypeOptions": true,
    "enableXXSSProtection": true,
    "ipWhitelist": ["192.168.1.0/24"],
    "ipBlacklist": ["10.0.0.5"]
  }
}

Security Headers

ProxyStack automatically adds security headers to all HTTPS responses: X-Content-Type-Options, X-Frame-Options, and Referrer-Policy. Additional headers (HSTS, XSS Protection) can be enabled in the Security tab.

IP Access Control

Configure IP whitelists and blacklists to restrict access to your sites.

Encrypted Secrets Vault

The Secrets & Tools tab provides an encrypted vault for storing sensitive values like API keys, database passwords, and tokens.

Auto-Start on Boot

Enable "Start ProxyStack with Windows" and "Auto-start Apache" in the Security tab to run ProxyStack as a background service.

REST API Reference

Enable the API from Security tab → "Enable REST API (port 9090)".

Endpoints

Authentication

For production use, enable API key authentication in the Production tab. Include the header X-API-Key: your-key with all requests.

Usage Examples

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9090/api/status"
Invoke-RestMethod -Uri "http://localhost:9090/api/apache/restart" -Method POST

# curl
curl http://localhost:9090/api/health
curl -X POST http://localhost:9090/api/apache/restart

# Node.js
const res = await fetch('http://localhost:9090/api/status');
const status = await res.json();

Error Handling

All endpoints return JSON. Errors include an error field. HTTP status codes: 200 (success), 401 (unauthorized), 404 (not found), 500 (internal error).

Alerts & Notifications

Supported Channels

Alert Types

• Service Down — Sent when Apache, PostgreSQL, or an app stops responding
• Service Up — Sent when a service recovers
• SSL Expiry — Warning when certificates approach expiration

Cooldown

Default 5-minute cooldown prevents alert spam for flapping services. Each service has an independent cooldown timer.

Plugins

Extend ProxyStack with plugins from the Plugin Marketplace (Advanced tab).

Managing Plugins

1. Go to Advanced tab → Plugin Marketplace
2. Click "Install Plugin" to add a new plugin
3. Click "Configure" to set up plugin-specific settings
4. Reload Apache config to apply plugin changes

Plugin Configuration

Plugin configs are stored as JSON files in the plugins/ directory. Each plugin has its own configuration schema.

Team & Roles

The Team tab supports multi-user access with role-based permissions.

User Roles

Audit Log

All actions (site changes, config updates, service starts/stops) are recorded in the audit log with timestamp, user, action, and details. Stored in team.json.

GUI Tabs Overview

File Locations

Troubleshooting

Apache won't start

• Check port conflict: netstat -ano | findstr :80
• Click "Validate" to check configuration
• Review logs/error.log
• Verify all certificate paths exist

Apache won't stop

• Run ProxyStackGUI.exe as Administrator
• Manual kill: taskkill /F /IM httpd.exe

Let's Encrypt fails

• Verify DNS points to this server: nslookup yourdomain.com
• Ensure port 80 is open in Windows Firewall
• Check for rate limiting (wait 1 hour)
• ProxyStack auto-stops Apache during validation; ensure no other process holds port 80

Docker not found

• Start Docker Desktop and wait 30-60 seconds
• Verify: docker --version and docker ps

PostgreSQL won't start

• Check port 5432: netstat -ano | findstr :5432
• Verify postgres/pgsql/bin/pg_ctl.exe exists
• Check postgres/data/log/ for errors

REST API not responding

• Ensure GUI is running with API enabled (Security tab)
• Check port 9090 is not blocked
• Test: curl http://localhost:9090/api/status

Logs Location

• Apache access log: logs/access.log
• Apache error log: logs/error.log
• Per-site logs: logs/{domain}-access.log, logs/{domain}-error.log
• PostgreSQL: postgres/data/log/