Adding External Applications to Cozystack Catalog

Learn how to add managed applications from external sources

Since v0.37.0, Cozystack administrators can add applications from external sources in addition to the standard application catalog. These applications will appear in the same application catalog and behave like regular managed applications for platform users.

This guide explains howto define a managed application package and how to add it to Cozystack.

1. Create an Application Package Repository

Create a repository with the application package sources. For a reference, see github.com/cozystack/external-apps-example.

Application repository has the following structure:

  • ./packages/core: Manifests for the platform configuration and to deploy system applications.
  • ./packages/system: Helm charts for system applications.
  • ./packages/apps: Helm charts for applications that can be installed from the dashboard.

Just like standard Cozystack applications, this external application package is using Helm and FluxCD. To learn more about developing application packages, read Cozystack Developer Guide

These FluxCD documents will help you understand the resources used in this guide:

2. Add the Application Package with a Manifest

Create a manifest file with resources GitRepository and HelmRelease, as in the example:

---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: external-apps
  namespace: cozy-public
spec:
  interval: 1m0s
  ref:
    branch: main
  timeout: 60s
  url: https://github.com/cozystack/external-apps-example.git
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: external-apps
  namespace: cozy-system
spec:
  interval: 5m
  targetNamespace: cozy-system
  chart:
    spec:
      chart: ./packages/core/platform
      sourceRef:
        kind: GitRepository
        name: external-apps
        namespace: cozy-public
      version: '*'

For a detailed reference, read Git Repositories in Flux CD.

Next, write this manifest to a file and apply it to your Cozystack cluster:

kubectl apply -f init.yaml

After applying the manifest, open your application catalog to confirm that the application is available.

Last modified 2025-10-30: Upd external-apps docs (565dad9)