From dfebc3a17c131f20f5c1c8880bfcc5fab8e81ff5 Mon Sep 17 00:00:00 2001 From: Kasra Bigdeli Date: Sun, 13 Sep 2026 13:48:22 -0700 Subject: [PATCH 1/2] docs: recommend image-based deployments --- README.md | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 922db34..6003e51 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,11 @@ Deploy checked-out source, a Docker image, or a prepared tar file to CapRover using an app token. -## Quick start +## Quick start (recommended) -```yaml -- uses: actions/checkout@v6 - -- uses: caprover/deploy-from-github@v2 - with: - server: https://captain.example.com - app: my-api - token: ${{ secrets.CAPROVER_APP_TOKEN }} -``` - -This packages the files committed in the checked-out `HEAD` and submits the deployment to CapRover. Generate an app token from the app's **Deployment** tab in CapRover. - -App tokens and deployment data are sent to the configured server. Use HTTPS unless the server is reached through a trusted private network. +For most deployments, build the Docker image on GitHub Actions, push it to a registry, and ask CapRover to deploy that image. -## Deploy a Docker image - -Build and push the image with the standard Docker actions, then ask CapRover to deploy it: +This keeps the expensive image build off your CapRover server, avoids consuming production CPU and memory during deployments, and lets GitHub Actions handle build caching and build logs. ```yaml - uses: actions/checkout@v6 @@ -45,6 +31,30 @@ Build and push the image with the standard Docker actions, then ask CapRover to image: ghcr.io/acme/my-api:${{ github.sha }} ``` +Generate an app token from the app's **Deployment** tab in CapRover. + +CapRover pulls the image from the registry during deployment. If the image is private, configure the registry credentials in CapRover as well. Logging the GitHub runner into the registry only grants access to the runner. + +App tokens and deployment data are sent to the configured server. Use HTTPS unless the server is reached through a trusted private network. + +## Deploy source directly + +For simple projects or quick testing, you can send the checked-out source directly to CapRover: + +```yaml +- uses: actions/checkout@v6 + +- uses: caprover/deploy-from-github@v2 + with: + server: https://captain.example.com + app: my-api + token: ${{ secrets.CAPROVER_APP_TOKEN }} +``` + +This packages the files committed in the checked-out `HEAD` and submits them to CapRover. CapRover then builds the Docker image on your server. + +For production deployments, image-based deployment is strongly recommended. Building from source on the CapRover server consumes the server's CPU, memory, disk I/O, and build cache space during every deployment. Building and pushing the image in GitHub Actions keeps those build resources off the server and gives you a reusable, immutable deployment artifact. + ## Monorepo `working-directory` packages that directory's committed contents at the root of the deployment tar: @@ -75,6 +85,8 @@ Use `tar-file` when an earlier step produces the exact deployment archive: tar-file: ./dist/deploy.tar ``` +Like direct source deployment, CapRover builds the resulting image on the server. Prefer deploying a pre-built image for production workloads when possible. + ## Inputs | Input | Required | Default | Description | From 71adc6260a66b28371413b475712483a67e46103 Mon Sep 17 00:00:00 2001 From: Kasra Bigdeli Date: Sun, 13 Sep 2026 13:52:20 -0700 Subject: [PATCH 2/2] docs: keep simple quick start first --- README.md | 46 ++++++++++++++++++---------------------------- 1 file changed, 18 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 6003e51..16cd3df 100644 --- a/README.md +++ b/README.md @@ -2,59 +2,51 @@ Deploy checked-out source, a Docker image, or a prepared tar file to CapRover using an app token. -## Quick start (recommended) - -For most deployments, build the Docker image on GitHub Actions, push it to a registry, and ask CapRover to deploy that image. - -This keeps the expensive image build off your CapRover server, avoids consuming production CPU and memory during deployments, and lets GitHub Actions handle build caching and build logs. +## Quick start ```yaml - uses: actions/checkout@v6 -- uses: docker/login-action@v3 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - -- uses: docker/build-push-action@v6 - with: - context: . - push: true - tags: ghcr.io/acme/my-api:${{ github.sha }} - - uses: caprover/deploy-from-github@v2 with: server: https://captain.example.com app: my-api token: ${{ secrets.CAPROVER_APP_TOKEN }} - image: ghcr.io/acme/my-api:${{ github.sha }} ``` -Generate an app token from the app's **Deployment** tab in CapRover. +This packages the files committed in the checked-out `HEAD` and submits the deployment to CapRover. Generate an app token from the app's **Deployment** tab in CapRover. -CapRover pulls the image from the registry during deployment. If the image is private, configure the registry credentials in CapRover as well. Logging the GitHub runner into the registry only grants access to the runner. +> **Important:** This is the simplest deployment setup, but CapRover builds the Docker image on your server. Builds can consume significant CPU, memory, disk I/O, and storage during deployment. For production workloads, we strongly recommend building the image in GitHub Actions and deploying the pre-built image instead, as shown below. App tokens and deployment data are sent to the configured server. Use HTTPS unless the server is reached through a trusted private network. -## Deploy source directly +## Deploy a Docker image -For simple projects or quick testing, you can send the checked-out source directly to CapRover: +For production deployments, this is the recommended approach. Build and push the image with the standard Docker actions, then ask CapRover to deploy it. The image build runs on GitHub Actions instead of consuming resources on your CapRover server. ```yaml - uses: actions/checkout@v6 +- uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + +- uses: docker/build-push-action@v6 + with: + context: . + push: true + tags: ghcr.io/acme/my-api:${{ github.sha }} + - uses: caprover/deploy-from-github@v2 with: server: https://captain.example.com app: my-api token: ${{ secrets.CAPROVER_APP_TOKEN }} + image: ghcr.io/acme/my-api:${{ github.sha }} ``` -This packages the files committed in the checked-out `HEAD` and submits them to CapRover. CapRover then builds the Docker image on your server. - -For production deployments, image-based deployment is strongly recommended. Building from source on the CapRover server consumes the server's CPU, memory, disk I/O, and build cache space during every deployment. Building and pushing the image in GitHub Actions keeps those build resources off the server and gives you a reusable, immutable deployment artifact. - ## Monorepo `working-directory` packages that directory's committed contents at the root of the deployment tar: @@ -85,8 +77,6 @@ Use `tar-file` when an earlier step produces the exact deployment archive: tar-file: ./dist/deploy.tar ``` -Like direct source deployment, CapRover builds the resulting image on the server. Prefer deploying a pre-built image for production workloads when possible. - ## Inputs | Input | Required | Default | Description |