compote

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 59 Open GitHub ↗

Compose Templater - UI for create, validate and manage docker compose based infrastructures

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Compote — Compose Templater

Visual Docker Compose editor for building, validating, and exporting self-hosted infrastructure stacks.
Compote is for homelab users, self-hosters, and DevOps engineers who want to build Docker Compose stacks visually, detect port/dependency conflicts, and export ready-to-deploy bundles.

## What it does

Compote lets you build and manage Docker Compose setups through a point-and-click UI instead of hand-writing YAML. You organize services into Compose projects, and projects onto hosts (physical or virtual machines). When you're done, export a ready-to-deploy ZIP bundle with your `docker-compose.yml` and a generated README.

**Key capabilities:**
- **Validation** — real-time rule-based checks catch misconfigured services before you deploy
- **Connectivity tracking** — detects port conflicts, missing network links, unresolved service dependencies, and cross-project collisions
- **Visual service editor** — configure images, ports, volumes, environment variables, and `depends_on` through forms; see the rendered YAML in real time
- **Multi-host management** — model your infrastructure as hosts (with OS/architecture metadata), each carrying one or more Compose projects
- **Registry search** — browse Docker Hub and GitHub Container Registry to pick images directly in the UI
- **README generation** — produces a Markdown README from your Compose file automatically
- **ZIP export** — download a bundle with `docker-compose.yml`, `.env`, and generated docs
- **Serverless** — runs entirely in the browser; no backend, no account, all data stays in local IndexedDB

## Why Compote?
- Avoid hand-writing repetitive Compose YAML
- Catch port conflicts and missing dependencies before deployment
- Build reusable service catalogs and stack presets
- Export clean, ready-to-deploy Compose bundles
- Works locally in the browser or self-hosted with SQLite

## How is this different from Portainer / Komodo?
Compote is not a runtime orchestrator. It focuses on planning, validating, templating, and exporting Docker Compose stacks before deployment.

## Screenshots

### Host Management 
![Host Management](https://raw.githubusercontent.com/aicrafted/compote/main/docs/assets/screenshots/host.png)

### Service Builder
![Visual Service Builder](https://raw.githubusercontent.com/aicrafted/compote/main/docs/assets/screenshots/service.png)

## Deployment

### Hosted (no setup)

The app is available at **[compote.aicrafted.org](https://compote.aicrafted.org)** — runs entirely in the browser, data stays in local IndexedDB, no account required.

### Self-host with Docker

```yaml
# docker-compose.yml
services:
  compote:
    image: ghcr.io/aicrafted/compote:latest
    ports:
      - "3474:3000"
    volumes:
      - ./data:/data
    restart: unless-stopped
```

```bash
docker compose up -d
# → http://localhost:3474
```

In self-hosted mode the app uses a **local SQLite database** stored in `./data` instead of the browser's IndexedDB. Data persists across browsers and devices on the same server. The `./data` directory also serves as the catalog volume — drop custom service definitions there to extend the built-in catalog at runtime.

---

## Tech stack

| Layer | Technology |
|---|---|
| Framework | React 18 + TypeScript 5 |
| Build | Vite 5 + Bun |
| Styling | Tailwind CSS 3 + shadcn/ui |
| State | Zustand |
| Storage | IndexedDB (browser) · SQLite via Bun (self-hosted) |
| Routing | React Router v6 |

## Development

**Prerequisites:** [Bun](https://bun.sh) ≥ 1.0

```bash
# Install dependencies
bun install

# Start dev server (http://localhost:3010)
bun run dev
```

## Build

```bash
# Production build
bun run build

# Preview production build
bun run preview
```

## Adding services to the catalog

Each service lives in its own directory under `public/catalog/{service-id}/`:

```
public/catalog/
  prometheus/
    metadata.json       ← display name, category, image, ports, env vars, volumes
    compose-part.yml    ← service body injected into Compose output (no top-level keys)
    icon.svg / icon.png
```

`catalog.json` is auto-generated by a Vite plugin on every build — never edit it directly.

**Minimal `metadata.json`:**

```json
{
  "name": "Prometheus",
  "category": "MONITORING",
  "description": "The Prometheus monitoring system and time series database.",
  "image": "prom/prometheus:latest",
  "containerPorts": [9090],
  "defaultHostPort": 9090,
  "requires": [],
  "requiredEnv": [],
  "publicExposure": "optional",
  "resourceClass": "medium",
  "iconSVG": true
}
```

Icons can be fetched automatically from [Simple Icons](https://simpleicons.org), [selfh.st](https://selfh.st/icons), or [Dashboard Icons](https://dashboardicons.com/icons) via:

```bash
node scripts/fetch-icons.mjs {service-id}
```

## Project structure

```
src/
├── components/ui/     # shadcn/ui primitives
├── features/          # Feature modules (builder, hosts)
├── lib/core/          # Pure logic: importers, exporters, renderers, validation rules
└── stores/            # Zustand stores
```

Data model: **Host → Compose Projects → Services**

Routes: `/hosts` → `/hosts/:hostId` → `/hosts/:hostId/:composeId`

## License

[MIT](LICENSE)

compote

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README