# Ravion project config workflow Reference file for the [`use-ravion` skill](https://www.ravion.com/SKILL.md). Read it before creating or changing any infrastructure. A project config file (`.yaml`, `.jsonc`, or `.cue`) declares environments and their module instances. It is the way to create and change infrastructure. Follow this sequence every time. ```bash ravion project config schema # 1. field-level schema for the file ravion module definition list # 2. available module types ravion module schema [version] # 3. inputs for each module you touch ravion project config apply --file ravion.yaml --dry-run # 4. preview ravion project config apply --file ravion.yaml # 5. apply ``` Generate the file with the CLI so it carries the current header, comments, and links — never hand-write it from memory: ```bash ravion project create --given-id --name "" --file ravion.yaml # new project ravion project config pull --file ravion.yaml # existing project ``` Both need a session. Without one, do not wait: draft the file from `ravion project config schema` (public) plus each module's catalog page at `https://www.ravion.com/docs/module-definitions/catalog/.md`, show the user the draft, and ask them to sign up or sign in. Once they have, run the generating command above and fold your draft into the file it writes, then re-check every input against `ravion module schema ` — a drafted file is a starting point, never what you apply. ## Module set List definitions with `ravion module definition list`, then read the input schema of every module you touch with `ravion module schema [version]`. Both need a session; while drafting without one, use the [module catalog](https://www.ravion.com/docs/module-definitions/catalog) pages, then confirm against `ravion module schema` before applying. A typical containerized web app is `rvn-aws-network` → `rvn-ecs-cluster` → `rvn-ecs-web`; a static site is `rvn-aws-static`. Add `rvn-rds` or `rvn-aurora` for Postgres/MySQL, `rvn-elasticache` for Redis, `rvn-s3` for buckets, `rvn-lambda` for functions, `rvn-ecs-worker` for background workers. Full list: [module catalog](https://www.ravion.com/docs/module-definitions/catalog). ## File shape Every environment the user talks about (`production`, `staging`, `preview`) is its own entry under `environments`, and `--environment-given-id staging` targets one of them. Modules wire together by `moduleGivenIdRef` — `{moduleGivenIdRef: "module"}` in the same environment, `"environment.module"` across environments, `"project.environment.module"` across projects. A database module takes `network: {moduleGivenIdRef: network}`, the same network the cluster uses. The service does **not** get a typed reference to it: `rvn-ecs-web` reads database credentials through runtime `secrets` (`{name, value_from}` pointing at Secrets Manager or SSM), so create the secret from the database outputs and pass it there. Read `ravion module schema rvn-rds` and `ravion module schema rvn-ecs-web` before wiring either side. ```yaml project: givenId: demo name: Demo environments: - givenId: production name: Production moduleInstances: - givenId: network name: Network type: rvn-aws-network version: 1.0.0 input: aws_account_id: ravion-prod aws_region: us-east-1 name: demo-production - givenId: cluster name: ECS cluster type: rvn-ecs-cluster version: 1.0.0 input: network: moduleGivenIdRef: network name: demo-production - givenId: web name: Web service type: rvn-ecs-web version: 1.0.0 input: cluster: moduleGivenIdRef: cluster name: demo-production-web build_source: railpack source_repo: my-org/my-repo container_port: 3000 - givenId: staging name: Staging moduleInstances: [] # same module shape as production, usually smaller sizes ``` Adding a database to an existing environment means adding a module instance to that environment's list, then applying scoped to it: `--environment-given-id staging --module-given-id database`. Changing one existing module (a version bump, an input) is the same loop: `config pull`, edit that module's entry, `config apply --module-instance-id ` — the `minst_` ID is in the dashboard URL the user pasted. ## Approval rules Creating new infrastructure can go straight through with `--autoapprove`, scoped to what you are creating so an unrelated change cannot ride along: ```bash ravion project config apply --file ravion.yaml --autoapprove \ --environment-given-id --module-given-id ``` Omit `--autoapprove` when the change modifies, replaces, or removes existing infrastructure, so a human reviews each Terraform plan first. Removing a module instance plans a destroy and waits for manual approval. Pass `--description ""` to label every stack run the apply creates. Narrow the target with `--environment-given-id`, `--module-given-id`, `--environment-id`, or `--module-instance-id`. ## Follow the stack runs Every apply prints a `PIPELINE_RUN_ID` per stack run it started, in dependency order, plus the exact wait command. Use `wait --watch`, never a polling loop: ```bash # Without --autoapprove: wait for the gate, read the plan, approve, wait for the apply ravion pipeline run wait --until PENDING_APPROVAL --watch ravion pipeline run get-plan ravion pipeline run approve ravion pipeline run wait --watch # With --autoapprove ravion pipeline run wait --watch --timeout 30m ravion pipeline run get-apply ``` A non-zero exit from `wait` means the run failed, was cancelled, or was rolled back. Read the plan and the step logs before retrying — see [operations](https://www.ravion.com/skills/use-ravion/operations.md). Full reference: [project config file](https://www.ravion.com/docs/config-as-code/project-config-file). Compact machine-readable schema: `https://api.ravion.com/projects/config/schema.md`.