CLI Commands

Docker

Deploy Cognova with Docker Compose, including PostgreSQL and Claude Code.

Cognova ships with a Dockerfile and docker-compose.yml for containerized deployment. The image is based on node:20-bookworm and includes Claude Code CLI, Python 3, and pnpm pre-installed.

Quick Start

Clone the repository and start the stack:

git clone https://github.com/Patrity/cognova.git
cd cognova

Create a .env file from the example:

cp .env.example .env

Edit .env with your values. See the Configuration reference for all available variables.

Start with the local PostgreSQL database:

docker compose --profile local up -d

Or, if using an external database (Neon, Supabase), skip the local profile:

docker compose up -d

The app will be available at http://localhost:3000.

Compose Services

`cognova` (app)

The main application container.

Setting	Value
Port	`3000:3000`
Restart	`unless-stopped`
Health check	`GET /api/health` every 30s

Volumes:

Mount	Purpose
`${VAULT_PATH:-~/vault}:/vault:rw`	Vault directory (read-write)
`claude_home:/home/node`	Persists Claude Code config and auth between restarts

`db` (PostgreSQL)

Only starts when using the local profile.

Setting	Value
Image	`postgres:16-alpine`
Port	`5432:5432`
Restart	`unless-stopped`
Health check	`pg_isready` every 5s

Data is persisted in the postgres_data named volume.

Environment Variables

The Compose file passes these to the app container. All values are documented in the Configuration reference.

environment:
  - DATABASE_URL=${DATABASE_URL:-postgres://postgres:postgres@db:5432/cognova}
  - VAULT_PATH=/vault
  - COGNOVA_API_URL=http://localhost:3000
  - COGNOVA_API_TOKEN=${COGNOVA_API_TOKEN}
  - AGENT_NAME=${AGENT_NAME:-Cognova}
  - AGENT_TONE=${AGENT_TONE:-casual}

When using the local profile, the default DATABASE_URL points to the db service (postgres://postgres:postgres@db:5432/cognova). When using an external database, set DATABASE_URL in your .env file.

Claude Code in Docker

The container comes with Claude Code CLI pre-installed. To authenticate:

Open the Cognova web UI
Navigate to the terminal
Run claude auth and follow the prompts

The claude_home named volume persists your Claude Code credentials between container restarts.

If you already have Claude Code configured on your host, you can mount your existing config by adding to docker-compose.yml:

volumes:
  - ~/.claude:/home/node/.claude
  - ~/.anthropic:/home/node/.anthropic

Entrypoint

The docker-entrypoint.sh script runs before the app starts. It syncs Claude config files (CLAUDE.md, rules, skills, hooks, settings.json) from the app source into /home/node/.claude/, ensuring updates are applied on container restart while preserving user-generated files like credentials.

Building the Image

To build locally:

docker compose build

The build sets NODE_OPTIONS=--max-old-space-size=4096 to prevent out-of-memory errors during Nuxt bundling.

Stopping

# Stop all services
docker compose --profile local down

# Stop and remove volumes (destroys data)
docker compose --profile local down -v

Upgrading

Pull the latest source and rebuild:

git pull
docker compose --profile local build
docker compose --profile local up -d

Database migrations run automatically on app startup.

CLI Commands

Overview of the Cognova CLI for managing your self-hosted installation.

Coolify

Deploy Cognova on Coolify, a self-hosted PaaS.