Skip to content

Latest commit

 

History

History
179 lines (129 loc) · 6.21 KB

INSTALLATION.md

File metadata and controls

179 lines (129 loc) · 6.21 KB

Installation

Plexus can be run via Docker, as a standalone binary, or from source using Bun.

Prerequisites

  • Bun 1.4.4+: Plexus is built with Bun. If you are running from source or building binaries, you will need Bun 1.4.4 or newer installed (mise install installs the pinned 1.4.4; Docker and CI pin oven/bun:1.4.4).

Docker (Preferred)

The easiest way to run Plexus is using the pre-built Docker image.

Pull the image:

docker pull ghcr.io/mcowger/plexus:latest

Run the container:

docker run -p 4000:4000 \
  -v plexus-data:/app/data \
  -e ADMIN_KEY="your-admin-key" \
  -e DATABASE_URL=sqlite:///app/data/plexus.db \
  -e LOG_LEVEL=info \
  ghcr.io/mcowger/plexus:latest
  • Mount a volume to /app/data to persist usage logs, configuration, and other data.
  • ADMIN_KEY is required — set it to a secure password for accessing the admin dashboard and management API.
  • DATABASE_URL is optional (defaults to SQLite at ./data/plexus.db when unset) — set it to a sqlite:// path (inside the mounted volume) or a postgres:// connection string when connecting to PostgreSQL or custom locations.
  • Set LOG_LEVEL to control verbosity.
  • The Docker image includes bunx and uvx so Plexus can run configured Local HTTP MCP servers inside the container.

Building the Docker Image

If you want to build the image yourself:

Build the image:

docker build -t plexus .

Run the container:

docker run -p 4000:4000 \
  -v plexus-data:/app/data \
  -e ADMIN_KEY="your-admin-key" \
  -e DATABASE_URL=sqlite:///app/data/plexus.db \
  -e LOG_LEVEL=info \
  plexus

Standalone Binary

Plexus can be compiled into a single, self-contained binary that includes the Bun runtime, all backend logic, the pre-built frontend dashboard, and the database migration files.

Build Commands

  1. Clone the repository:

    git clone https://github.com/mcowger/plexus.git
    cd plexus
  2. Install dependencies:

    bun install
  3. Compile:

    • macOS (ARM64/Apple Silicon): bun run compile:macos
    • Linux (x64): bun run compile:linux-amd64
    • Linux (ARM64): bun run compile:linux-arm64
    • Windows (x64): bun run compile:windows

The resulting executable will be named plexus-macos, plexus-linux-amd64, plexus-linux-arm64, or plexus.exe in the project root.

The binary is fully self-contained: migration SQL files are embedded inside it at compile time, so no separate drizzle/ directory or DRIZZLE_MIGRATIONS_PATH environment variable is needed when running the standalone binary.

Running the Windows Standalone Binary

If plexus.exe opens and closes immediately, run it from a terminal so startup errors remain visible. ADMIN_KEY must be set before starting the server.

Windows PowerShell:

$env:ADMIN_KEY = "your-admin-password"
$env:DATABASE_URL = "sqlite://./data/plexus.db"
.\plexus.exe

Windows Command Prompt:

set ADMIN_KEY=your-admin-password
set DATABASE_URL=sqlite://./data/plexus.db
plexus.exe

Running from Source

  1. Clone the repository:

    git clone https://github.com/mcowger/plexus.git
    cd plexus
  2. Install dependencies:

    bun install
  3. Start Development Stack:

    ADMIN_KEY="your-admin-key" DATABASE_URL=sqlite://./data/plexus.db bun run dev

    If mise is not activated in your shell, use mise exec -- bun run dev. Run mise install once to install the project-managed tools. FRP is optional; without frpc on PATH, or without FRPC_SERVER_ADDR and FRPC_AUTH_TOKEN, the dev server runs without a tunnel. The tunnel is stopped with the direct dev process, or when Paseo stops its managed service.

    To run the background lifecycle instead:

    bun run dev:agent --detach
    bun run dev:stop

    Prefix these commands with mise exec -- when mise is not activated. When Paseo manages the stack, make sure Paseo itself runs with the project mise environment if you want to use the mise-managed frpc binary.

Environment Variables

When running Plexus, you can use the following environment variables to control its behavior:

  • ADMIN_KEY (Required): Password for the admin dashboard and management API.
    • Must be set before starting the server. Server will refuse to start without it.
  • DATABASE_URL (Optional): Database connection string (defaults to SQLite at ./data/plexus.db).
    • SQLite: sqlite:///app/data/plexus.db or sqlite://./data/plexus.db
    • PostgreSQL: postgres://user:password@host:5432/dbname
  • ENCRYPTION_KEY (Optional): Encryption key for sensitive data at rest (API keys, OAuth tokens, provider credentials).
  • LOG_LEVEL: The verbosity of the server logs.
    • Supported values: error, warn, info, debug, silly.
    • Default: info.
    • Note: silly logs all request/response/transformations.
    • Runtime override: You can change log level live via the management API/UI (/v0/management/logging/level). This override is ephemeral and resets on restart.
  • PORT (Optional): HTTP server port. Default: 4000 (Note: When running bun run dev locally, the port is automatically derived from the git worktree directory name).
  • HOST (Optional): Address to bind to. Default: 0.0.0.0
  • DATA_DIR (Optional): Directory for SQLite database. Default: ./data
  • FRPC_SERVER_ADDR (Development only): LAN-reachable address of the frps server.
  • FRPC_AUTH_TOKEN (Development only): Token shared with frps.
  • FRPC_SERVER_PORT (Development only): frps control port. Default: 7000.
  • FRPC_SUBDOMAIN_HOST (Development only): Optional suffix used only to print the full HTTPS URL. The frps subDomainHost setting controls routing.

Example Usage

ADMIN_KEY="your-secret" DATABASE_URL=sqlite://./data/plexus.db LOG_LEVEL=debug ./plexus

For configuration details, please refer to the Configuration Guide.