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:

start a local PostgreSQL instance with the repository-provided Docker Compose file
apply the current schema migrations
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

cd /root/code/aios

2. Start local PostgreSQL

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:

docker compose -f deploy/dev/docker-compose.postgres.yml logs -f postgres

3. Set AiOS runtime environment variables

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

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

go run ./cmd/aios

6. Verify the service is using external state

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/api/v1/system/info

CLI Examples

# 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

​Local PostgreSQL Development Setup

​Audience

​Goal and Scope

​Core Concepts

​Standard Workflow

​1. Enter the repository root

​2. Start local PostgreSQL

​3. Set AiOS runtime environment variables

​4. Run migrations

​5. Start the current server/bootstrap entry

​6. Verify the service is using external state

​CLI Examples

​Web UI Path

​Pitfalls / Risk Notes

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

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

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

​Related Pages