satellite

Quick Start

The fastest way to get started is using the @fileverse/satellite CLI:

npm install @fileverse/satellite
npx @fileverse/satellite --apiKey <key> --rpcUrl <url>

This will prompt for any missing values, set up configuration, run migrations, and start the server.

Manual Setup

git clone <your-repo-url>
cd satellite
npm install

Configure runtime variables via config/.env or ~/.satellite/.env (see Environment Variables). The CLI creates ~/.satellite/.env when you run fileverse-satellite with your API key.

Building the Project

Important: After installation or when making code changes, you must build the project:

# Clean old compiled code and rebuild
npm run clean && npm run build

build generates constants from config/network.config.json then runs tsup. For a build using dev config (e.g. to test against a local backend), use npm run build:local (uses config/dev.network.config.json).

Why clean before build?

• Ensures compiled code (dist/) matches your source code (src/)
• Prevents stale compiled code from causing errors
• Always run npm run clean && npm run build after:
  • Initial setup
  • Pulling new changes
  • Making significant code changes
  • Seeing errors that don't match your source code

For details on config flow and publishing, see docs/CONFIG_AND_PUBLISH.md.

Run

API Server

npm run start:api

Note: All /api/* endpoints require authentication via ?apiKey=<key> query parameter. The API key is the same key provided during setup.

Worker (for processing sync jobs)

npm run start:worker

Development

# Run API server (uses config/dev.network.config.json)
npm run dev

# Run worker in another terminal
npm run dev:worker

dev and dev:worker generate constants from config/dev.network.config.json before starting.

CLI Usage

The CLI tool ddctl provides commands to manage your ddocs from the command line.

Setup

Important: All commands must be run from the project root directory (where package.json is located).

1. Build the project:

   npm run clean && npm run build

2. Set execute permissions and link globally:

   chmod +x dist/commands/index.js
   npm link

   Note: npm link must be run from the project root directory because it reads package.json to find the binary path.

3. Verify installation:

   ddctl --help

Usage

# Development mode (no build needed, uses ts-node)
npm run dev:cli list

# Production mode (uses compiled code)
ddctl list

Events (failed recovery): List failed sync events with ddctl events list-failed. Retry one with ddctl events retry <eventId> or all with ddctl events retry-all. Events are scoped by portal; the API (GET /api/events/failed, POST /api/events/:id/retry, POST /api/events/retry-failed) only lists and retries events for the portal of the API key.

Note: The CLI works from any directory because DB_PATH is resolved to an absolute path at startup.

Environment Variables

Create a .env file in config/ or ~/.satellite/ with the following variables:

Required:

• DB_PATH: Database file path (required) - Must be an absolute path. Both API and CLI use the same database location.
  • Examples:
    • DB_PATH=/Users/username/data/satellite.db
    • DB_PATH=/absolute/path/to/satellite.db
  • Important:
    • Use absolute paths only (e.g., /Users/username/data/satellite.db)
    • Relative paths will cause issues when running CLI from different directories
    • The directory will be created automatically if it doesn't exist
    • Both API server and CLI tool use the exact same database file

Optional:

• PORT: Server port (default: 8001)
• IP: Server IP (default: 127.0.0.1)
• NODE_ENV: Environment (development, production, etc.)
• WORKER_CONCURRENCY: Number of concurrent events to process (default: 5)
• LOG_LEVEL: Logging level - trace, debug, info, warn, error, fatal (default: info)
• SERVICE_NAME: Service name for logging (default: satellite)

Note: The application will not start if DB_PATH is not set. Both the API server and CLI tool use the same database location specified by DB_PATH.