> ## 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. # Self-hosted: v2 to v3 > Set up a self-hosted SCANOSS v3 deployment next to your v2 one: the crc64 knowledge base, engine 6 and LDB 5, the scanoss-services-api service, decoration data, load balancing, validation, cut-over, and updates. This page is for customers who run SCANOSS in their own infrastructure on v2 and want to offer the v3 API to their users. v3 covers both scanning and decoration (licences, vulnerabilities, cryptography, dependencies, geoprovenance, copyright, and components). There is no installer for v3 yet. This page lists the manual steps. Your v2 deployment keeps working for now, so you can build v3 next to it, test it, and move clients over when you're ready. For the bigger picture, see [Migrating to v3](https://docs.scanoss.com/en/latest/developer-tools/migrating/overview.md). ## What changes | | v2 (today) | v3 | | - | - | - | | API service | `scanoss-go-api`, with endpoints such as `/scan/direct` | `scanoss-services-api`, one service with every endpoint under `/v3` | | Scan engine | Engine 5.x | Engine 6.x (`-crc64` releases) | | LDB library | LDB 4.x | LDB 5.x (`-crc64` releases) | | Knowledge base | The current KB line | The crc64 KB line, delivered over the same SFTP access | | Decoration data | Read from the KB by the engine | A separate serving database, delivered as DuckDB files | | File contents | Served from your KB | Not served from the self-hosted KB. The crc64 KB has no `sources` table. | | Clients | `scanoss-py`, SCANOSS integrations | [`scanoss-cli`](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py) | > [!WARNING] > > **Engine 6 and LDB 5 can't share a host with engine 5 and LDB 4.** The two lines are not > interchangeable in either direction: a crc64-line engine needs a crc64-line LDB, and an older > engine can't read crc64-line tables. The engine refuses to start on a mismatch. Build v3 on a > separate host and keep v2 where it is. See [SCANOSS LDB](https://docs.scanoss.com/en/latest/core/scanoss-ldb.md). ## Prerequisites * **A separate Linux x86-64 host** for v3. The `scanoss-services-api` binary needs glibc 2.36 or later, so use Debian 12 or later, or another distribution with glibc 2.36+. * **`libgcrypt` and `zlib`**, for example `apt install libgcrypt20 zlib1g` on Debian. * **At least 7.5 TB of SSD for the crc64 KB.** The full KB is about 7.2 TB today and grows by about 400 GB a month, so plan room for the updates you'll import. * **64 GB of RAM and 16 to 20 CPU threads** as a starting point. That is what SCANOSS runs on its own crc64 scan nodes. The services themselves use little memory: most of the RAM works as the operating system's page cache for the KB, and more cache means faster scans. * **Your SFTP credentials**, the same ones you use for v2 KB downloads. * **Outbound HTTPS to `api.osv.dev`**, if you turn on the OSV vulnerability source in the API service's config. * **An API key for `scanoss-cli`** is not needed when you point it at your own deployment. A custom API URL may run without a key. ## Set up v3 **1. Download the crc64 knowledge base** The crc64 KB is in your SFTP account under `kb/crc64/`, next to the v2 KB you download today: | Folder | What it holds | | - | - | | `kb/crc64/full//` | The full crc64 KB for a release. | | `kb/crc64/update//` | Incremental updates. | | `kb/duckdb//` | The decoration data, as DuckDB files. | The `kb-download.sh` script from the [on-premise repository](https://github.com/scanoss/on-premise) downloads all three. Its default is still the v2 KB, so always pass one of the crc64 modes with `-m`. See the [script's documentation](https://github.com/scanoss/on-premise/tree/main/install#knowledge-base-download-kb-downloadsh) for every option. ```bash theme={null} # Full crc64 KB. -o is where the 'oss' folder goes. Keep it apart from your v2 KB. ./kb-download.sh -m crc64_full -o /var/lib/ldb/oss # A crc64 update (latest by default, or pick one with -V ) ./kb-download.sh -m crc64_update # Decoration data ./kb-download.sh -m duckdb ``` Never point `-o` at a folder that holds a v2 KB: the tables have the same names. The crc64 KB and the DuckDB files are not part of every subscription. Without access, the script stops and asks you to contact SCANOSS support. The script asks for your SFTP host, port, user, and password unless you pass them. If you download with your own SFTP client instead, only take a full release folder that contains the `COMPLETE` file. A folder without it is still being published. Check every file after the download. Each entry has a checksum manifest: from release 26.10, a SHA-256 file under `sha256sum/`, and before that an MD5 file under `md5sum/`. Each DuckDB file comes with a `.sha256` file next to it. **2. Install LDB 5 and engine 6** Install the crc64 line of LDB first, then the engine. Their releases carry a `-crc64` suffix, for example `v5.0.0-crc64` for LDB and `v6.0.0-crc64` for the engine. Debian packages are on the [LDB releases](https://github.com/scanoss/ldb/releases) and [engine releases](https://github.com/scanoss/engine/releases) pages. Put the `oss` folder of the full KB where the engine reads it, `/var/lib/ldb/oss`, as in v2. Then check that both binaries report the crc64 line: ```bash theme={null} ldb -v scanoss -v ``` **3. Install and configure the API service** `scanoss-services-api` is one Linux x86-64 binary. It links the system `libldb.so` from LDB 5. Download the release from your SCANOSS SFTP account, with the same credentials you use for the KB. Copy the binary onto your `PATH`, and check it: ```bash theme={null} sudo install -m 0755 scanoss-services-api /usr/local/bin/ scanoss-services-api -version ``` Then write a config file. This is a minimal one for a node that does both scanning and decoration: ```yaml theme={null} server: host: "0.0.0.0" port: 9001 # the default port # Scanning. The /v3 scan endpoints exist only when engine_path is set. scan: engine_path: /usr/bin/scanoss # the engine 6 binary; it reads the KB in /var/lib/ldb timeout: 120s # per synchronous request batch: # chunked uploads from scanoss-cli max_total_size: 268435456 # largest fingerprint file one scan may upload (256 MiB) session_ttl: 1h # how long a scan and its result are kept after last use workers: 2 # scans that run at the same time # Decoration. Point this at the DuckDB serving file from kb/duckdb//. serving_db: driver: duckdb # sqlite | postgres | duckdb | none path: /var/lib/scanoss/serving/current.duckdb # Vulnerability sources. At least one must be enabled. vulnerabilities: osv: enabled: true # needs outbound HTTPS to api.osv.dev api_base_url: "https://api.osv.dev/v1" info_base_url: "https://osv.dev/vulnerability" api_workers: 5 scanoss: enabled: true max_workers: 5 ``` A few things to know about the config: * **Scan-only or decoration-only nodes.** Leave out `serving_db` for a node that only scans. Leave out `scan.engine_path` for a node that only decorates. * **Candidates per match.** `scan.batch.pipeline.max_components` sets how many candidate components a full-file match reports when the client doesn't ask. A client can override it for one scan with `scanoss-cli scan --max-components N` or `--max-components all`. * **DuckDB files.** Point `serving_db.path` at a symlink to the file, not at the file. To switch to a new month's file, change the symlink and send the process `SIGHUP`. The service checks the new file, switches to it, and keeps the old one if the new one fails its checks. * **File contents.** The crc64 KB has no `sources` table, so `/v3/file-contents` isn't served from your KB. Evidence links in licence and copyright results point at the public SCANOSS URLs by default. Start the service with the config file: ```bash theme={null} scanoss-services-api --config /etc/scanoss/config.yaml ``` To run it under systemd, a minimal unit looks like this: ```ini theme={null} [Unit] Description=SCANOSS Services API (v3) After=network-online.target [Service] ExecStart=/usr/local/bin/scanoss-services-api --config /etc/scanoss/config.yaml ExecReload=/bin/kill -HUP $MAINPID Restart=always [Install] WantedBy=multi-user.target ``` **4. Put it behind your proxy or load balancer** * **Authentication.** `scanoss-services-api` has no authentication of its own. Don't expose it directly. Put it behind your own reverse proxy and network controls. The service can also require client certificates (mutual TLS) with `server.tls.client_ca_file`. * **TLS.** The service listens on plain HTTP by default. Terminate TLS at your proxy, or turn on `server.tls` in the config. * **More than one node.** A `scanoss-cli` scan uploads in several blocks and then polls for the result. The service keeps each scan in its own memory and local disk, so every request for one scan must reach the same node. Route by the scan ID: the `X-Scan-Id` header on uploads to `/v3/wfp/scan`, and the ID in the path of `GET /v3/wfp/scan/{id}`. With one node, you don't need this. * **Upload size.** Allow request bodies of at least the upload block size. `scanoss-cli` sends 1 MiB blocks by default. **5. Validate** Check that the service is up and that its dependencies are ready: ```bash theme={null} curl -sS http://:9001/v3/health # {"status":"ok"} curl -sS http://:9001/v3/health/ready # 200 and "status": "ok" when ready ``` `/v3/health/ready` answers `503` with `"status": "not_ready"` when a critical dependency, such as the serving database, is unavailable. The service also serves its API reference at `/v3/docs/`. Then scan something you know, and decorate it: ```bash theme={null} scanoss-cli scan ./known-project \ --api-url http://:9001 \ --include licenses,vulns \ --output v3-results.json jq -r '.components[] | select(.scope == "detected") | .purl' v3-results.json ``` Compare the components with a v2 scan of the same code. Expect some differences. See [Behaviour changes that alter results](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md#behaviour-changes-that-alter-results). **6. Point clients at v3** Set the API URL on each client that moves to v3: ```bash theme={null} # One machine scanoss-cli config set api-url https://scanoss.example.com # CI jobs export SCANOSS_API_URL=https://scanoss.example.com ``` Use the base URL only. `scanoss-cli` adds the `/v3` paths. See [From scanoss-py to scanoss-cli](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md) for the rest of the client changes. **7. Keep v2 running** Leave your v2 deployment in place. Clients that stay on `scanoss-py`, and the SCANOSS integrations, need it: they can't talk to v3. If something goes wrong on v3, point the moved clients back at v2. Nothing on the v2 host changes, so that is your rollback. ## Keep v3 up to date * **KB updates.** SCANOSS publishes crc64 KB updates on the same cadence as v2, under `kb/crc64/update//` in your SFTP account. Download them with `kb-download.sh -m crc64_update` and import them as described in the [KB update guide](https://docs.scanoss.com/en/latest/installation/on-prem/kb-update-guide.md), using the crc64 folder instead of the v2 one. Check each download against its checksum manifest. * **Decoration data.** Each release has new DuckDB files under `kb/duckdb//`. Download the new file, check it against its `.sha256` file, point the `serving_db.path` symlink at it, and reload the service (`systemctl reload` with the unit above, or `kill -HUP`). * **Engine and LDB.** Upgrade them together and stay on the crc64 line. Check `ldb -v` and `scanoss -v` after every upgrade. * **The API service.** Keep the previous binary until the new one passes `/v3/health/ready`, so you can switch back. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.