App settings

Every write here changes what the next deploy renders. None of them starts a deploy on its own: call redeploy (see Deployments) when you want the change live.

Source and build

updateAppSource

Needs configure_apps. Returns App.

Change where the app is built from: another repository or branch, a different image, or a new compose file. Applied on the next deploy.

mutation {
  updateAppSource(
    id: "prj_9f1c2ab7d3e4f5a6"
    input: { source: DOCKER_IMAGE, dockerImage: "ghcr.io/acme/shop:1.4.0" }
  ) {
    id
    slug
    name
    status
    productionUrl
  }
}

updateAppBuild

Needs configure_apps. Returns App.

Save the app's build settings: method, commands, port, root directory, runtime version. Applied on the next deploy.

mutation {
  updateAppBuild(
    build: { buildMethod: "nixpacks", buildCommand: "npm run build", startCommand: "npm start", port: 3000 }
    id: "prj_9f1c2ab7d3e4f5a6"
  ) {
    id
    slug
    name
    status
    productionUrl
  }
}

buildServerChoices

Any signed-in principal. Returns [BuildServerChoice!].

The hosts this team can compile on, for an app's 'Build on' setting. Wider than the deploy-target list on purpose: a build-only server is here BECAUSE it cannot deploy, and an ordinary server is here too (one big machine can build for several small ones without giving up its own apps). Two roles are excluded: storage-only (no Docker, no build) and a migration source (it has Docker, but it is another platform's machine and a build would ship the app's source and decrypted env there). hostArch is included so the caller can disable the servers whose architecture cannot produce a runnable image for the target.

query {
  buildServerChoices {
    id
    name
    buildOnly
    hostArch
  }
}

setAppBuildServer

Needs configure_apps. Returns App.

Choose which server BUILDS this app. Null buildServerId is Automatic (a build-only server if the fleet has one this team can reach and its architecture matches, otherwise build where the app runs); passing the app's own server id means 'always build here'. buildFallback decides what happens when that host cannot compile: try the fleet's build fallbacks and then the app's own server (the default), or fail the deploy. Changing either never starts a deploy.

mutation {
  setAppBuildServer(id: "prj_9f1c2ab7d3e4f5a6", buildServerId: "srv_9f1c2ab7d3e4f5a6", buildFallback: true) {
    id
    buildServerId
    buildFallback
  }
}

clearAppBuildCache

Needs configure_apps. Returns App.

Clear this app's build cache: the next deployment builds from scratch instead of reusing cached layers, then caches again. Nothing is pruned on the server - the build cache is shared by every app on it.

mutation {
  clearAppBuildCache(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

setAppComposeUpArgs

Needs configure_apps. Returns App.

Set (or clear, with null) the extra flags appended to this app's docker compose up. Rejects anything that isn't a plain flag, and any flag that would choose the project, stack file or env-file.

mutation {
  setAppComposeUpArgs(id: "prj_9f1c2ab7d3e4f5a6", value: "--remove-orphans") {
    id
    composeUpArgs
  }
}

renderComposeStack

Any signed-in principal. Returns String.

Render the docker-compose stack an app would deploy.

mutation {
  renderComposeStack(appId: "prj_9f1c2ab7d3e4f5a6")
}

setAppAutoDeploy

Needs configure_apps. Returns App.

Turn automatic deploys on push on or off.

mutation {
  setAppAutoDeploy(id: "prj_9f1c2ab7d3e4f5a6", value: true) {
    id
    slug
    name
    status
    productionUrl
  }
}

setAppRollbackKeep

Needs configure_apps. Returns App.

How many previous deployments this app can be rolled back to (0-20, default 3). It is retention: the app's server keeps this many of its images behind the running one. Takes effect on the next sweep - lowering it removes nothing now, and raising it cannot bring back images already removed.

mutation {
  setAppRollbackKeep(count: 5, id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

Runtime

updateAppResources

Needs configure_apps. Returns App.

Save the app's per-app resource caps (RAM/CPU/PIDs/disk/...). Applied on the next deploy. A cleared field => that dimension is uncapped.

mutation {
  updateAppResources(
    id: "prj_9f1c2ab7d3e4f5a6"
    limits: { memoryMb: 512, cpuMilli: 500 }
  ) {
    id
    slug
    name
    status
    productionUrl
  }
}

updateAppHealthCheck

Needs configure_apps. Returns App.

Save the app's health check, or send no input to turn it off. Applied on the next deploy, because the block is baked into the rendered compose. Refused for a compose stack: that YAML is its author's, and a healthcheck: written there is the one that runs.

mutation {
  updateAppHealthCheck(
    id: "prj_9f1c2ab7d3e4f5a6"
    input: { type: http, path: "/healthz", port: 3000, intervalS: 10, timeoutS: 5, retries: 3, startPeriodS: 15 }
  ) {
    id
    healthCheck { type path }
  }
}

hostPortsInUse

Needs create_databases. Returns HostPortCheck.

Which of these host ports are already taken on a server - both by something listening right now and by a database that has reserved one. For a screen that has to say so before anything is created, such as the import review. checked is false when the server's agent could not answer (too old, or unreachable); the reason says which. Requires the publish-ports grant.

query {
  hostPortsInUse(serverId: "srv_9f1c2ab7d3e4f5a6", ports: [5432, 6379]) {
    checked
    inUse
    reason
  }
}

setAppPorts

Needs configure_apps. Returns App.

Replace the host ports an app publishes. Needs the publish-ports grant, and is refused for a compose stack, which publishes its own.

mutation {
  setAppPorts(id: "prj_9f1c2ab7d3e4f5a6", ports: [{ published: 8080, target: 3000, protocol: "tcp" }]) {
    id
    ports { published target protocol }
  }
}

setAppVolumes

Needs configure_apps. Returns App.

Replace an app's volumes (named, app-files, and host bind mounts). Compose-stack apps included - each volume names the service it mounts into.

mutation {
  setAppVolumes(
    id: "prj_9f1c2ab7d3e4f5a6"
    volumes: [
      { type: "named", name: "uploads", mountPath: "/app/uploads" }
      { type: "app", projectPath: "config", mountPath: "/app/config" }
    ]
  ) {
    id
    volumes { type name mountPath }
  }
}

Config files

A File storage entry mounts a file Deplo keeps for the app. These two read and write its content.

appStorageFile

Needs configure_apps. Returns AppStorageFile.

Read the file a File storage entry points at (Settings -> Storage). A path that is not there yet answers state "new" with an empty body instead of failing, so the editor can offer it as a file to write.

query {
  appStorageFile(appId: "prj_9f1c2ab7d3e4f5a6", path: "config/app.yml") {
    path
    state
    text
  }
}

writeAppFile

Needs configure_apps. Returns String.

Write the file a File storage entry points at. Answers its path.

mutation {
  writeAppFile(
    appId: "prj_9f1c2ab7d3e4f5a6"
    content: "port: 3000\n"
    path: "config/app.yml"
  )
}

See also