Skip to main content
The oxy start command is the recommended way to run Oxy with a production-ready PostgreSQL database. It automatically manages a PostgreSQL container using a Docker-compatible container runtime and starts the Oxy web server.

​
Prerequisites

Container Runtime Required: oxy start needs a Docker API-compatible container runtime (e.g., Docker Engine, Podman with Docker socket).You can use:
  • Docker Engine (standalone, no GUI needed)
  • Docker Desktop, Rancher Desktop, Colima, OrbStack, or Podman
  • Any runtime that provides a Docker API
See the Container Runtime Setup Guide for installation instructions.

​
Overview

oxy start simplifies database setup by:
  1. Checking container runtime availability - Verifies Docker API is accessible
  2. Starting PostgreSQL in a container (or using existing one)
  3. Waiting for PostgreSQL to be ready
  4. Configuring the database connection automatically
  5. (Optional) Starting ClickHouse + OTel Collector with --enterprise flag

​
Quick Usage

oxy start                    # start DB + web server
oxy start --enterprise       # also start ClickHouse + OTel
oxy start --clean            # clean existing containers/volumes first
oxy start --clean --enterprise  # clean + start with enterprise features

​
Key Ports

ServiceHost Port
PostgreSQL (oxy-postgres)15432
ClickHouse (oxy-clickhouse) HTTP / Native8123 / 9000
OTel Collector (oxy-otel-collector) gRPC / HTTP4317 / 4318
Cube.js Semantic Engine (oxy-cubejs)4000

​
Clean option

The --clean flag removes all existing Oxy-managed Docker resources before starting: Standard mode (oxy start --clean):
  • Removes oxy-postgres container
  • Removes oxy-postgres-data volume (⚠️ all data lost)
Enterprise mode (oxy start --clean --enterprise):
  • Removes oxy-postgres, oxy-clickhouse, oxy-otel-collector containers
  • Removes oxy-postgres-data and oxy-clickhouse-data volumes (⚠️ all data lost)
  • Removes the oxy-enterprise-network Docker network
Use cases:
  • Troubleshooting database issues
  • Resetting to a fresh state for development
  • Clearing corrupted data
  • Starting with a clean slate after schema changes
⚠️ Warning: The --clean option permanently deletes all data in the database volumes. Make sure you have backups of any important data before using this option.

​
Environment vars (enterprise)

  • OXY_CLICKHOUSE_URL = http://localhost:8123
  • OXY_CLICKHOUSE_DATABASE = otel
  • OTEL_EXPORTER_OTLP_ENDPOINT = http://localhost:4317

​
Minimal commands

  • Check status: oxy status
  • View logs: docker logs -f oxy-postgres (and oxy-clickhouse, oxy-otel-collector for enterprise)
  • Stop containers: docker stop oxy-postgres [oxy-clickhouse oxy-otel-collector]
  • Clean restart: oxy start --clean (removes all containers and volumes)

​
Command-Line Options

​
--clean
boolean
default:"false"
Remove all existing Oxy-managed containers and volumes before starting.⚠️ Warning: This permanently deletes all database data.
​
--enterprise
boolean
default:"false"
Enable enterprise features including ClickHouse, OpenTelemetry Collector, and Cube.js semantic engine.

​
Important Notes

Container Runtime Required: A Docker-compatible container engine must be installed and running. See Container Runtime Setup for options.
  • Data persists in named volumes (oxy-postgres-data, oxy-clickhouse-data)
  • Use --clean to remove existing containers and volumes for a fresh start (⚠️ data loss)
  • If a port is already in use, stop the conflicting service or configure external databases

​
Troubleshooting

Ensure your container runtime is installed and running:
# Verify Docker CLI works
docker ps

# If using a custom socket, set DOCKER_HOST
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
oxy start
See the Container Runtime Guide for detailed setup instructions.
If PostgreSQL port 15432 is in use:
  1. Check what’s using the port: lsof -i :15432
  2. Stop the conflicting service
  3. Or configure Oxy to use an external database instead
The container may still be initializing:
# Check container logs
docker logs -f oxy-postgres

# Wait for "ready to accept connections" message

​
Next Steps

Container Runtime Setup

Install and configure Docker Engine, Colima, or other runtimes

Production Deployment

Deploy Oxy in production environments

Database Sync

Learn about database migrations and syncing

Monitor Status

Check Oxy service status