Publish your first app

Start from the template

If you have access to the CI-Marketplace repository, clone it and copy the template:

cp -r apps/_template apps/my-app

Otherwise, create a folder named my-app with the four files below. The web form and cihub submit accept the folder from anywhere on your machine.

The slug you choose is your app’s identity — the directory name and the id in config.json must match.

Write config.json

Ten fields are required:

A minimal valid file:

{
  "id": "my-app",
  "name": "My App",
  "version": "1.0.0",
  "short_desc": "A short description of what the app does.",
  "author": "your-name",
  "port": 8080,
  "source": "https://github.com/you/my-app",
  "categories": ["utilities"],
  "available": true,
  "supported_architectures": ["arm64", "amd64"]
}

Optional fields worth knowing: description, website, exposable, dynamic_config, form_fields, cihub_app_version, force_pull, no_gui, and mcp. See the config.json reference.

Write docker-compose.json

JSON, not YAML, on schema version 2. Exactly one service must be marked isMain.

{
  "schemaVersion": 2,
  "services": [
    {
      "name": "my-app",
      "image": "org/my-app:1.0.0",
      "internalPort": 8080,
      "isMain": true,
      "volumes": [
        { "hostPath": "${APP_DATA_DIR}/data", "containerPath": "/data" }
      ],
      "environment": [{ "key": "KEY", "value": "value" }]
    }
  ]
}

environment is a list of key and value pairs, not an object, and every value needs at least one character. Common per-service properties: name, image, internalPort, isMain, volumes, environment, dependsOn, entrypoint, extraLabels, plus ports, command, healthCheck, and more. See Dynamic Compose.

Add metadata

• metadata/description.md — the long description on your app’s detail page
• metadata/logo.png or logo.jpg — at least one, and it must not be 0 bytes

Test on a device

Install your app on a Hub and confirm it starts, serves on its port, and persists data across a restart.

Capture a verification screenshot

Save a screenshot of your app running to:

e2e/screenshots/my-app.png

This is the QA record, in the CI-Marketplace repository, that the app was installed and verified on a device. It is strongly recommended for the pull-request route and surfaced by the audit tooling, but it is not currently a hard deploy gate — the pipeline ships any apps/<slug>/ with a valid config.json. Store visibility is controlled by available, not by the screenshot.

Submit it

Pick a route. All three need the same four files and end in review — see Submitting apps to the marketplace for the details.

• Web form (recommended). Go to ci.computer/store-submit  and submit your app there. You don’t need repository access.
• CLI. Run cihub login, check the folder with cihub submit --dry-run ./my-app, then cihub submit ./my-app. It ingests your app as pending; it never publishes on its own.
• Pull request. If you have access to CI-Marketplace, commit your directory and open a PR against it. The pipeline deploys on merge.