Skip to content

Commit 69c336e

Browse files
hailangvnhailangvn
committed
feat: colocate deploy.py skill in CLI repo
1 parent 0670fe9 commit 69c336e

1 file changed

Lines changed: 250 additions & 0 deletions

File tree

‎skills/deploy.py/SKILL.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
name: odoo-dev:deploy.py
3+
description: Deploy and manage Odoo, Python, and generic service instances on remote servers via SSH using the deploy CLI tool. Use when setting up new instances (configure), deploying updates (update), or checking instance status (status).
4+
version: 1.0.0
5+
argument-hint: "[configure|update|status] [instance_name] [options]"
6+
---
7+
8+
# deploy.py
9+
10+
Deploy and manage application instances on remote servers over SSH using the [`deploy`](https://github.com/trobz/deploy.py) CLI tool.
11+
12+
Supports three deployment types:
13+
- **`odoo`** — Odoo projects (auto-detected from `odoo-` / `openerp-` prefix)
14+
- **`python`** — Generic Python services (FastAPI, Flask, workers, etc.)
15+
- **`service`** — Any non-Python application where build/start commands are operator-defined
16+
17+
**Scope:** deploy CLI only. Does NOT handle SSH key setup, PostgreSQL provisioning, or Odoo module development.
18+
19+
---
20+
21+
## Installation
22+
23+
### Local machine (operator)
24+
25+
```bash
26+
uv tool install deploy
27+
```
28+
29+
Or:
30+
31+
```bash
32+
pip install deploy
33+
```
34+
35+
### Remote server (target host)
36+
37+
Install tools required by the deployment type:
38+
39+
```bash
40+
# Odoo deployments
41+
uv tool install odoo-venv
42+
uv tool install odoo-addons-path
43+
uv tool install git-aggregator
44+
45+
# Python deployments
46+
uv tool install uv # usually pre-installed
47+
```
48+
49+
---
50+
51+
## Instance Name Convention
52+
53+
```
54+
<type_prefix>-<project_slug>-<environment>[-<suffix>]
55+
```
56+
57+
| Segment | Examples |
58+
|---------|---------|
59+
| `type_prefix` | `odoo`, `openerp`, `service` |
60+
| `environment` | `integration`, `staging`, `production`, `hotfix`, `debug`, `demo` |
61+
| `suffix` | Optional: `-02`, `-eu`, `-vn` |
62+
63+
**Examples:**
64+
```
65+
odoo-myproject-production
66+
odoo-myproject-staging-02
67+
service-myapi-production-eu
68+
```
69+
70+
---
71+
72+
## Configuration File (`deploy.yml`)
73+
74+
Lives **locally** on the operator's machine (not committed to the project repo).
75+
76+
```yaml
77+
# deploy.yml
78+
79+
odoo-myproject-production:
80+
ssh_host: deploy@myserver.example.com
81+
ssh_port: 22 # optional, default 22
82+
repo_url: git@github.com:org/repo.git # used by configure
83+
# type: odoo # auto-detected from "odoo-" prefix
84+
db: myproject # optional; defaults to instance_name
85+
86+
hooks:
87+
pre-update:
88+
- ./scripts/check_disk_space.sh
89+
pre-update-required:
90+
- ./scripts/run_tests.sh # failure aborts the update
91+
pre-update-success:
92+
- ./scripts/notify.sh "Pre-checks passed"
93+
pre-update-fail:
94+
- ./scripts/notify.sh "Pre-checks failed"
95+
post-update:
96+
- ./scripts/smoke_test.sh
97+
post-update-success:
98+
- ./scripts/notify.sh "Update succeeded"
99+
post-update-fail:
100+
- ./scripts/notify.sh "Update failed"
101+
102+
service-myapi-production:
103+
ssh_host: deploy@apiserver.example.com
104+
repo_url: git@github.com:org/myapi.git
105+
type: python
106+
exec_start: python -m myapi.main
107+
108+
service-myui-production:
109+
ssh_host: deploy@uiserver.example.com
110+
repo_url: git@github.com:org/myui.git
111+
type: service
112+
build: npm ci && npm run build
113+
exec_start: node dist/server.js
114+
```
115+
116+
CLI arguments always override config file values.
117+
118+
---
119+
120+
## Commands
121+
122+
### `deploy configure` — Set up a new instance
123+
124+
Clones the repo, sets up the application environment, and registers a systemd user unit.
125+
126+
```bash
127+
deploy configure <instance_name> [ssh_host] [repo_url] [--type odoo|python|service] [-p PORT] [--force]
128+
```
129+
130+
**Options:**
131+
- `--type` — Override auto-detected type
132+
- `--force` — Re-run setup even if the instance directory already exists
133+
- `-p` — SSH port (default: 22)
134+
135+
**Examples:**
136+
```bash
137+
# Odoo instance (type auto-detected from "odoo-" prefix)
138+
deploy configure odoo-myproject-staging deploy@server.example.com git@github.com:org/repo.git
139+
140+
# With config file (only instance name needed)
141+
deploy configure odoo-myproject-staging
142+
143+
# Python service
144+
deploy configure service-myapi-production deploy@server.example.com git@github.com:org/api.git --type python
145+
146+
# Force re-setup
147+
deploy configure odoo-myproject-staging --force
148+
```
149+
150+
**What it does:**
151+
1. Connects via SSH (or runs locally if no `ssh_host`)
152+
2. Clones the repo into `~/<instance_name>` on the remote host
153+
3. Sets up the environment:
154+
- **odoo**: runs `odoo-venv` + `odoo-addons-path`
155+
- **python**: creates `.venv`, installs from `requirements.txt` or `pyproject.toml`
156+
- **service**: runs the `build` command from `deploy.yml`
157+
4. Writes and enables a systemd user unit at `~/.config/systemd/user/<instance_name>.service`
158+
159+
---
160+
161+
### `deploy update` — Deploy / update an existing instance
162+
163+
Pulls latest code, updates dependencies, applies changes, and restarts the service.
164+
165+
```bash
166+
deploy [--config FILE] update <instance_name> [ssh_host] [-p PORT] [--type odoo|python|service] [--db DATABASE] [--ignore-hooks]
167+
```
168+
169+
**Options:**
170+
- `--db` — (Odoo only) Override the target database name
171+
- `--ignore-hooks` — Skip all hook execution
172+
173+
**Examples:**
174+
```bash
175+
# With config file
176+
deploy update odoo-myproject-staging
177+
178+
# Override database
179+
deploy update odoo-myproject-staging --db myproject_alt
180+
181+
# Skip hooks
182+
deploy update odoo-myproject-staging --ignore-hooks
183+
184+
# Specify config file location
185+
deploy --config /path/to/deploy.yml update odoo-myproject-staging
186+
```
187+
188+
**Hook execution order:**
189+
190+
| Hook | When | Blocks on failure? |
191+
|------|------|--------------------|
192+
| `pre-update` | Before update | No |
193+
| `pre-update-required` | After pre-update | **Yes** |
194+
| `pre-update-success` / `pre-update-fail` | After pre-update phase | No |
195+
| `post-update` | After update | No |
196+
| `post-update-success` / `post-update-fail` | After update | No |
197+
198+
**What it does (Odoo):**
199+
1. Runs pre-update hooks
200+
2. `git pull` in `~/<instance_name>`
201+
3. `uv pip install -r requirements.txt`
202+
4. `click-odoo-upgrade -d <database_name>`
203+
5. `systemctl --user restart <instance_name>`
204+
6. Runs post-update hooks
205+
206+
---
207+
208+
### `deploy status` — Check instance state
209+
210+
```bash
211+
deploy [--config FILE] status <instance_name> [ssh_host] [-p PORT]
212+
```
213+
214+
**Output:**
215+
```
216+
Instance: odoo-myproject-staging
217+
Remote: git@github.com:org/repo.git
218+
Branch: main (abc1234)
219+
Unit: active (running) since 2026-03-09 08:12:03
220+
```
221+
222+
---
223+
224+
## Workflow Guide
225+
226+
### New instance setup
227+
228+
1. Ensure the remote server has the required tools installed
229+
2. Create or update `deploy.yml` with the instance configuration
230+
3. Run `deploy configure <instance_name>`
231+
4. Verify with `deploy status <instance_name>`
232+
233+
### Regular deployment
234+
235+
1. Run `deploy update <instance_name>`
236+
2. Monitor output for hook results and update status
237+
3. Verify with `deploy status <instance_name>`
238+
239+
### Always ask for confirmation before production deployments
240+
241+
Before running any `deploy update` or `deploy configure` on a **production** instance, present the full command to the user and wait for explicit approval.
242+
243+
---
244+
245+
## Global Options
246+
247+
| Option | Default | Description |
248+
|--------|---------|-------------|
249+
| `--config FILE` | `deploy.yml` | Path to config file (local machine) |
250+
| `--verbose` | `False` | Print each remote command and its output |

0 commit comments

Comments
 (0)