A custom Cosmos marketplace for self-hosted applications. This repository provides a structured way to create and maintain your own collection of Cosmos Server applications (servapps).

Live Marketplace: https://iceteasa.github.io/tea-marketplace/index.json

☕Buy me a coffee

Based on the official cosmos-servapps-official repository structure.

Cosmos is a self-hosted platform that simplifies the deployment and management of Docker applications with built-in reverse proxy, automatic SSL, and security features.

• Bookshelf - Ebook and audiobook collection manager (Readarr revival)
• Posterizarr - Automated poster generation tool for media libraries
• Recyclarr - TRaSH Guides quality profiles sync for Sonarr/Radarr
• StreamyStats - Statistics and analytics service for Jellyfin
• Wizarr - User invitation system for Plex, Jellyfin, and Emby
• JellyPlex-Watched - Sync watched status between Jellyfin, Plex, and Emby
• LibreWolf - Privacy-focused web browser in a Docker container
• Example-App - Template application demonstrating servapp structure

tea-marketplace/
├── .github/
│   └── workflows/
│       └── build.yml          # GitHub Actions workflow
├── servapps/                   # Directory containing all applications
│   └── Example-App/            # Example application
│       ├── description.json    # App metadata
│       ├── cosmos-compose.json # Cosmos compose configuration
│       ├── icon.png           # App icon (256x256 or 512x512 PNG)
│       └── screenshots/        # App screenshots
├── config.json                 # Marketplace configuration
├── index.js                    # Build script
├── package.json               # Node.js package configuration
└── README.md                  # This file

• Node.js (v14 or higher)
• A Cosmos Server instance

1. Clone this repository:

   git clone <repository-url>
   cd tea-marketplace

2. Build the marketplace index:

   npm run build

   This will generate:

   • servapps.json - List of all applications
   • index.json - Complete marketplace index
   • servapps_test.json - Local testing version

The marketplace is configured in config.json:

{
  "url": "https://iceteasa.github.io/tea-marketplace/servapps.json"
}

This URL is used by the build script to generate correct asset URLs.

mkdir -p servapps/YourApp/screenshots

Create servapps/YourApp/description.json:

{
  "name": "Your App Name",
  "description": "Short description of your application",
  "longDescription": "<p>Detailed HTML description with features and information</p>",
  "tags": ["tag1", "tag2", "tag3"],
  "repository": "https://github.com/repo/project",
  "image": "https://hub.docker.com/r/image/name",
  "supported_architectures": ["amd64", "arm64"]
}

You can use either docker-compose.yml (standard Docker Compose) or cosmos-compose.json (Cosmos-specific format with forms).

Example cosmos-compose.json:

{
  "cosmos-installer": {
    "form": [
      {
        "name": "dataPath",
        "label": "What is the path to your data directory?",
        "initialValue": "{DefaultDataPath}/yourapp",
        "type": "text"
      }
    ]
  },
  "minVersion": "0.7.6",
  "services": {
    "{ServiceName}": {
      "image": "your/image:latest",
      "container_name": "{ServiceName}",
      "restart": "unless-stopped",
      "environment": [
        "TZ=auto"
      ],
      "labels": {
        "cosmos-force-network-secured": "true",
        "cosmos-auto-update": "true",
        "cosmos-icon": "https://iceteasa.github.io/tea-marketplace/servapps/YourApp/icon.png"
      },
      "volumes": [
        {
          "source": "{ServiceName}-data",
          "target": "/data",
          "type": "volume"
        }
      ],
      "routes": [
        {
          "name": "{ServiceName}",
          "description": "Expose {ServiceName} to the web",
          "useHost": true,
          "target": "http://{ServiceName}:PORT",
          "mode": "SERVAPP"
        }
      ]
    }
  }
}

• Add icon.png (256x256 or 512x512 px) to the app directory
• Add screenshots to the screenshots/ subdirectory

npm run build

The marketplace is currently deployed at: https://iceteasa.github.io/tea-marketplace/servapps.json

The GitHub Actions workflow automatically:

• Builds the marketplace on every push to main/master
• Creates a dist/ directory with only necessary files
• Deploys to the gh-pages branch
• Updates GitHub Pages with the latest servapps

Note: GitHub Pages must be configured in repository settings to deploy from the gh-pages branch.

To add this marketplace to your Cosmos Server:

1. Open your Cosmos Server admin panel
2. Navigate to the Market section
3. Click the Sources button (in the toolbar above the app list)
4. Click Add Source
5. Fill in the form:
   • Name: tea-marketplace (must be unique, cannot be "cosmos-cloud")
   • URL: https://iceteasa.github.io/tea-marketplace/index.json
6. Click Save
7. Wait for the marketplace to refresh (up to 12 hours) or restart Cosmos for immediate refresh:

   sudo systemctl restart cosmos

All applications from this marketplace will now appear in Cosmos with the @ tea-marketplace tag!

Note: Both index.json (recommended modern standard) and servapps.json (alternative) formats are supported by Cosmos.

For local testing, you can use servapps_test.json which uses localhost:3000 URLs:

1. Start a local server:

   npx http-server -p 3000

2. Configure Cosmos to use:

   http://localhost:3000/servapps_test.json
   

Extends Docker Compose with Cosmos-specific features:

• cosmos-installer.form - User input forms
• routes - Reverse proxy configuration
• labels - Cosmos-specific labels
• Template variables: {ServiceName}, {DefaultDataPath}, {Context.*}

See Cosmos Compose documentation for details.

• Cosmos Official Documentation
• Cosmos GitHub
• Official Servapps Repository
• Cosmos Documentation Repository

MIT License - Feel free to use and modify for your needs.

Contributions are welcome! Please feel free to submit a Pull Request.