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

# Task & service examples

> Common patterns for database setup, preview servers, cloud auth, and more.

Copy and adapt these examples for your projects. These patterns work for both humans and agents. When an agent sees these tasks, it can use them as part of its run loop.

## Database provisioning

Start PostgreSQL and seed it with development data:

```yaml theme={null}
services:
  postgresql:
    name: PostgreSQL
    description: Development database
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: docker run --rm --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15
      ready: docker exec postgres pg_isready -U postgres
      stop: docker stop postgres

tasks:
  seed:
    name: Seed database
    triggeredBy:
      - manual
    command: ./scripts/seed-dev-db.sh
```

## Containerized services

Run services in Docker containers using `docker run` directly. This gives you full control over ports, volumes, environment variables, and container entrypoints.

> [!WARNING]
>
> Do **not** use `docker run -d` (detached mode) in a service `start` command. The `-d` flag makes `docker run` exit immediately, which causes the service to transition to Stopped. Run containers in the foreground so the process stays alive.

```yaml theme={null}
services:
  redis:
    name: Redis
    description: In-memory cache
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        if docker inspect redis >/dev/null 2>&1; then
          docker start -a redis
        else
          docker run --name redis -p 6379:6379 \
            -e REDIS_MAXMEMORY=256mb \
            -e REDIS_MAXMEMORY_POLICY=allkeys-lru \
            redis:7-alpine
        fi
      ready: docker exec redis redis-cli ping | grep -q PONG
      stop: docker stop redis

  elasticsearch:
    name: Elasticsearch
    description: Search engine
    triggeredBy:
      - manual
    commands:
      start: |
        if docker inspect elasticsearch >/dev/null 2>&1; then
          docker start -a elasticsearch
        else
          docker run --name elasticsearch -p 9200:9200 \
            -e discovery.type=single-node \
            -e xpack.security.enabled=false \
            -e ES_JAVA_OPTS="-Xms512m -Xmx512m" \
            elasticsearch:8.11.0
        fi
      ready: curl -sf http://localhost:9200/_cluster/health
      stop: docker stop elasticsearch
```

The `if docker inspect` pattern handles environment restarts — it reuses the existing container instead of failing on a name conflict.

## Prebuild optimization

Speed up environment starts by running tasks during prebuild:

```yaml theme={null}
tasks:
  install-deps:
    name: Install dependencies
    description: Install and cache all dependencies
    triggeredBy:
      - prebuild
    command: |
      npm ci
      go mod download
      pip install -r requirements.txt

  build-assets:
    name: Build static assets
    description: Compile CSS and bundle JavaScript
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: npm run build:assets

  warm-cache:
    name: Warm build cache
    description: Pre-compile common modules
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: go build -v ./...
```

> [!NOTE]
>
> Tasks with the `prebuild` trigger run during [prebuild execution](https://ona.com/docs/ona/projects/prebuilds.md). Organization and project secrets are available, but user secrets are not.

## Build and test pipeline

Chain tasks with dependencies:

```yaml theme={null}
tasks:
  build:
    name: Build
    command: yarn && yarn build

  test:
    name: Run tests
    dependsOn:
      - build
    command: yarn test

  setup:
    name: Full setup
    dependsOn:
      - build
      - test
    triggeredBy:
      - postDevcontainerStart
    command: echo "Ready to develop"
```

Agents can run `test` knowing it will build first.

## Cloud authentication

Authenticate with AWS using Ona's identity provider:

```yaml theme={null}
tasks:
  aws-auth:
    name: AWS Auth
    triggeredBy:
      - postEnvironmentStart
    command: ona idp login aws --role arn:aws:iam::123456789:role/dev-role
```

## Preview server

Serve your application for testing:

```yaml theme={null}
services:
  preview:
    name: Preview server
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        npm install
        npm run build
        npx serve -p 3000 ./build
      ready: curl -sf http://localhost:3000 > /dev/null
```

Agents can share this preview URL when demonstrating changes.

## Jupyter notebook

Start Jupyter for data science work:

```yaml theme={null}
services:
  jupyter:
    name: Jupyter Notebook
    triggeredBy:
      - manual
    commands:
      start: |
        pip install jupyter pandas numpy matplotlib
        jupyter notebook --ip=0.0.0.0 --no-browser
      ready: curl -sf http://localhost:8888 > /dev/null
```

## Storybook

Component development with hot reload:

```yaml theme={null}
services:
  storybook:
    name: Storybook
    triggeredBy:
      - manual
    commands:
      start: yarn storybook
      ready: curl -sf http://localhost:6006 > /dev/null
```

## Parallel database testing

Test against multiple database versions:

```yaml theme={null}
services:
  pg14:
    name: Postgres 14
    commands:
      start: docker run --rm --name pg14 -p 5432:5432 postgres:14
      ready: docker exec pg14 pg_isready
      stop: docker stop pg14

  pg15:
    name: Postgres 15
    commands:
      start: docker run --rm --name pg15 -p 5433:5432 postgres:15
      ready: docker exec pg15 pg_isready
      stop: docker stop pg15

tasks:
  test-compat:
    name: Compatibility tests
    triggeredBy:
      - manual
    command: |
      DATABASE_URL=postgres://localhost:5432 npm test
      DATABASE_URL=postgres://localhost:5433 npm test
```

## Troubleshooting environment

Manual task for debugging production issues:

```yaml theme={null}
tasks:
  troubleshoot:
    name: Setup troubleshooting
    triggeredBy:
      - manual
    command: |
      sudo apt-get update && sudo apt-get install -y htop iftop
      ./scripts/setup-vpn.sh
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.