Skip to content

INSTALLATION.md

Latest commit

 

History

History
125 lines (94 loc) · 4.12 KB

INSTALLATION.md

File metadata and controls

125 lines (94 loc) · 4.12 KB

Installation

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

Prerequisites

  • Bun: Plexus is built with Bun. If you are running from source or building binaries, you will need Bun installed.

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 $(pwd)/config/plexus.yaml:/app/config/plexus.yaml \
  -v plexus-data:/app/data \
  -e DATABASE_URL=sqlite:///app/data/plexus.db \
  -e LOG_LEVEL=info \
  ghcr.io/mcowger/plexus:latest
  • Mount your configuration file to /app/config/plexus.yaml.
  • Mount a volume to /app/data to persist usage logs and other data.
  • DATABASE_URL is required — set it to a sqlite:// path (inside the mounted volume) or a postgres:// connection string.
  • Set LOG_LEVEL to control verbosity.

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 $(pwd)/config/plexus.yaml:/app/config/plexus.yaml \
  -v plexus-data:/app/data \
  -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 run install:all

  3. Compile:

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

The resulting executable will be named plexus-macos (or plexus-linux / 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 from Source

  1. Clone the repository:

    git clone https://github.com/mcowger/plexus.git
cd plexus

  2. Install dependencies:

    bun run install:all

  3. Start Development Stack:

    DATABASE_URL=sqlite://./data/plexus.db bun run dev

Environment Variables

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

  • DATABASE_URL (Required): Database connection string.
    • 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).
  • CONFIG_FILE: Path to the plexus.yaml configuration file.
    • Default: config/plexus.yaml (relative to project root).
  • 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.
  • AUTH_JSON (Deprecated): Previously used to specify a path to OAuth credentials file. OAuth credentials are now stored in the database and managed through the Admin UI.
    • This environment variable is no longer used and will be ignored.

Example Usage

DATABASE_URL=sqlite://./data/plexus.db CONFIG_FILE=./my-config.yaml LOG_LEVEL=debug ./plexus

For configuration details, please refer to the Configuration Guide.