> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Configuration

> Set up a Caddy reverse proxy to centrally manage your SCANOSS API key and control outbound traffic across your organisation.

## 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](https://caddyserver.com/): A reverse proxy server used to inject your SCANOSS
  API key into outgoing API requests.
* [SCANOSS API key](https://www.scanoss.com/try-it-now): 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
    }
}
```

4. Replace `YOUR_API_KEY_HERE` with your actual SCANOSS API key. If you do not yet have
   a key, refer to the [Prerequisites](#prerequisites) section above.
5. 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**

```powershell theme={null}
caddy run --config Caddyfile
```

**macOS / Linux**

```bash theme={null}
sudo caddy run --config Caddyfile
```

### Background Mode

Run Caddy as a background process so it continues running after you close the terminal.

**Windows**

```powershell theme={null}
caddy start --config Caddyfile
```

**macOS / Linux**

```bash theme={null}
sudo caddy start --config Caddyfile
```

### Stopping Caddy

```bash theme={null}
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:

```bash theme={null}
sudo nano /etc/systemd/system/caddy-proxy.service
```

2. Add the following configuration:

```ini theme={null}
[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`).

3. Enable and start the service:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable caddy-proxy
sudo systemctl start caddy-proxy
```

4. Check the service status:

```bash theme={null}
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)](https://nssm.cc/download).
2. Open PowerShell as Administrator and change directory to the folder where NSSM
   is installed.
3. Install Caddy as a service:

```powershell theme={null}
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`.

4. Configure the service (optional):

```powershell theme={null}
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"
```

5. Start the service:

```powershell theme={null}
nssm start CaddyProxy
```

6. Verify the service is running:

```powershell theme={null}
nssm status CaddyProxy
```

**Managing the Windows service:**

```powershell theme={null}
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:**

```powershell theme={null}
taskkill /IM caddy.exe /F
```

**Linux / macOS:**

```bash theme={null}
pkill caddy

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