Skip to main content

​
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

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