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

# KB Docker example

> Build a local SCANOSS Knowledge Base with Docker and test file matching and snippet matching against it.

## Tools included

The image contains three tools:

* `ldb` is the Linked-list database that stores Knowledge Base (KB) data.
* `minr` is the mining tool that downloads and indexes open-source software (OSS) components.
* `scanoss` is the scanning engine that queries the KB.

## Quick start

### 1. Build the Docker image

```bash theme={null}
docker build -t scanoss-stack .
```

### 2. Start the container

```bash theme={null}
# sleep infinity keeps the container running so subsequent commands can be executed against it
docker run -d --name scanoss scanoss-stack sleep infinity
```

### 3. Create a Knowledge Base

```bash theme={null}
# Download and index an OSS component into the mined/ directory
docker exec scanoss minr -d scanoss,webhook,1.0,20200320,BSD-3-Clause,pkg:github/scanoss/webhook \
     -u https://github.com/scanoss/webhook/archive/1.0.tar.gz

# Extract snippet fingerprints from the mined/ directory
docker exec scanoss minr -z mined

# Create the version file required by the minr import step
docker exec scanoss bash -c "echo '{\"monthly\":\"25.01\", \"daily\":\"25.01.12\"}' > mined/version.json"

# Import the mined data into the KB
docker exec scanoss minr -i mined/
```

### 4. Download test files

Download and extract the same archive to get a file to scan:

```bash theme={null}
docker exec scanoss curl -sL https://github.com/scanoss/webhook/archive/1.0.tar.gz -o /tmp/test.tar.gz
docker exec scanoss tar -xzf /tmp/test.tar.gz -C /tmp
```

### 5. Scan the original file

An unmodified file should produce a 100% file match against the KB:

```bash theme={null}
docker exec scanoss scanoss /tmp/webhook-1.0/scanoss/github.py | jq
```

Expected output:

```json theme={null}
{
  "github.py": [{
    "id": "file",
    "matched": "100%",
    "purl": ["pkg:github/scanoss/webhook"],
    ...
  }]
}
```

### 6. Modify the file

```bash theme={null}
docker exec scanoss bash -c "echo '# modified by user' >> /tmp/webhook-1.0/scanoss/github.py"
```

### 7. Scan the modified file

The modified file should produce a snippet match, because only part of its code matches:

```bash theme={null}
docker exec scanoss scanoss /tmp/webhook-1.0/scanoss/github.py | jq
```

Expected output:

```json theme={null}
{
  "github.py": [{
    "id": "snippet",
    "matched": "97%",
    "lines": "1-192",
    "oss_lines": "3-194",
    "purl": ["pkg:github/scanoss/webhook"],
    ...
  }]
}
```

### 8. Cleanup

```bash theme={null}
docker stop scanoss && docker rm scanoss
```

## End-to-end example

```bash theme={null}
# Build and start
docker build -t scanoss-stack .
docker run -d --name scanoss scanoss-stack sleep infinity

# Create Knowledge Base
docker exec scanoss minr -d scanoss,webhook,1.0,20200320,BSD-3-Clause,pkg:github/scanoss/webhook \
     -u https://github.com/scanoss/webhook/archive/1.0.tar.gz
docker exec scanoss minr -z mined
docker exec scanoss bash -c "echo '{\"monthly\":\"25.01\", \"daily\":\"25.01.12\"}' > mined/version.json"
docker exec scanoss minr -i mined/

# Download test files
docker exec scanoss curl -sL https://github.com/scanoss/webhook/archive/1.0.tar.gz -o /tmp/test.tar.gz
docker exec scanoss tar -xzf /tmp/test.tar.gz -C /tmp

# Test file matching (100%)
docker exec scanoss scanoss /tmp/webhook-1.0/scanoss/github.py | jq

# Modify file
docker exec scanoss bash -c "echo '# modified' >> /tmp/webhook-1.0/scanoss/github.py"

# Test snippet matching
docker exec scanoss scanoss /tmp/webhook-1.0/scanoss/github.py | jq

# Cleanup
docker stop scanoss && docker rm scanoss
```

## Scanning your own files

### Copy files into the container

To scan files from your host machine, copy them into the container first:

```bash theme={null}
# Copy a file into the container
docker cp /path/to/your/file.py scanoss:/tmp/file.py

# Scan it
docker exec scanoss scanoss /tmp/file.py
```

### Mount a volume

To scan a directory without copying each file, mount a volume when you start the container:

```bash theme={null}
docker run -d --name scanoss -v $(pwd)/mycode:/code scanoss-stack sleep infinity
docker exec scanoss scanoss /code/myfile.py
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.