> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Deploy an app > Deploy uploaded files as the app. Open an upload and send the files to it first, and deploy once it has SUCCEEDED. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml post /apps/{id}/deploys openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: FeatureFlags - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: AwsAmp - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: Integrations - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: EksPrometheus - name: EksLoki - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleCategories - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: GitHub Actions - name: Alerts - name: Gitlab - name: Slack - name: Git - name: MergeQueues - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Domains - name: AcmCertificates - name: NotificationDestinations - name: NotificationDispatches - name: NotificationEvents - name: NotificationRules - name: Activity - name: Describe - name: Reports - name: BillingPlans - name: BillingAccounts - name: BillingCycles - name: BillingUsageSummaries - name: BillingAddOns - name: BillingInvoices - name: Authorization - name: Sandboxes - name: SandboxCommands - name: SandboxPorts - name: Apps paths: /apps/{id}/deploys: post: tags: - Apps summary: Deploy an app description: >- Deploy uploaded files as the app. Open an upload and send the files to it first, and deploy once it has `SUCCEEDED`. Returns 201 with the pipeline run that carries out the deploy: read it for the deploy's status and its steps' logs, and the app for its URLs. The run cancels a deploy of the same app that is still in progress and waits for it to stop. It then moves the upload into place, builds and starts the app in its sandbox as the definition says, resuming a paused sandbox without running its old start commands, and serves every exposed port at its URL once the port answers its health check. A deploy of an app that exposes no port is ready once its start commands have succeeded. The run fails, running nothing, when the app's sandbox no longer holds the upload or did not unpack it whole from the archive `archiveSha256` names. Each domain of the app's own that an exposed port lists is claimed for the app when the run serves its ports: its certificate is requested and attached to the App Cluster's load balancer, and the app's `domains` give the DNS records to add. A domain the definition no longer lists is released, and its certificate with it. Fails with 422 when the definition is invalid, when it asks for more than the App Cluster allows, when a module reference in its environment variables does not resolve in the App Cluster's environment, when a domain is under Ravion's domain or one of the App Cluster's domains (`DOMAIN_NOT_ALLOWED`), or when the App Cluster's load balancer holds no more certificates (`CERTIFICATE_LIMIT`); with 409 when another app or service has a domain (`DOMAIN_TAKEN`), and while the app is being deleted. operationId: DeployApp parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/AppDeployRequest' required: - data type: object required: true responses: '201': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/AppDeployStarted' required: - data type: object description: >- The request has succeeded and a new resource has been created as a result. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '404': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The server cannot find the requested resource. '409': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request conflicts with the current state of the server. '422': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Client error '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error components: schemas: AppDeployRequest: additionalProperties: false description: What a deploy of an app deploys. properties: archiveSha256: description: >- SHA-256, in lower-case hex, of the archive the files were sent as: the `archiveSha256` the upload was opened with. The deploy takes the files only when the app's sandbox unpacked them whole from that archive. pattern: ^[0-9a-f]{64}$ type: string branch: description: >- Branch the uploaded files were taken from. Leave it out when they were not on a branch. type: string commit: description: >- Commit the uploaded files were taken from. Leave it out for files that were not taken from a git commit. type: string definition: allOf: - $ref: '#/components/schemas/App.AppDefinition' description: >- The app's definition, as `ravion deploy` reads it from `ravion-app.yaml`. Its sizes and idle timeout default to the App Cluster's defaults and may not exceed its limits. A value of `env` may reference an output of a module in the App Cluster's environment as `<< modules..output. >>`; references are resolved when the deploy is requested, and the values are kept with the deploy, so a wake never brings the app back with different ones. dirty: description: >- True when the uploaded files had changes that were not committed. Default false. type: boolean env: description: >- Environment variables set for this deploy on top of the definition's, such as secrets that are not committed with `ravion-app.yaml`. A name set in both takes this value. Values are kept with the app's sandbox and never returned. items: $ref: '#/components/schemas/App.AppVariable' type: array uploadId: description: >- The upload that holds the files to deploy, as opening it answered. Lower-case letters, digits and hyphens, starting with a letter or a digit, at most 64 characters. pattern: ^[a-z0-9][a-z0-9-]{0,63}$ type: string required: - uploadId - archiveSha256 - definition type: object AppDeployStarted: additionalProperties: false description: The deploy that was started. properties: pipelineRunId: description: >- Pipeline run (`prun_*`) that carries out the deploy. Read it for the deploy's status and its steps' logs. type: string required: - pipelineRunId type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object App.AppDefinition: additionalProperties: false description: >- An app's definition, as `ravion deploy` sends it: `ravion-app.yaml` with its shorthands expanded and every port known. properties: compose: allOf: - $ref: '#/components/schemas/App.AppCompose' description: The Docker Compose project. Set when `kind` is `compose`. x-templateable: true cpu: description: vCPUs. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: CPU x-templateable: true description: description: >- What the app is, from `description` in `ravion-app.yaml`. Shown on the app's overview. maxLength: 500 type: string x-templateable: true diskGib: description: Disk in GiB. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: DiskGiB x-templateable: true env: description: Environment variables, in order. May be empty. items: $ref: '#/components/schemas/App.AppVariable' type: array x-templateable: true expose: description: >- HTTP ports served at the app's URLs, in order. Empty for an app that serves no port. items: $ref: '#/components/schemas/App.AppExposure' type: array x-templateable: true idleTimeoutSeconds: description: >- Seconds without a request or a running command before the app is paused: 0 never pauses it, otherwise at least 60. Defaults to the cluster's default. format: int32 minimum: 0 type: integer x-templateable: true kind: allOf: - $ref: '#/components/schemas/App.AppKind' description: Whether `compose` or `run` builds and starts the app. x-templateable: true memoryMib: description: Memory in MiB. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: MemoryMiB x-templateable: true run: allOf: - $ref: '#/components/schemas/App.AppRun' description: The build and start commands. Set when `kind` is `run`. x-templateable: true workdir: description: >- Folder that holds `ravion-app.yaml`, relative to the root of the uploaded files, or `.` for the root. Commands run in it. minLength: 1 type: string x-templateable: true required: - kind - workdir - expose - env type: object x-go-type: app.Definition x-go-type-import: name: app path: ravion/schemas/app App.AppVariable: additionalProperties: false description: An environment variable. properties: name: description: Variable name. Names starting with `RAVION_` are reserved. pattern: ^[A-Za-z_][A-Za-z0-9_]*$ type: string x-templateable: true value: description: Plain text, including multiline text. type: string x-templateable: true required: - name - value type: object x-go-type: app.Variable x-go-type-import: name: app path: ravion/schemas/app Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object App.AppCompose: additionalProperties: false description: A Docker Compose project Ravion builds and starts. properties: file: description: Compose file, relative to the app's folder. minLength: 1 type: string x-templateable: true profiles: description: Compose profiles to enable. May be empty. items: type: string type: array x-templateable: true services: description: >- Services to build and start. Empty builds and starts every service the enabled profiles include. items: type: string type: array x-templateable: true required: - file - profiles - services type: object x-go-type: app.Compose x-go-type-import: name: app path: ravion/schemas/app App.AppExposure: additionalProperties: false description: >- An HTTP port an app serves. The first exposure is served at the app's primary URL. properties: domains: description: >- Domains of your own the port is also served at, in order. An app has at most 10 domains across its exposures, no two exposures list the same domain, and at least one of the app's domains is at most 64 characters long, to name its certificate. Absent or empty for a port served only at the App Cluster's domains. items: $ref: '#/components/schemas/App.AppDomainName' maxItems: 10 type: array x-go-type-skip-optional-pointer: true x-templateable: true healthCheckPath: description: HTTP path requested to tell whether the port is ready. pattern: ^/ type: string x-templateable: true name: description: >- 1 to 20 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row, unique within the app. maxLength: 20 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ type: string x-templateable: true port: description: Port inside the app. format: int32 maximum: 65535 minimum: 1 type: integer x-templateable: true required: - name - port - healthCheckPath type: object x-go-type: app.Exposure x-go-type-import: name: app path: ravion/schemas/app App.AppKind: description: How an app is built and started. enum: - compose - run type: string x-go-type: app.Kind x-go-type-import: name: app path: ravion/schemas/app App.AppRun: additionalProperties: false description: An app's own build and start commands. properties: build: description: Commands run in order on every deploy, before `start`. May be empty. items: type: string type: array x-templateable: true start: description: >- Commands run in order on every deploy, after `build`, and every time the app wakes. items: type: string minItems: 1 type: array x-templateable: true required: - build - start type: object x-go-type: app.Run x-go-type-import: name: app path: ravion/schemas/app App.AppDomainName: description: >- A domain name in a DNS zone you control, such as `shop.example.com`: two or more lowercase labels of letters, digits and hyphens, with no `*.` and no trailing dot. maxLength: 253 pattern: >- ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ type: string securitySchemes: BearerAuth: scheme: Bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.