Deploy your first app
This guide takes a GitHub repository from code to a running app on your Orchard instance. You connect GitHub, deploy the repository, create a Postgres database, and connect the database to the app. At the end, your app runs on an HTTPS URL and reads its database connection string from a variable.
You can follow each step in the dashboard or with the orchard CLI.
Prerequisites
Section titled “Prerequisites”- A running Orchard instance that you can sign in to. To set one up, refer to Install.
- A GitHub repository that contains a Dockerfile, or an app that Orchard can detect and build without one.
- For private repositories, a GitHub App on the instance. To create one, refer to Connect a GitHub App.
- For the CLI steps, the
orchardCLI. To install it, refer to Use the CLI.
1. Connect GitHub
Section titled “1. Connect GitHub”Orchard needs access to your GitHub account to list your repositories and to deploy again on each push. For a public repository, you can skip this step.
- Open your account menu.
- Select Account settings > Connections.
- In GitHub, select Connect.
- Approve the request on GitHub.
- In Repository access, select Add account.
- Install the GitHub App on the account that owns your repository.
-
Sign in to your instance:
orchard auth login --api-url https://orchard.example.com -
Link your GitHub account:
orchard github link --open -
Install the GitHub App on the account that owns your repository:
orchard github install --open
2. Deploy the app
Section titled “2. Deploy the app”Orchard clones the repository, builds an image on your cluster, and starts the app.
- Open a project.
- Select New app.
- In Start from scratch, select GitHub repo.
- In Repository, select your repository. For a public repository, paste
owner/repointo the search field. - In Branch, select a branch.
- In Name, enter a name for the app.
- In Networking, confirm that the port matches the port your app listens on.
- In Reach, select Public link for a URL that anyone can open. The default, Private link, requires people to sign in to Orchard.
- Select Deploy.
Orchard opens a progress page with these steps: Starting the builder, Cloning the repo, Building the image, Pushing the image, and Rolling out. The build logs stream on the same page.
-
In your project directory, link the directory to an Orchard project:
orchard link -
Create the app and wait for the first build:
orchard deploy create --github owner/repo#main --name web --port 3000 --wait
The CLI generates a URL that requires people to sign in to Orchard. To make the URL public, refer to Protect an app.
The app is live when its status is Running. Its URL appears in the header of the app page. A new URL can show a certificate warning for up to a minute, until its certificate is issued.
If the build fails, refer to Builds.
3. Create a database
Section titled “3. Create a database”A managed database is a Postgres instance with its own backups. It has its own lifecycle, separate from any app that connects to it, so a redeploy of the app does not change it.
- Open the project.
- Select New app.
- In Start from scratch, select Postgres.
- In Database name, enter a name.
- Select Create database.
orchard db create --name appdb --wait4. Connect the database to the app
Section titled “4. Connect the database to the app”Connect the database with a reference instead of a copied connection string. A reference follows the database through a password rotation or a restore, so the app keeps working without an edit.
- Open the app.
- Go to Variables.
- Add a variable named
DATABASE_URL. - In the value field, select Use a resource.
- Select your database.
- Select Save.
orchard deploy bindings add <app-id> --database appdbThis command adds DATABASE_URL to the app.
Orchard restarts the app with the new variable.
Next steps
Section titled “Next steps”At this point, your app runs on an HTTPS URL with a Postgres database behind it. To put it on your own domain, add a custom domain. To deploy on every push, set up auto-deploy.
Related resources
Section titled “Related resources”- Set variables - Set variables for one app, or share them across an environment.
- Roll back an app - Go back to an earlier build, and restore bound databases with it.
- Deploy from your terminal - Deploy a local folder with
orchard up, without a repository. - Read logs and open a shell - Search the logs of an app and open a shell in a running container.