> ## 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.

# API Installation

> This section provides instructions for deploying the [SCANOSS Go API](https://github.com/scanoss/api.go).

## Prerequisites

Before installing the **SCANOSS Go API**, ensure the following components are
already installed and operational on the target system.

* [LDB](https://github.com/scanoss/ldb)
* [Engine](https://github.com/scanoss/engine)

## Installation

Before starting the installation, ensure you have received a `.tar.gz` archive
containing the following:

* Installation scripts
* **API binary**
* **Engine binary** (optional)

> **Note:** The Engine binary is optional if the SCANOSS Engine is already
> installed as a prerequisite (see above).

### Create a Dedicated User

Create a system user under which the **SCANOSS Go API** service will run:

```bash theme={null}
sudo useradd --system scanoss
```

### Download the API

Download the latest release for your architecture (**AMD64** or **ARM64**)
from the [SCANOSS Go API releases](https://github.com/scanoss/api.go/releases),
or use the following commands:

```bash theme={null}
mkdir api.go
curl -L https://api.github.com/repos/scanoss/api.go/tarball -o api.go.tar.gz
tar -xzvf api.go.tar.gz -C api.go --strip-components=1
```

### Build the API Binary

> **Note:** This step is only required if you are building from source rather
> than using a pre-built release binary.

Navigate to the source directory and build the binary for your architecture:

```bash theme={null}
cd api.go
make build_amd   # For AMD64
# or
make build_arm   # For ARM64
```

### Set Up the Environment and Install

Run the setup script included in the package:

```bash theme={null}
cd scripts
./env-setup.sh
```

### Start the Service

```bash theme={null}
sudo systemctl start scanoss-go-api
```

### Verify the Service

Confirm the service is running by checking the following endpoints:

```bash theme={null}
curl -i -X GET http://localhost:5443/
curl -i -X GET http://localhost:5443/api/health
curl -i -X GET http://localhost:5443/api/metrics/all
```

View logs in real time:

```bash theme={null}
tail -f /var/log/scanoss/api/scanoss-api-prod.log
```

Check the service status:

```bash theme={null}
sudo systemctl status scanoss-go-api
```

Stop the service:

```bash theme={null}
sudo systemctl stop scanoss-go-api
```

## Configuration & Tuning

The behaviour of the **SCANOSS Go API** can be customised by modifying the
configuration file located at:

```
/usr/local/etc/scanoss/api/app-config-prod.json
```

### Default Configuration

```json theme={null}
{
  "App": {
    "Name": "SCANOSS API Server",
    "Port": "5443",
    "Addr": "",
    "Debug": false,
    "Trace": false,
    "Mode": "prod"
  },
  "Logging": {
    "DynamicLogging": false,
    "DynamicPort": "localhost:60085",
    "ConfigFile": ""
  },
  "Scanning": {
    "WfpLoc": "",
    "ScanBinary": "scanoss",
    "ScanDebug": false,
    "ScanFlags": 0,
    "ScanTimeout": 300,
    "WfpGrouping": 3,
    "Workers": 2,
    "TmpFileDelete": true,
    "KeepFailedWfps": true
  },
  "Tls": {
    "CertFile": "",
    "KeyFile": ""
  }
}
```

### Configuration Parameters

#### Application Settings (`App`)

| Parameter   | Description                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `App.Name`  | Display name for the API, shown on startup.                                                                         |
| `App.Port`  | Port to which the service binds.                                                                                    |
| `App.Addr`  | Hostname or IP address for binding. Leave blank to bind to all interfaces (`0.0.0.0`), allowing remote connections. |
| `App.Debug` | Enables debug-level logging when set to `true`.                                                                     |
| `App.Trace` | Enables trace-level logging when set to `true`.                                                                     |
| `App.Mode`  | Logging and behaviour mode. Accepted values: `prod` (production) or `dev` (development).                            |

#### Logging Settings (`Logging`)

| Parameter                | Description                                                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Logging.DynamicLogging` | Enables dynamic log-level adjustment at runtime when set to `true`.                                                                    |
| `Logging.DynamicPort`    | Host and port used for runtime log-level control.                                                                                      |
| `Logging.ConfigFile`     | Optional path to a [Zap](https://github.com/uber-go/zap) logging configuration file. If left blank, default logging settings are used. |

#### Scanning Settings (`Scanning`)

WFP refers to **Winnowing Fingerprint**, the hashing method used by the SCANOSS
Engine to fingerprint source files.

| Parameter                 | Description                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Scanning.WfpLoc`         | Directory for temporary WFP files. Defaults to the system temporary directory if left blank.                                                                             |
| `Scanning.ScanBinary`     | Name or absolute path of the SCANOSS Engine binary.                                                                                                                      |
| `Scanning.ScanDebug`      | Enables debug mode for scan operations when set to `true`.                                                                                                               |
| `Scanning.ScanFlags`      | Default flags passed to the SCANOSS Engine. Set to `0` for no additional flags. Refer to the [Engine documentation](https://github.com/scanoss/engine) for valid values. |
| `Scanning.ScanTimeout`    | Timeout in seconds for individual scan commands.                                                                                                                         |
| `Scanning.WfpGrouping`    | Number of WFP requests batched per worker. Increase this value to reduce per-request overhead under high load.                                                           |
| `Scanning.Workers`        | Number of concurrent scan workers. Tune based on available CPU cores and expected request volume.                                                                        |
| `Scanning.TmpFileDelete`  | Deletes temporary WFP files after processing when set to `true`.                                                                                                         |
| `Scanning.KeepFailedWfps` | Retains WFP files for failed scan operations when set to `true`. Useful for debugging.                                                                                   |

#### TLS Settings (`Tls`)

| Parameter      | Description                       |
| -------------- | --------------------------------- |
| `Tls.CertFile` | Path to the TLS certificate file. |
| `Tls.KeyFile`  | Path to the private TLS key file. |