> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local PostgreSQL Development Setup

> Start PostgreSQL with Docker Compose, run migrations, and launch AiOS against external state in local development.

# Local PostgreSQL Development Setup

## Audience

This page is for maintainers and developers who need a local AiOS control-plane workflow backed by external state rather than in-process stubs.

## Goal and Scope

This page explains how to:

1. start a local PostgreSQL instance with the repository-provided Docker Compose file
2. apply the current schema migrations
3. launch `go run ./cmd/aios` with PostgreSQL-backed module wiring

## Core Concepts

* the repository's real external state path is PostgreSQL, not SQLite
* `cmd/aios` now requires `postgres.dsn` in `dev` mode and no longer silently falls back to in-memory repositories
* `make migrate-up` and `make migrate-down` wrap the `golang-migrate` `migrate` CLI

## Standard Workflow

### 1. Enter the repository root

```bash theme={null}
cd /root/code/aios
```

### 2. Start local PostgreSQL

```bash theme={null}
docker compose -f deploy/dev/docker-compose.postgres.yml up -d
docker compose -f deploy/dev/docker-compose.postgres.yml ps
```

To watch database health:

```bash theme={null}
docker compose -f deploy/dev/docker-compose.postgres.yml logs -f postgres
```

### 3. Set AiOS runtime environment variables

```bash theme={null}
export AIOS_RUNTIME__MODE=dev
export AIOS_DEV_COMPOSE_PROJECT=aios-dev
export AIOS_DEV_POSTGRES_PORT=5432
export AIOS_POSTGRES__DSN="postgres://aios:aios@localhost:${AIOS_DEV_POSTGRES_PORT}/aios?sslmode=disable"
export DATABASE_URL="$AIOS_POSTGRES__DSN"
```

Notes:

* `AIOS_RUNTIME__MODE=dev` keeps the current local-development runtime semantics
* `dev` now requires PostgreSQL to be available; only `bootstrap` may start without a DSN
* `AIOS_DEV_COMPOSE_PROJECT` isolates Compose resource names across worktrees or developers
* `AIOS_DEV_POSTGRES_PORT` lets you avoid an existing local `5432`
* `AIOS_POSTGRES__DSN` overrides `postgres.dsn`
* `DATABASE_URL` is consumed by the migration command

### 4. Run migrations

```bash theme={null}
make migrate-up
```

If `migrate` is not installed on your machine yet, install `golang-migrate` first because the current `Makefile` calls it directly.

### 5. Start the current server/bootstrap entry

```bash theme={null}
go run ./cmd/aios
```

### 6. Verify the service is using external state

```bash theme={null}
curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/api/v1/system/info
```

## CLI Examples

```bash theme={null}
# Start local PostgreSQL
docker compose -f deploy/dev/docker-compose.postgres.yml up -d

# Apply migrations
export AIOS_RUNTIME__MODE=dev
export AIOS_DEV_COMPOSE_PROJECT=aios-dev
export AIOS_DEV_POSTGRES_PORT=5432
export AIOS_POSTGRES__DSN="postgres://aios:aios@localhost:${AIOS_DEV_POSTGRES_PORT}/aios?sslmode=disable"
export DATABASE_URL="$AIOS_POSTGRES__DSN"
make migrate-up

# Start the control plane
go run ./cmd/aios

# Stop local PostgreSQL
docker compose -f deploy/dev/docker-compose.postgres.yml down
```

## Web UI Path

This page is about local control-plane development and does not map to a single product UI screen. Once the service is running, you can open the web frontend or call the frozen HTTP APIs directly.

## Pitfalls / Risk Notes

### 1. Running only `go run ./cmd/aios` without a DSN

In that case, `dev` mode now fails fast. Only `bootstrap` may start without a DSN, and that path still exists only as a temporary stub rather than an external-state development loop.

### 2. `make migrate-up` fails with `migrate: command not found`

That means `golang-migrate` is missing from your PATH. Install it first, then rerun the migration step.

### 3. PostgreSQL is up but the app still cannot connect

Check:

* `AIOS_POSTGRES__DSN`
* whether `AIOS_DEV_POSTGRES_PORT` matches the port in the DSN
* whether `AIOS_DEV_COMPOSE_PROJECT` points to the same Compose resource set you started
* whether the container health check has passed

## Related Pages

* [Start Here](/en/getting-started/index)
* [First Agent Command](/en/getting-started/first-agent-command)
* [Configuration Reference](/en/platform/config-reference)