One-Click Deploy (OSS → remote server via Docker Compose)
Deploy any open-source project to a target Linux server with a single
orchestrated run: clone-or-upload → auto-compose → transfer → docker compose up.
When to use
- User says "把 XX 部署到服务器 / 一键部署 / deploy XX to my server".
- User provides a git URL (GitHub/GitLab/Gitee) or a local project folder
and a target server (host, user, SSH key). - User wants a reproducible, containerized deployment without hand-rolling
Dockerfiles each time.
Design decisions (fixed by this skill)
- Transport: SSH with a private key (passwordless). No passwords in scripts.
- Runtime: Docker Compose (v2 plugin preferred, v1 fallback).
- Sources: Either
--git-url(clone on local staging) or--local-path
(upload). Both supported. - Compose: Use the repo's own compose file if present; otherwise auto-generate
from the detected stack (Node / Python / Go / static). Rust & JVM are NOT
auto-generated — ask the user for a Dockerfile/compose. - Provisioning: Optional (
--provision) and idempotent — installs docker,
git, curl, firewall rules, and adds the user to the docker group.
Workflow
1. Collect required inputs
Ask the user (or read from conversation) for:
| Input | Flag | Notes |
|---|---|---|
| Server host | --host |
IP or domain |
| SSH user | --user |
e.g. ubuntu, root |
| SSH private key | --key |
Path on THIS machine (not .pub) |
| Project source | --git-url or --local-path |
Mutually exclusive |
| Project name | --project |
Optional; defaults to repo/dir name |
| Remote dir | --deploy-dir |
Optional; default ~/deploy/<project> |
| Env vars | --env K=V |
Repeatable |
| Port mapping | --ports H:C |
Repeatable; default 8080:8080 |
| Branch | --git-branch |
Optional; default main |
| Provision | --provision |
Add to install docker/firewall on a bare server |
| Force recreate | --force |
Recreate containers |
If any of host / user / key / source is missing, ask the user before running.
2. Locate the skill scripts
scripts/deploy.sh, scripts/provision.sh, scripts/gen_compose.py live
beside this SKILL.md. Resolve their absolute path via the skill directory.
3. Run the deploy
bash <skill>/scripts/deploy.sh \
--host <HOST> --user <USER> --key <KEY> \
--git-url <URL> # OR --local-path <DIR>
--ports 80:8080 \
--env NODE_ENV=production \
--provision # include on a fresh/bare server
The script prints a 6-step progress log and a final summary (access URL, how
to view logs, how to stop / redeploy).
4. Handle generation failures
If gen_compose.py exits non-zero (Rust/JVM/unknown stack), do NOT retry the
script blindly. Instead:
- Tell the user the stack wasn't auto-detectable, and ask them to either
(a) provide/commit adocker-compose.yml+Dockerfilein the repo, or
(b) paste a known-good compose file for you to drop into the staging dir.
5. Report
Summarize: deployed project, server, access URL, and the exact commands for
logs / stop / redeploy. Point to references/troubleshooting.md if anything
failed mid-way.
Reference material
references/ssh-setup.md— generate keys, copy pub key, verify passwordless SSH.references/compose-cookbook.md— detection rules and how to customize output.references/troubleshooting.md— connection / provision / build failure fixes.
Notes & safety
- Private keys stay local; only the public key ever touches the server.
- Re-running re-pulls / re-uploads fresh code and rebuilds — safe to repeat.
- Cloud security groups are separate from OS firewall; the user may still need
to open ports at the provider level. - Never hardcode secrets; pass them via
--envand they land in a server-side
.envthat is git-ignored by convention.
