# CapRover

> Deploy Grovs on a CapRover server from the preview One Click App template, with shared object storage.

Source: https://docs.grovs.io/docs/self-hosting/platforms/caprover

[Get CapRover template](https://raw.githubusercontent.com/grovs-io/self-host/main/deploy/catalogs/caprover/grovs.yml)

## When to use

You already run CapRover. The One Click App template creates the backend, dashboard, two workers, PostgreSQL, Redis and ClickHouse.

**Preview:** the template passes local checks. Live CapRover validation and an official catalog listing are pending, so you import it manually.

## Prerequisites

| Requirement                  | Notes                                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| CapRover server              | 4 vCPU, 8 GB RAM, 80 GB SSD. To install the panel, see [CapRover's setup guide](https://caprover.com/docs/get-started.html). |
| Domains you control          | App, production links and test links                                                                                         |
| Private S3-compatible bucket | Bucket name, region, access key and secret. The API and workers read uploads from it.                                        |

## 1. Prepare DNS and proxy

Point the [Grovs DNS records](https://docs.grovs.io/docs/self-hosting/get-started/deployment#dns) at your CapRover server. Plan wildcard certificates for both link domains with DNS validation or supplied certificates; see [CapRover's certificate configuration](https://caprover.com/docs/certbot-config). Wildcard DNS alone does not provide HTTPS.

## 2. Create the app

1. Open the template with the button at the top of this page and copy its full contents.
2. In CapRover, open **Apps → One-Click Apps/Databases** and select **>> TEMPLATE <<**.
3. Paste the template and select **Next**.

This follows CapRover's [custom template import flow](https://github.com/caprover/one-click-apps#test-your-one-click-apps).

## 3. Configure environment

Choose an app name, such as `grovs`, and fill in:

| Setting                 | Example                                  |
| ----------------------- | ---------------------------------------- |
| App base domain         | `grovs.example.com`                      |
| Production links domain | `links.example.com`                      |
| Test links domain       | `test.links.example.com`                 |
| Administrator email     | Your email for the first dashboard login |
| Object storage          | Your private bucket and credentials      |

Leave the storage endpoint empty for AWS S3. For another provider, enter its S3-compatible HTTPS endpoint. Keep the generated database, OAuth, encryption and admin secrets as they are, and save them securely.

## 4. Deploy and verify

### 1. Create the services

Web waits for the databases and completes migrations and initial setup before starting the API. Workers start when web is healthy. Database services have persistent volumes and no public ports.

### 2. Attach domains

In each app's HTTP settings, use container port **3000** and attach:

| App               | Custom hosts                                                   |
| ----------------- | -------------------------------------------------------------- |
| `grovs-dashboard` | `dashboard.<app domain>`                                       |
| `grovs-web`       | `api`, `sdk`, `mcp`, `go` and `preview` under the app domain   |
| `grovs-web`       | `links.<production links domain>`, `links.<test links domain>` |
| `grovs-web`       | `*.<production links domain>`, `*.<test links domain>`         |

Replace `grovs` with your app name. Enable HTTPS for the fixed hosts, then configure wildcard host routing and certificates for both link domains.

### 3. Sign in

Read `BOOTSTRAP_ADMIN_EMAIL` and `BOOTSTRAP_ADMIN_PASSWORD` from the web app's environment and sign in at `https://dashboard.<app domain>`.

### 4. Verify

Check `https://api.<app domain>/up`, create a project, open a link, inspect its analytics and upload an image. Verify production and test link hosts over HTTPS, including the mobile association files. Check web's logs for startup or migration failures.

## Upgrades

1. Back up the databases, the bucket and the environment secrets. See [Backups](https://docs.grovs.io/docs/self-hosting/operate/backups#platforms).
2. Stop the workers.
3. Update both Grovs images to the same release.
4. Wait for web to finish migrations and become healthy.
5. Restart the workers and dashboard.

Preserve all three database volumes. Never reinstall the template over an existing deployment.

## Platform-specific gotchas

- Keep one instance of each service.
- `worker-1` holds the scheduler. Stop the existing one before starting a replacement.
- See [Troubleshooting](https://docs.grovs.io/docs/self-hosting/operate/troubleshooting) and the [template package](https://github.com/grovs-io/self-host/blob/main/deploy/catalogs/caprover/README.md).