Installation

Choose your setup

Docker combines the built web UI and gateway in one container and runs PostgreSQL alongside it. Source development runs the Vite UI and gateway separately and is useful when contributing to OwnPilot.

The product requires Node.js 22+, pnpm 10+ and PostgreSQL 16+ for source development. These product requirements are separate from the versions used to build this website.

Docker installation

Copy .env.example, set POSTGRES_PASSWORD to a strong value, then build and start the postgres profile. Visit http://localhost:8080.

git clone https://github.com/ownpilot/OwnPilot.git ownpilot
cd ownpilot
cp .env.example .env
# Set a strong POSTGRES_PASSWORD in .env before starting.
docker compose --profile postgres up -d --build

Develop from source

Install the product prerequisites. Start only the postgres service for source development; the gateway will run through pnpm dev. Update POSTGRES_PASSWORD in .env first.

git clone https://github.com/ownpilot/OwnPilot.git ownpilot
cd ownpilot
cp .env.example .env
# Set a strong POSTGRES_PASSWORD in .env.
pnpm install
docker compose --profile postgres up -d postgres
pnpm dev

Check your services

The development web UI is at http://localhost:8199. The gateway is at http://localhost:8080. The Compose database is mapped to 127.0.0.1:25432 on the host. The UI development server proxies API and WebSocket requests to the gateway.

docker compose --profile postgres ps
docker compose --profile postgres logs --tail=100 gateway

Troubleshooting

If the database is unhealthy, check that .env exists and POSTGRES_PASSWORD is set. If a port is already in use, review the product’s PORT and UI_PORT settings. On Windows, use 127.0.0.1 for the host database connection to avoid IPv4/IPv6 localhost differences.

A failed model request usually needs a provider configuration or model-capability check in Config Center. Keep credentials out of public issues and redact logs before sharing them.