Self-hosting overview

Velic is open source under Apache-2.0. This section is a reference for running and operating your own instance: its prerequisites, configuration, architecture, and the Filecoin integration it builds on.

Not a product API

This is operator and architecture documentation for self-hosting the application. Velic is not a developer platform. There is no public API, SDK, or CLI to build against. The internal HTTP API between the web app and the backend is an implementation detail described here only so you can run the system, not an interface to integrate with.

Prerequisites

Node.js ≥ 22
pnpm (corepack enable)
Docker and Docker Compose

Repository layout

The repository is a pnpm + Turborepo monorepo:

api: Fastify HTTP API

worker: BullMQ ingest/restore pipeline

web: Vite + React app

docs: this documentation site

Run it locally

Install and configure

pnpm install
cp .env.example .env

Then fill in the secrets. See Configuration for every variable. At minimum you need:

# 32+ char secrets
openssl rand -hex 32   # APP_SESSION_SECRET
openssl rand -hex 32   # APP_DOWNLOAD_URL_SECRET
# 32-byte base64 key for wrapping per-master encryption keys
openssl rand -base64 32 # KMS_LOCAL_MASTER_KEY

and an operator signer key (an encrypted keystore, or OPERATOR_PRIVATE_KEY for dev) funded on the Calibration testnet.

Start infrastructure

docker compose up -d postgres redis minio minio-init

This brings up Postgres 16, Redis 7, and MinIO (S3-compatible staging for the encrypted upload), and creates the velic-staging bucket. The MinIO console is at http://localhost:9001.

Apply database migrations

pnpm --filter @velic/db exec drizzle-kit migrate

Run the apps

pnpm dev

The API serves on http://localhost:4000 (/health for liveness) and the web app on http://localhost:5173. For a fully containerised stack instead, use docker compose up --build (API on :4000, web on :4173).

Fund the operator on Calibration

This version builds and verifies on the Filecoin Calibration testnet (chain ID 314159). Fund the operator signer with test tokens:

tFIL (gas): https://faucet.calibnet.chainsafe-fil.io
tUSDFC (settlement): https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc

Beta contracts

The Filecoin Warm Storage and PDP contracts are beta. Pin versions, let the app resolve contract addresses at init (it reads them from the installed Synapse packages rather than hardcoding), and confirm the network state before any mainnet use.

Self-hosting overview

On this page