CapRover one-click apps and the YAML that turns a Docker Compose file into a form

A catalogue of templates, not a piece of software

The repository is the CapRover One Click Apps catalogue, a community maintained set of deployment templates for CapRover, which is the platform itself at github.com/caprover/caprover.

What a one-click app is, in practice, is a Docker Compose file with one extra section. The README says to look at a simple example first, the privatebin.yml file in the public/v4/apps directory, and then describes the format as of v1.8.0.

The process for creating one is three steps. Find or create a docker-compose file for the app you are interested in. Add captainVersion: 4 to the very top of the yaml file. Then add a section to the end of the file, which is where the metadata that turns a Compose file into a form lives.

The metadata block looks like this:

caproverOneClickApp:
    variables:
        - id: '$$cap_myapp_version'
          label: Awesome App Version
          defaultValue: '1.2.3'
          description: Check out their Docker page for the valid tags https://hub.docker.com/r/....../tags
          validRegex: '/.{1,}/'
    instructions:
        start: |-
            A description that will be displayed to the user when they
            are installing one click app!
            It can be multiline and contain more details and probably special
            hardware requirements!
        end: |-
            A summary when the app is deployed!
            It can be multiline.

            It can also include the dynamic parameters such as
            $$cap_appname and $$cap_other_random_char
    displayName: The Awesome App
    isOfficial: true ## Only if all images used here are official or from a trusted source.
    description: A relatively short description, less than 200 characters.
    documentation: This docker-compose is taken from example.com

That is the whole authoring format. The instructions block has a start and an end, and both accept free text that can carry the dynamic parameters. The description field has a stated limit of less than 200 characters, and isOfficial is only set when all the images used are official or from a trusted source, which is a claim the contributor has to be able to stand behind.

$$cap variables are substituted anywhere in the file

The variable mechanism is the part that makes a template reusable, and the rules are specific enough that they are worth reading twice.

Variables are prefixed with $$cap, they can be anywhere in the content, and they will be replaced by what the user enters. There are three special variables built in for all one-click apps: $$cap_appname, $$cap_root_domain and $$cap_gen_random_hex(length). The README gives the composite case, where an app needs an environment variable holding the URL of the app, you can use $$cap_appname.$$cap_root_domain, which resolves to something like myappname.rootdomain.com. And for a default password you can use $$cap_gen_random_hex(10).

So the same template can produce a different deployment per user, with the app name, the domain and a generated secret filled in, without the template author knowing anything about the target instance.

Each custom variable must have an id and a label, and can also have a defaultValue, a validRegex and a description. The id doubles as the placeholder name in the Compose file, which is why it carries the $$cap prefix in the example rather than a plain name.

There is one behaviour that catches contributors out, and the README flags it as IMPORTANT. By default, fields are not required to be filled, and if validRegex is not set the field can be set as empty and ignored by the user. So a template whose image tag comes from a variable is not guaranteed to get a value, and a validRegex is what turns a field into a required one in practice.

Only eight Compose parameters are actually parsed

This is the constraint that decides whether a given application can be a one-click app at all.

The format used by one-click apps is Docker Compose, but the README is explicit that not all parameters defined in a Docker Compose file are parsed out by CapRover. Only the following are used: image, environment, ports, volumes, depends_on, hostname, command and cap_add. Other parameters are currently being ignored by CapRover, and if you need a particular parameter, the instruction is to file an issue and it will be added to the respected list.

That is a small list for a Compose file, and it excludes most of what people reach for. No networks beyond the default, no deploy settings, no resource limits, no healthcheck, no logging configuration, no secrets, no build. A container image that relies on any of those is not expressible as a one-click app template.

Alongside the Compose keys there is a CapRover-specific subsection called caproverExtra, which holds service specific parameters available only via CapRover and not through Docker Compose. The README lists what it can take.

dockerfileLines is a multiline variable that can be used instead of the image property in the service, and you must delete the image property if you want to use it. The README is cautious about it: it should be used in rare cases where other methods cannot work, and command is preferred where possible. containerHttpPort is useful when the underlying service uses a custom port for HTTP, and if it is not provided the default is "80". notExposeAsWebApp can be set to "true" when the underlying service is not an HTTP app, which is the case for databases and other internally used services. And websocketSupport can be set to "true" to automatically enable Websocket Support, only supported in versions 1.12 and later.

The notExposeAsWebApp flag is the one that makes the catalogue useful for databases rather than only for web applications, and websocketSupport is what lets a template cover a realtime service without extra manual configuration in the CapRover dashboard.

Testing a template happens in the CapRover dashboard

The README asks contributors to test before opening a pull request, and the procedure is a manual one through the CapRover user interface.

Log in to your CapRover dashboard, go to apps, and click on One-Click Apps/Databases. At the bottom of the dropdown list, select the option marked >> TEMPLATE <<. Then copy and paste your YAML into the text area and click NEXT, enter values, and make sure it is working as expected.

The TEMPLATE entry is the part that is not obvious from a description. It is how you exercise a template that is not yet in the catalogue, without publishing it, and it is the only way to see the form that a user will actually fill in, with your variable ids, labels, defaults and validation regex rendered by the interface.

There is also a required step for the template itself. The README says to make sure you add an app icon to the logos directory, which is what the catalogue uses for the entry to look like an app rather than a raw YAML file.

So the contributor loop is: write the Compose file and the metadata block, add an icon, paste it into the dashboard as a template, fill in the form, deploy it, and only then open the pull request. The automated check comes afterwards, in the build pipeline, and the README describes a separate npm run validate_apps step for that.

Building your own repository is four npm commands

The repository documents how to run a private catalogue, which is the more interesting use of the format for an organisation that does not want to send its templates to a public list.

CapRover supports having multiple repositories, and you add new repository URLs on the one click app page. The official one, this repository, is available as https://oneclickapps.caprover.com.

To create your own, the steps are to fork the repository, delete all existing apps to avoid duplicate apps and add your own, then run the four commands. The scripts in the package manifest spell out what they do:

The four commands are `npm ci`, `npm run validate_apps`, `npm run formatter-write` and `npm run build`.

The build script is worth reading because it shows the shape of the output. It removes the dist directory, recreates it, and then runs two separate build scripts, one for the older template set and one for v4, which is how the catalogue supports both formats at once. The output in ./dist is static content, and you host it with any static file server.

The package manifest also shows the shape of the tooling. The dependencies are fs-extra, prettier and yaml, which is the minimum for a project that reads YAML files, writes formatted YAML and copies directories around. The scripts include a formatter that checks formatting and a formatter-write that applies it, both scoped to the json and yml files under public, so the catalogue is kept in a canonical format automatically.

One inconsistency is worth flagging if you are reading the licences. The project metadata for the repository records Apache-2.0, while the license field in the package manifest says ISC. The LICENSE file at the repository root is the document to read if this matters to you, and it is a good example of why the two values should be checked rather than assumed.

Three ways to publish a private catalogue

There are three publishing routes in the README, and they differ in how much infrastructure they assume.

The first is GitHub Pages, using the workflow included in the repository, which validates, builds and publishes when changes are pushed to master. The setup is to enable GitHub Actions on the fork, then go to Settings, then Pages, and under Build and deployment set Source to GitHub Actions. A custom domain is configured in the same place, with the required DNS records added at the domain provider. There is a detail here: the GitHub Actions publishing workflow ignores public/CNAME, so a CNAME file in the repository will not do what you expect.

The default repository URL is https://<owner>.github.io/one-click-apps, and the README notes that no personal access token is required.

The second route is to host the repository on a CapRover instance itself, using the newly added captain-definition file. You follow the same steps to create your own repository, and the note about updating your fork from the upstream master branch matters if captain-definition is missing from your root directory. Then in the CapRover dashboard you go to apps, under Create A New App you name it something relevant such as caprover-apps, you leave the Has Persistent Data checkbox unchecked, and you click Create New App. In the new app you go to Deployment, scroll down to Method 3: Deploy from Github/Bitbucket/Gitlab, put the Git url for your forked repository and the other requested data, click Save and Update, and then Force Build. The alternative within that method is to make a tarball of the contents of the one-click-apps repo, a .tar file, and upload it under Method 2: Tarball. The verification step is to check that the domain listed under HTTP Settings shows the Welcome to nginx! page.

The third route is a third-party repository, which is the feature that makes a private catalogue usable by other people. You add a repository URL and it appears alongside the official one in the CapRover interface.

Hosting the catalogue on the same CapRover instance that consumes it is the neat option, since the deployment is then a CapRover app like any other.

Where a one-click app is the wrong tool

The first wrong case is an application that needs a Compose parameter CapRover ignores. The respected list is eight keys, and anything outside it is dropped without a warning, so an app that needs networks, resource limits, healthchecks, secrets or a build step cannot be expressed as a template at all. You can file an issue and ask for the parameter to be added, and that is the correct path, but it is not a solution for today.

The second wrong case is a deployment that needs a dependency graph with real ordering. depends_on is parsed, which is enough for the simple case of a database that must start before the app that talks to it, but the rest of a Compose deployment story, with retry policies, health gating and migration steps, is not in the format.

The third wrong case is a service whose configuration is more than a handful of strings. A one-click app is a form plus a Compose file, and the form is generated from a list of variables with a label, a default and a regex. A service with forty settings, or with settings whose meaning depends on each other, is going to be painful to express, and the alternative, a Helm chart or an operator, is built for that shape.

The alternative worth naming is a Helm chart or a Docker Compose file that you keep in your own repository and deploy by hand, and the difference in approach is about who fills in the values. A template in this catalogue is a public form: a user opens it in the CapRover interface, sees the fields, types values, and the platform does the substitution and the deployment. A chart or a Compose file is a document your team edits and applies, which means the values live in version control and the review process applies to them.

So the trade is between self-service and control. If you want an internal service that anyone can install from a form, a one-click app is the right tool and the catalogue is where you contribute it. If you want the deployment to be reviewed, versioned and reproduced, keep the Compose file in your repository and deploy it yourself, and use this format only where the operator is trusted with the values.

Editorial conclusion

The one-click-apps repository fits a team that deploys through CapRover and wants a self-service install form for a service it runs internally, and it fits a maintainer who wants to contribute a template to the shared catalogue. It is the wrong choice if you need a Docker Compose parameter that CapRover does not parse, since the template format silently ignores most of the Compose specification, and it is the wrong choice if you need a deployment with its own dependency graph and secrets handling, since a template is a form plus a Compose file and nothing more. Before you contribute, run npm run validate_apps and npm run formatter-write as the README describes, and read the eight parsed service parameters, because the ones that are ignored are the ones that will surprise you.

Frequently asked questions

Official sources

1. caprover/one-click-apps on GitHub
2. Issues
3. License: Apache-2.0
4. README