ui-syncup 0.2.4 → 0.3.10

package/README.md

@@ -1,84 +1,93 @@
-# ui-syncup
+# ui-syncup CLI
 
-CLI for managing self-hosted [UI SyncUp](https://github.com/BYKHD/ui-syncup) instances.
-
-UI SyncUp is a visual feedback and issue tracking platform for design-to-development collaboration — pin annotations on mockups, create issues from visual feedback, and track them through a structured workflow.
+Self-host [UI SyncUp](https://github.com/BYKHD/ui-syncup) with a single command. No infrastructure knowledge required.
 
 ## Requirements
 
-- **Node.js** ≥ 20
-- **Docker** — required by `ui-syncup up` (Supabase runs inside Docker)
-- **Bun** — required to run the full application after `init`
-- **Supabase CLI** — installed automatically if missing, or install manually: `brew install supabase/tap/supabase`
+- [Docker](https://docs.docker.com/get-docker/) ≥ 24
+- Node.js ≥ 20 (only needed to run the CLI — the app itself runs in Docker)
 
-## Installation
+## Quick Start
 
 ```bash
-npm install -g ui-syncup
-# or
-bun add -g ui-syncup
+mkdir my-syncup && cd my-syncup
+npx ui-syncup init
 ```
 
-## Quick Start
+The wizard downloads `compose.yml`, walks you through service configuration, and starts the stack.
 
-```bash
-# 1. Clone the repository into a new folder
-ui-syncup init
+## Commands
 
-# 2. Start all services (Supabase, migrations, admin user)
-ui-syncup up
+### Setup & Lifecycle
 
-# 3. Start the development server (from inside the project folder)
-bun dev
-```
+| Command | Description |
+|---|---|
+| `init` | Guided first-time setup wizard |
+| `start` | Start the stack (reads `COMPOSE_PROFILES` from `.env`) |
+| `stop` | Stop gracefully — data is preserved |
+| `restart [service]` | Restart all services or a single one |
+| `remove` | Remove containers (`--volumes` to also wipe all data) |
 
-Open [http://localhost:3000](http://localhost:3000) in your browser.
+### Observability
 
-## Commands
+| Command | Description |
+|---|---|
+| `status` | Show container states, health, and app URL |
+| `logs [service]` | Tail last 200 lines (`-F` to stream live) |
+| `doctor` | Validate env vars, health endpoint, and disk space |
+| `open` | Open the app in your default browser |
+
+### Maintenance
 
 | Command | Description |
-|---------|-------------|
-| `ui-syncup init` | Initialize a new project — creates `.env` files, storage dirs, and config |
-| `ui-syncup up` | Start all services: Supabase, run migrations, create admin user |
-| `ui-syncup down` | Stop all services |
-| `ui-syncup reset` | Reset data to a clean state (preserves config files) |
-| `ui-syncup purge` | Full cleanup — removes all data, volumes, and config |
+|---|---|
+| `upgrade` | Pull latest image and restart (migrations apply automatically) |
+| `backup` | Dump PostgreSQL + MinIO to a timestamped `.tar.gz` |
+| `restore <archive>` | Restore from a backup archive |
 
-## Global Options
+## Usage Examples
 
-| Flag | Description |
-|------|-------------|
-| `-v, --version` | Display CLI version |
-| `--verbose` | Enable verbose output for debugging |
-| `--no-color` | Disable colored output (useful in CI environments) |
+```bash
+# First-time setup
+npx ui-syncup init
 
-## Init Modes
+# Day-to-day
+ui-syncup status
+ui-syncup logs -F              # stream all logs
+ui-syncup logs app -F          # stream app logs only
+ui-syncup restart app          # restart just the app container
 
-`ui-syncup init` supports two setup modes:
+# Upgrades
+ui-syncup upgrade
 
-- **Local** — sets up a local development environment with MinIO (S3-compatible storage)
-- **Production** — configures production with Cloudflare R2/AWS S3 and transactional email (Resend or SMTP)
+# Backup & restore
+ui-syncup backup -o ~/backups
+ui-syncup restore ~/backups/ui-syncup-backup-2026-03-19T12-00.tar.gz
 
-## Examples
+# Teardown
+ui-syncup remove               # keep data volumes
+ui-syncup remove --volumes     # wipe everything
+```
 
-```bash
-# Initialize in local mode without prompts
-ui-syncup init --mode local
+## Bundled Services (Docker Compose profiles)
 
-# Start with verbose output for debugging
-ui-syncup up --verbose
+`init` lets you choose which services to bundle. Your selection is saved as `COMPOSE_PROFILES` in `.env` so subsequent `start`/`upgrade` commands pick it up automatically.
 
-# Skip migrations on startup (if already up to date)
-ui-syncup up --skip-migrations
+| Profile | Service | Use when |
+|---|---|---|
+| `db` | PostgreSQL 15 | No external database |
+| `cache` | Redis 7 | No external Redis/Upstash |
+| `storage` | MinIO | No external S3/R2/Backblaze |
 
-# Full reset (requires typing the confirmation phrase)
-ui-syncup purge
-```
+## Backup Details
+
+`backup` only exports data for active profiles:
 
-## Repository
+- **PostgreSQL** (`db` profile) — `pg_dumpall` → `postgres.sql`
+- **MinIO** (`storage` profile) — volume tar → `minio_data.tar.gz`
+- Redis is intentionally excluded (cache — not persistent state)
 
-Source code, issue tracker, and full documentation:
-[github.com/BYKHD/ui-syncup](https://github.com/BYKHD/ui-syncup)
+Output is a single `.tar.gz` archive you can store offsite.
 
 ## License