Skip to content
Install

Deploy from your terminal

The Orchard CLI can create and deploy an app without opening the dashboard. Use orchard up to deploy a local directory, which needs no Git repository, and run it again to ship each change. Use orchard import to turn a GitHub repository into a project and a running app with one command.

The orchard up command packs a directory, uploads it, and builds it on the cluster. The first run creates the app in the linked project. Later runs deploy the new code to the same app.

  • The Orchard CLI, installed and signed in.
  • A project linked to the directory. To link one, run orchard link --project <project>.
  • S3 storage on the instance, as described in Turn on local deploys.
orchard up

If the directory has a Dockerfile, Orchard builds it. If the directory has no Dockerfile, Railpack detects the language. To use Railpack when a Dockerfile exists, add --railpack.

The CLI always excludes .git, .orchard, and .env.orchard. It also leaves out files that look like secrets, such as .env, .env.*, .npmrc, .aws, .ssh, and *.pem, and prints what it skipped. To upload one, add a line such as !.env.build to .dockerignore. The CLI also uses .dockerignore if the file exists. Otherwise, it uses .gitignore.

The compressed directory cannot be larger than 100 MB. If you exceed the limit, the CLI returns this error:

build context exceeds 100MB; add a .dockerignore to exclude build artifacts
FlagDescription
--nameThe app name. The default is the directory name.
--rootThe directory of the app inside a monorepo.
--portThe port the app listens on. The default is the EXPOSE value, then the port the base image exposes, or 3000.
--dockerfileThe path to the Dockerfile, relative to the directory.
--output-dirA directory of built static files. The app serves them as a static site.
--detachStart the build without following its logs.
--waitBlock until the deploy is live. This is the default. To return when the build finishes, use --wait=false.

The command exits with code 9 if the build fails and code 10 if the pods crash. It also warns you if the app is live and nothing listens on its port.

For all flags, refer to the orchard up reference.

Local deploys need S3 storage, because Orchard stores each uploaded directory in a bucket that build pods can reach. The store on the server holds database backups, so builds do not use it.

To turn on local deploys, a superadmin adds S3 storage. Local deploys then turn on with no other setting.

If the instance has no S3 storage, the CLI returns this error:

Local deploys need S3 storage. Add it under Instance admin, or run: sudo orchardctl backups s3 set

To deploy without S3 storage, import a GitHub repository.

If you set storage with R2_* environment variables, also set LOCAL_DEPLOYS_ENABLED=true and R2_BUILD_CONTEXT_BUCKET. To turn local deploys off, set LOCAL_DEPLOYS_ENABLED=false.

The orchard import command creates a project named after the repository. It detects how to build the repository and starts the first build. It also attaches a protected generated URL. Auto-deploy is on when the GitHub App covers the repository.

orchard import owner/repo --wait

To select a branch, use owner/repo#branch. You can also pass a repository URL.

FlagDescription
--nameThe project and app name. The default is the repository name.
--portThe port. This overrides the detected port.
--waitBlock until the operation finishes.
  • Deploy from GitHub - Create an app from the dashboard and deploy on each push.
  • Builds - Learn how Orchard builds images and how to fix common build errors.