{"id":47272959,"url":"https://github.com/hoveychen/muvee","last_synced_at":"2026-05-25T09:10:27.863Z","repository":{"id":344397870,"uuid":"1177771352","full_name":"hoveychen/muvee","owner":"hoveychen","description":"Lightweight self-hosted PaaS for private clouds — Git → Docker → Deploy, with smart data warehouse integration.","archived":false,"fork":false,"pushed_at":"2026-05-08T14:08:55.000Z","size":27832,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T16:18:44.515Z","etag":null,"topics":["docker","git","paas"],"latest_commit_sha":null,"homepage":"https://hoveychen.github.io/muvee/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoveychen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T11:01:24.000Z","updated_at":"2026-05-08T14:10:37.000Z","dependencies_parsed_at":"2026-04-20T14:05:31.521Z","dependency_job_id":null,"html_url":"https://github.com/hoveychen/muvee","commit_stats":null,"previous_names":["hoveychen/muvee"],"tags_count":77,"template":false,"template_full_name":null,"purl":"pkg:github/hoveychen/muvee","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoveychen%2Fmuvee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoveychen%2Fmuvee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoveychen%2Fmuvee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoveychen%2Fmuvee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoveychen","download_url":"https://codeload.github.com/hoveychen/muvee/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoveychen%2Fmuvee/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32987764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","git","paas"],"created_at":"2026-03-15T14:28:26.405Z","updated_at":"2026-05-13T15:00:52.471Z","avatar_url":"https://github.com/hoveychen.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003emuvee\u003c/h1\u003e\n\n\u003cimg src=\"docs/static/img/mascot.png\" alt=\"muvee mascot\" width=\"320\" /\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/hoveychen/muvee/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://github.com/hoveychen/muvee/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hoveychen/muvee/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/hoveychen/muvee?color=c8f03c\" alt=\"Latest Release\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hoveychen/muvee/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/hoveychen/muvee\"\u003e\n    \u003cimg src=\"https://goreportcard.com/badge/github.com/hoveychen/muvee\" alt=\"Go Report Card\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go\" alt=\"Go Version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-linux%20%7C%20macos-lightgrey\" alt=\"Platform\" /\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\u003cstrong\u003eLightweight self-hosted PaaS for private clouds — Git → Docker → Deploy, with smart data warehouse integration.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e · \u003ca href=\"README.zh.md\"\u003e中文\u003c/a\u003e ·\n  \u003ca href=\"https://hoveychen.github.io/muvee\"\u003eDocs\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/hoveychen/muvee/releases\"\u003eReleases\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/static/img/comic-promo-en.png\" alt=\"muvee comic — from localhost to the world\" width=\"720\" /\u003e\n\u003c/div\u003e\n\n---\n\n## 🤖 Deploy with AI — One-Click via Agent Skill\n\nmuvee ships a built-in **Agent Skill** (`SKILL.md`) that teaches Cursor, Claude Code, Copilot, and other AI coding assistants how to use `muveectl`. Once the AI reads the skill, it can create projects, trigger deployments, and manage your cloud — all from a single instruction.\n\n**Load the skill into your AI assistant:**\n\n```\nhttps://YOUR_MUVEE_SERVER/api/skill\n```\n\n\u003e Replace `YOUR_MUVEE_SERVER` with the domain of your muvee instance (e.g. `https://example.com`).  \n\u003e You can also find the live URL on the Community page of your muvee deployment.\n\n---\n\n## What is muvee?\n\n**muvee** stands for **M**icroservices **U**nified **V**irtualized **E**xecution **E**ngine.\n\nmuvee is a **self-hosted PaaS** designed for private clouds with many lightweight applications. No Kubernetes, no YAML sprawl. Push a tag → binary is released. Connect a Git repo → container is deployed.\n\nKey features:\n\n- **Git → Docker → Deploy** — point at a repo with a `Dockerfile`, click Deploy. muvee builds the image on a builder node, pushes to its internal registry, and runs the container on a deploy node, wired to `{project}.example.com` automatically via Traefik.\n- **Data Warehouse Integration** — declare NFS-backed datasets as dependencies. muvee rsyncs them to the deploy node (LRU-cached, versioned) and mounts them into the container at `/data/{name}`. Or declare a dataset as `readwrite` for a direct NFS bind-mount.\n- **Smart Affinity Scheduling** — deploy nodes are scored by how many required datasets they already have cached, minimizing rsync time.\n- **File-level Dataset Tracking** — a background monitor scans NFS paths, diffs file trees, and records a `git log`–style history of every file change (added / modified / deleted), with per-file timelines in the UI.\n- **Flexible Identity Providers** — sign in via Google, Feishu/Lark, WeCom (企业微信), or DingTalk (钉钉). Multiple providers can be enabled simultaneously. Per-project ForwardAuth supports Google for protecting deployed apps.\n- **Per-Project Access Control** — flip a project to `private` to restrict the deployed service to an explicit allow-list. Owners get a Recent Visitors list (who's been hitting the service) and a Pending Requests inbox (denied users can submit a one-click access request from the deny page).\n- **Adhoc Tunnel** — publish any local port to the internet with `muveectl tunnel 8080`. A deterministic, human-readable subdomain (e.g. `t-bold-fox.example.com`) is generated from the working directory and port — like a self-hosted ngrok.\n- **Single binary** — one `muvee` binary runs as `muvee server`, `muvee agent`, or `muvee authservice`. The server subcommand embeds the React web UI — no separate web server needed.\n\n## Quick Start\n\n**Prerequisites — DNS**\n\nPoint a wildcard A record at your VPS IP before starting:\n\n```\nType  Name               Value\nA     example.com        \u003cyour-vps-ip\u003e   (control panel)\nA     *.example.com      \u003cyour-vps-ip\u003e   (covers all project subdomains, including www)\n```\n\nMake sure ports **80** and **443** are open on the VPS firewall. Traefik will obtain a Let's Encrypt certificate automatically.\n\n**1 — Configure an identity provider**\n\nmuvee requires at least one identity provider. You can enable multiple simultaneously — the login page shows a button for each. Supported providers:\n\n| Provider | Env vars to set |\n|---|---|\n| [Google](https://hoveychen.github.io/muvee/docs/auth/auth-google) | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |\n| [Feishu / Lark](https://hoveychen.github.io/muvee/docs/auth/auth-feishu) | `FEISHU_APP_ID`, `FEISHU_APP_SECRET` |\n| [WeCom 企业微信](https://hoveychen.github.io/muvee/docs/auth/auth-wecom) | `WECOM_CORP_ID`, `WECOM_CORP_SECRET`, `WECOM_AGENT_ID` |\n| [DingTalk 钉钉](https://hoveychen.github.io/muvee/docs/auth/auth-dingtalk) | `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET` |\n\n**2 — Configure**\n\n```bash\ngit clone https://github.com/hoveychen/muvee.git \u0026\u0026 cd muvee\ncp .env.example .env\n# Edit .env — fill in BASE_DOMAIN, at least one identity provider,\n#             JWT_SECRET, ACME_EMAIL, ADMIN_EMAILS,\n#             REGISTRY_USER, REGISTRY_PASSWORD,\n#             AGENT_SECRET (shared secret for agent authentication)\n```\n\n**3 — Generate registry credentials**\n\nThe private registry requires a htpasswd file. Run once on the control plane host:\n\n```bash\ndocker run --entrypoint htpasswd httpd:2 -Bbn \u003cREGISTRY_USER\u003e \u003cREGISTRY_PASSWORD\u003e \u003e registry/htpasswd\n```\n\nUse the same `REGISTRY_USER` / `REGISTRY_PASSWORD` values you set in `.env`.\n\n**4 — Start**\n\n**Standalone** (single machine — default, recommended for getting started):\n\n```bash\ndocker compose up -d\n```\n\nThis starts everything on one machine: server, agents (builder + deploy), Traefik, PostgreSQL, and the private registry.\n\n**Multi-node** (agents on separate worker machines):\n\n```bash\n# On the control-plane host — server only\ndocker compose -f docker-compose.server.yml up -d\n```\n\nThen register each worker node separately (see step 5).\n\nTraefik is now listening on 443. Open `https://BASE_DOMAIN` and sign in with your configured identity provider. Admin accounts listed in `ADMIN_EMAILS` also gain access to `https://traefik.BASE_DOMAIN`.\n\n**5 — Register worker nodes** *(multi-node only — skip if using standalone)*\n\nRun the following on each worker machine. Registry credentials, `BASE_DOMAIN`, `VOLUME_NFS_BASE_PATH`, and `DATASET_NFS_BASE_PATH` are **automatically distributed** from the control plane — agents fetch them via `/api/agent/config` on startup, so you don't need to configure these values per node.\n\n\u003e `CONTROL_PLANE_URL` must be the **internal network address** of the control plane (e.g. `http://10.0.0.1:8080`), not the public domain. The agent uses this to detect the correct network interface for Traefik routing.\n\u003e\n\u003e If you run agents in Docker, volume mounts are still required:\n\u003e - Workspace: mount `VOLUME_NFS_BASE_PATH` (same absolute path as control plane)\n\u003e - Datasets: mount `DATASET_NFS_BASE_PATH` (same absolute path as control plane)\n\n\u003e **Using an AI assistant?** Load the install-agent skill and let your AI walk you through the setup:\n\u003e ```\n\u003e https://raw.githubusercontent.com/hoveychen/muvee/main/.cursor/skills/install-agent/SKILL.md\n\u003e ```\n\n**Linux (Docker Compose)**\n\n```bash\n# Builder node\ncp .env.agent.example .env\ndocker compose -f docker-compose.agent-builder.yml up -d\n\n# Deploy node\ncp .env.agent.example .env\n# If workspace/dataset features are enabled on control plane:\n#   set VOLUME_NFS_BASE_PATH / DATASET_NFS_BASE_PATH in .env\n#   then uncomment their volume lines in docker-compose.agent-deploy.yml\ndocker compose -f docker-compose.agent-deploy.yml up -d\n```\n\n**Linux (Docker)**\n\n```bash\n# Builder node\ndocker run -d --name muvee-agent --restart unless-stopped \\\n  -e NODE_ROLE=builder \\\n  -e CONTROL_PLANE_URL=http://10.0.0.1:8080 \\\n  -e AGENT_SECRET=\u003cyour-agent-secret\u003e \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  ghcr.io/hoveychen/muvee:latest agent\n\n# Deploy node\ndocker run -d --name muvee-agent --restart unless-stopped \\\n  -e NODE_ROLE=deploy \\\n  -e CONTROL_PLANE_URL=http://10.0.0.1:8080 \\\n  -e AGENT_SECRET=\u003cyour-agent-secret\u003e \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v /muvee/data:/muvee/data \\\n  -v /mnt/nfs/volumes:/mnt/nfs/volumes \\\n  -v /mnt/nfs/datasets:/mnt/nfs/datasets \\\n  ghcr.io/hoveychen/muvee:latest agent\n```\n\n**macOS (binary — recommended)**\n\nDocker Desktop on macOS runs containers inside a Linux VM, so `docker.sock` inside a container points to the VM rather than your Mac. Use the native binary instead:\n\n```bash\n# Download (Apple Silicon)\ncurl -Lo muvee https://github.com/hoveychen/muvee/releases/latest/download/muvee_darwin_arm64\nchmod +x muvee \u0026\u0026 sudo mv muvee /usr/local/bin/\n\n# Builder node\nNODE_ROLE=builder CONTROL_PLANE_URL=http://10.0.0.1:8080 AGENT_SECRET=\u003csecret\u003e \\\n  muvee agent\n\n# Deploy node\nNODE_ROLE=deploy CONTROL_PLANE_URL=http://10.0.0.1:8080 AGENT_SECRET=\u003csecret\u003e \\\n  DATA_DIR=/Users/Shared/muvee/data muvee agent\n```\n\n**Windows (binary via WSL2 — recommended)**\n\nRun the agent inside WSL2 so it has access to `docker.sock`, `rsync`, and Linux paths:\n\n```bash\n# Inside WSL2 shell\ncurl -Lo muvee https://github.com/hoveychen/muvee/releases/latest/download/muvee_linux_amd64\nchmod +x muvee\n\nNODE_ROLE=deploy CONTROL_PLANE_URL=http://10.0.0.1:8080 AGENT_SECRET=\u003csecret\u003e \\\n  DATA_DIR=/mnt/c/muvee/data ./muvee agent\n```\n\n\u003e Ensure Docker Desktop → Settings → **Use the WSL 2 based engine** is enabled, and the WSL2 distro is allowed under **Resources → WSL Integration**.\n\nSee the **[Agent Installation Guide →](https://hoveychen.github.io/muvee/docs/install-agent)** for full step-by-step instructions including dependency setup.\n\nSee the **[full documentation →](https://hoveychen.github.io/muvee)**\n\n## Architecture at a Glance\n\n![muvee system architecture overview](docs/static/img/arch-overview-en.png)\n\n```\nControl Plane (single host)\n  muvee-server    — API + Web UI (Go, embeds React)\n  muvee-authsvc   — Traefik ForwardAuth sidecar\n  PostgreSQL      — metadata\n  Traefik v3      — HTTPS reverse proxy, auto-routing\n  Distribution    — private Docker registry\n\nWorker Nodes (any number, any mix)\n  muvee-agent     — builder or deploy role, polls control plane\n```\n\n## Release Binaries\n\n**Server / Agent** — pre-built for Linux and macOS (amd64 + arm64):\n\n```bash\ncurl -L https://github.com/hoveychen/muvee/releases/latest/download/muvee_linux_amd64.tar.gz | tar xz\n./muvee_linux_amd64 server      # starts API + web UI on :8080, auto-migrates DB\n./muvee_linux_amd64 agent       # worker node (set NODE_ROLE=builder or deploy)\n./muvee_linux_amd64 authservice # Traefik ForwardAuth sidecar\n```\n\n**muveectl** — CLI client for Linux, macOS, and Windows.\n\nFastest path — once your hub is up, a one-liner installs the right binary for your OS/arch:\n\n```bash\ncurl -fsSL https://YOUR_MUVEE_SERVER/api/install.sh | sh\n```\n\nThe hub serves `muveectl` binaries that were cross-compiled alongside the server, so the install works fully offline. If the hub wasn't built with embedded binaries, `/api/muveectl/*` transparently 302-redirects to the matching GitHub release asset.\n\nIf you don't have a hub yet (e.g. installing on the machine that will host it), pull directly from GitHub:\n\n```bash\n# macOS (Apple Silicon)\ncurl -Lo muveectl https://github.com/hoveychen/muvee/releases/latest/download/muveectl_darwin_arm64\nchmod +x muveectl \u0026\u0026 sudo mv muveectl /usr/local/bin/\n\n# macOS (Intel)\ncurl -Lo muveectl https://github.com/hoveychen/muvee/releases/latest/download/muveectl_darwin_amd64\nchmod +x muveectl \u0026\u0026 sudo mv muveectl /usr/local/bin/\n\n# Linux (amd64)\ncurl -Lo muveectl https://github.com/hoveychen/muvee/releases/latest/download/muveectl_linux_amd64\nchmod +x muveectl \u0026\u0026 sudo mv muveectl /usr/local/bin/\n\n# Linux (arm64)\ncurl -Lo muveectl https://github.com/hoveychen/muvee/releases/latest/download/muveectl_linux_arm64\nchmod +x muveectl \u0026\u0026 sudo mv muveectl /usr/local/bin/\n```\n\n```powershell\n# Windows (PowerShell)\nInvoke-WebRequest -Uri https://github.com/hoveychen/muvee/releases/latest/download/muveectl_windows_amd64.exe -OutFile muveectl.exe\nMove-Item muveectl.exe \"$env:LOCALAPPDATA\\Microsoft\\WindowsApps\\muveectl.exe\"\n```\n\n```bash\nmuveectl login --server https://example.com  # first-time setup\nmuveectl projects list\nmuveectl projects deploy PROJECT_ID\n```\n\nSee the [muveectl CLI reference](https://hoveychen.github.io/muvee/docs/muveectl) for full command documentation.\n\n## Prerequisites\n\n| | |\n|---|---|\n| Control plane host | Linux, Docker |\n| **Builder nodes** | Linux, **Docker CE 20.10+** with `docker-buildx-plugin`, `git` |\n| **Deploy nodes** | Linux, Docker (any recent), `rsync` |\n| NFS share | Mounted at the same path on all deploy nodes |\n| PostgreSQL 16+ | Can use the bundled Docker Compose service |\n| Identity provider | At least one of: [Google](https://hoveychen.github.io/muvee/docs/auth/auth-google), [Feishu/Lark](https://hoveychen.github.io/muvee/docs/auth/auth-feishu), [WeCom](https://hoveychen.github.io/muvee/docs/auth/auth-wecom), [DingTalk](https://hoveychen.github.io/muvee/docs/auth/auth-dingtalk) |\n\n\u003e **Builder nodes require Docker CE from [docker.com](https://docs.docker.com/engine/install/ubuntu/), not the `docker.io` package** in Ubuntu's default apt repo. The `docker.io` package often lacks the `docker-buildx-plugin`, causing builds to fail with `unknown flag: --platform`. See the [Agent Installation Guide](https://hoveychen.github.io/muvee/docs/install-agent) for the full step-by-step setup.\n\n## Documentation\n\n- [Getting Started](https://hoveychen.github.io/muvee/docs/getting-started)\n- [Installation](https://hoveychen.github.io/muvee/docs/installation)\n- [Configuration Reference](https://hoveychen.github.io/muvee/docs/configuration)\n- **Authentication** — [Google](https://hoveychen.github.io/muvee/docs/auth/auth-google) · [Feishu/Lark](https://hoveychen.github.io/muvee/docs/auth/auth-feishu) · [WeCom](https://hoveychen.github.io/muvee/docs/auth/auth-wecom) · [DingTalk](https://hoveychen.github.io/muvee/docs/auth/auth-dingtalk)\n- [Architecture](https://hoveychen.github.io/muvee/docs/architecture)\n- [Scheduler \u0026 Affinity](https://hoveychen.github.io/muvee/docs/scheduler)\n- [Dataset Monitor](https://hoveychen.github.io/muvee/docs/dataset-monitor)\n- [ForwardAuth \u0026 Access Control](https://hoveychen.github.io/muvee/docs/forward-auth)\n- [muveectl CLI](https://hoveychen.github.io/muvee/docs/muveectl)\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) if you'd like to contribute.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoveychen%2Fmuvee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoveychen%2Fmuvee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoveychen%2Fmuvee/lists"}