Quickstart

Run Octarq on your server or local environment using Docker Compose or single binary builds.

1. Quick Start with Docker Compose

Clone the repository and spin up the complete Octarq stack with Docker Compose:

git clone https://github.com/octarq-org/octarq.git && cd octarq
cp .env.example .env          # set OCTARQ_SECRET_KEY and OCTARQ_ADMIN_PASSWORD
docker compose up -d

Prefer a minimal image (deploy/Dockerfile.binary) or from-source build? See make release and deploy/.

2. Environment Setup

Create .env based on .env.example and customize your configuration:

OCTARQ_SECRET_KEY=your-32-byte-secret-key
OCTARQ_ADMIN_PASSWORD=your-secure-admin-password
OCTARQ_LISTEN=:8080

# Database engine: sqlite (default, zero-config) or postgres (production recommended)
OCTARQ_DB_DRIVER=sqlite
# When using postgres:
# OCTARQ_DB_DRIVER=postgres
# OCTARQ_DB_DSN=postgres://user:password@localhost:5432/octarq?sslmode=disable

• Database Options:
  • SQLite (Default): Automatically stored as octarq.db (zero external dependencies).
  • PostgreSQL: Set OCTARQ_DB_DRIVER=postgres and OCTARQ_DB_DSN for multi-instance or high-concurrency production deployments.
• Authentication: Admin account configured via OCTARQ_ADMIN_PASSWORD.

3. First Login & Dashboard Verification

Open your browser and navigate to http://localhost:8080:

1. Enter your administrator username (admin by default) and the password set in OCTARQ_ADMIN_PASSWORD.
2. Click Sign In to access the backoffice.

4. Consuming @octarq/plugin-sdk

If you are developing plugins or extensions, install @octarq/plugin-sdk directly from npm:

pnpm add @octarq/plugin-sdk