Skip to main content

​
What is a Proxy?

A proxy is a server that acts as an intermediary between your application and another server. In the context of SCANOSS, a reverse proxy sits between your tools and the SCANOSS API, forwarding requests on your behalf.

​
Why Use a Proxy with SCANOSS?

​
Centralised API Key Management

The proxy automatically injects the SCANOSS API key into outgoing requests, eliminating the need to distribute it to individual developer machines. This ensures centralised control over API access.

​
Security & Access Control

  • Enforce corporate policies with centralised traffic monitoring and filtering
  • Restrict access to authorised internal systems
  • Maintain full visibility into all API interactions

​
Usage Tracking & Logging

  • Monitor scan activity by team or project
  • Analyse API usage patterns
  • Preserve detailed audit logs for compliance

​
Network Architecture Requirements

Supports enterprise network policies requiring:
  • Centralised outbound traffic control
  • Internal certificate-based communication
  • Deep packet inspection and filtering

​
Prerequisites

Before you begin, you will need:
  • Caddy: A reverse proxy server used to inject your SCANOSS API key into outgoing API requests.
  • SCANOSS API key: Required to authenticate requests to the SCANOSS API.

​
Basic Proxy Configuration

Follow the steps below to configure Caddy as a reverse proxy that injects your SCANOSS API key into outgoing requests. Windows / macOS / Linux
  1. Create a new folder to store Caddy and its configuration.
  2. Inside that folder, create a new file named Caddyfile.
  3. Add the following configuration:
:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
  1. Replace YOUR_API_KEY_HERE with your actual SCANOSS API key. If you do not yet have a key, refer to the Prerequisites section above.
  2. Save and close the file.
You can change port 1980 to any available port (e.g. 8080 or 8888).
Ensure the chosen port is not already in use by another service.

​
Running Caddy

Once the Caddyfile is configured, you can start the proxy in either interactive or background mode.

​
Interactive Mode

Run Caddy in the foreground to verify your configuration and observe logs in real time. Windows 
caddy run --config Caddyfile
macOS / Linux 
sudo caddy run --config Caddyfile

​
Background Mode

Run Caddy as a background process so it continues running after you close the terminal. Windows 
caddy start --config Caddyfile
macOS / Linux 
sudo caddy start --config Caddyfile

​
Stopping Caddy

caddy stop

​
Running as a systemd Service (Linux only)

Note: systemd is a Linux-specific init system and is not available on macOS by default. macOS users should use launchd or run Caddy in background mode instead.
Run Caddy as a systemd service to ensure it starts automatically on boot and restarts if it crashes.
  1. Create a systemd service file:
sudo nano /etc/systemd/system/caddy-proxy.service
  1. Add the following configuration:
[Unit]
Description=Caddy API Proxy
After=network.target

[Service]
ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile
Restart=always
User=caddy
Group=caddy

[Install]
WantedBy=multi-user.target
Update /etc/caddy/Caddyfile to match the actual path to your Caddyfile.
Update /usr/bin/caddy if Caddy is installed in a different location (verify with which caddy).
  1. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable caddy-proxy
sudo systemctl start caddy-proxy
  1. Check the service status:
sudo systemctl status caddy-proxy

​
Running as a Windows Service

Run Caddy as a Windows service to ensure it starts automatically on boot and restarts if it crashes.
  1. Download and install NSSM (Non-Sucking Service Manager).
  2. Open PowerShell as Administrator and change directory to the folder where NSSM is installed.
  3. Install Caddy as a service:
nssm install CaddyProxy "C:\path\to\caddy.exe" "run --config C:\path\to\Caddyfile"
Replace C:\path\to\caddy.exe with the actual path to your Caddy executable.
Replace C:\path\to\Caddyfile with the actual path to your Caddyfile.
  1. Configure the service (optional):
nssm set CaddyProxy AppDirectory "C:\path\to\caddy\folder"
nssm set CaddyProxy AppStdout "C:\path\to\logs\caddy-output.log"
nssm set CaddyProxy AppStderr "C:\path\to\logs\caddy-error.log"
  1. Start the service:
nssm start CaddyProxy
  1. Verify the service is running:
nssm status CaddyProxy
Managing the Windows service: 
nssm stop CaddyProxy
nssm restart CaddyProxy
nssm remove CaddyProxy confirm
You can also manage the service through the Windows Services manager (services.msc).

​
Troubleshooting

​
Port Conflicts

If Caddy fails to start, Caddy’s built-in admin API (which listens on a separate port by default) may be conflicting with another process. Disable the admin API by adding the following global block at the top of your Caddyfile, before any site definitions: 
{
  admin off
}

​
Stopping Existing Caddy Instances

If the conflict persists, check for running Caddy processes and stop them. Windows: 
taskkill /IM caddy.exe /F
Linux / macOS: 
pkill caddy

# Or, if running as a systemd service (Linux only)
sudo systemctl stop caddy