@codewizard-dt/bootstrap 3.2.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cli.js +0 -5
- package/lib/hooks/README.md +14 -5
- package/lib/hooks/lib/command-parse.js +28 -0
- package/lib/hooks/package-install-consent.js +60 -2
- package/lib/scripts/README.md +19 -11
- package/lib/scripts/bootstrap-prefs.js +20 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +9 -0
- package/lib/skills/README.md +1 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +137 -0
- package/lib/skills/roadmap-assess/SKILL.md +51 -13
- package/package.json +2 -4
- package/.github/workflows/docker-harness.yml +0 -26
- package/.github/workflows/security.yml +0 -24
- package/.gitleaks.toml +0 -15
- package/lib/prompts/setup-deployment.md +0 -322
- package/lib/scripts/setup-deployment.sh +0 -113
- package/raw/guides/deployment-strategy.md +0 -448
|
@@ -1,448 +0,0 @@
|
|
|
1
|
-
# Docker Compose Deployment with GitHub Actions
|
|
2
|
-
|
|
3
|
-
End-to-end guide: build images on GitHub Actions, push to GHCR, auto-deploy to a Linux VPS via a self-hosted runner. No inbound firewall ports required on the VPS.
|
|
4
|
-
|
|
5
|
-
### Target quick-reference
|
|
6
|
-
|
|
7
|
-
| Target | When to run |
|
|
8
|
-
|---|---|
|
|
9
|
-
| `make ports` | Check which URLs/ports the stack is using |
|
|
10
|
-
| `make login` | First-time GHCR auth on a new machine or VPS |
|
|
11
|
-
| `make dev` | Day-to-day local development (hot-reload, builds from source) |
|
|
12
|
-
| `make up` | Start production stack from pre-built GHCR images |
|
|
13
|
-
| `make down` | Stop and remove all containers |
|
|
14
|
-
| `make ps` | Check container health/status |
|
|
15
|
-
| `make push` | Build and push prod images manually (CI bypass) |
|
|
16
|
-
| `make deploy` | Full manual deploy: sync files to VPS + pull + restart |
|
|
17
|
-
| `make deploy-pull` | Run on VPS directly after files are already synced |
|
|
18
|
-
| `make ssh-alias` | Add/update the `~/.ssh/config` entry for the VPS |
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## Architecture
|
|
23
|
-
|
|
24
|
-
- **GitHub Actions** (cloud) builds Docker images on every push to `main` and pushes them to GHCR.
|
|
25
|
-
- **GHCR** stores versioned images (`latest` + semver tag).
|
|
26
|
-
- **Self-hosted runner** (daemon on the VPS) picks up the `deploy` job after the build succeeds, pulls the new images, and restarts the stack.
|
|
27
|
-
- **VPS** runs only pre-built images — it never builds anything.
|
|
28
|
-
- **Local dev** uses a Docker Compose overlay to build from source.
|
|
29
|
-
|
|
30
|
-
```
|
|
31
|
-
git push main
|
|
32
|
-
└── GitHub Actions: build job
|
|
33
|
-
├── builds backend / frontend / caddy images
|
|
34
|
-
├── pushes :latest + :<version> to GHCR
|
|
35
|
-
└── triggers deploy job (self-hosted runner on VPS)
|
|
36
|
-
├── docker compose pull
|
|
37
|
-
└── docker compose up -d --wait
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
---
|
|
41
|
-
|
|
42
|
-
## Prerequisites
|
|
43
|
-
|
|
44
|
-
- Docker Engine and Docker Compose v2 on the VPS (`docker compose` subcommand)
|
|
45
|
-
- SSH access to VPS as root
|
|
46
|
-
- GitHub repository (private — see Security Notes)
|
|
47
|
-
- GitHub CLI (`gh`) installed locally and on the VPS (for GHCR auth)
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## Part 1 — Docker Compose Structure
|
|
52
|
-
|
|
53
|
-
### Three compose files
|
|
54
|
-
|
|
55
|
-
**`docker-compose.yml`** — production base. All services use pre-built GHCR images. No `build:` context. This is what runs on the VPS.
|
|
56
|
-
|
|
57
|
-
```yaml
|
|
58
|
-
services:
|
|
59
|
-
backend:
|
|
60
|
-
image: ghcr.io/<ORG>/<PROJECT>-backend:latest
|
|
61
|
-
frontend:
|
|
62
|
-
image: ghcr.io/<ORG>/<PROJECT>-frontend:latest
|
|
63
|
-
caddy:
|
|
64
|
-
image: ghcr.io/<ORG>/<PROJECT>-caddy:latest
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
**`docker-compose.build.yml`** — local dev overlay. Adds `build:` context and source volume mounts. Used with:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
docker compose -f docker-compose.yml -f docker-compose.build.yml up --build --wait
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
**Additional overlays** (optional) — for services not always needed (e.g. local ML sidecars). Layered on top as needed.
|
|
74
|
-
|
|
75
|
-
### Production Dockerfiles
|
|
76
|
-
|
|
77
|
-
Create `Dockerfile.prod` for each service:
|
|
78
|
-
|
|
79
|
-
- Multi-stage build: builder stage installs deps and compiles; runtime stage is lean.
|
|
80
|
-
- Set `ENV NODE_ENV=production` in the runtime stage.
|
|
81
|
-
- Use `npm install` (not `npm ci`) in Docker builder stages — `npm ci` silently omits platform-specific native bindings when the lock was generated on a different OS.
|
|
82
|
-
- Never run dev servers in production containers. For static frontends: build with the framework, serve `dist/` with `serve` or nginx. Install `wget` in the runtime image for Docker healthchecks.
|
|
83
|
-
- For backends: compile to `dist/`, run with `node`.
|
|
84
|
-
- Install `openssl` if the project uses Prisma.
|
|
85
|
-
|
|
86
|
-
### Reverse proxy (Caddy)
|
|
87
|
-
|
|
88
|
-
If using Caddy, create a `Dockerfile.caddy` that copies the `Caddyfile` into `FROM caddy:2-alpine` and push it to GHCR as another service image. Do not use `tls internal` for public domains — Caddy will provision a Let's Encrypt cert automatically. Ensure port 80 is open on the VPS for the ACME HTTP-01 challenge.
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## Part 2 — GitHub Actions Workflows
|
|
93
|
-
|
|
94
|
-
### Build and push: `.github/workflows/build.yml`
|
|
95
|
-
|
|
96
|
-
Triggers on push to `main`. Builds each service image in a matrix and pushes two tags (`:latest` and `:<version>`). After all images push, the `deploy` job runs on the self-hosted runner.
|
|
97
|
-
|
|
98
|
-
```yaml
|
|
99
|
-
name: Build & Push
|
|
100
|
-
|
|
101
|
-
on:
|
|
102
|
-
push:
|
|
103
|
-
branches: [main]
|
|
104
|
-
|
|
105
|
-
env:
|
|
106
|
-
REGISTRY: ghcr.io
|
|
107
|
-
OWNER: <ORG>
|
|
108
|
-
|
|
109
|
-
jobs:
|
|
110
|
-
build:
|
|
111
|
-
runs-on: ubuntu-latest
|
|
112
|
-
permissions:
|
|
113
|
-
contents: read
|
|
114
|
-
packages: write
|
|
115
|
-
strategy:
|
|
116
|
-
matrix:
|
|
117
|
-
include:
|
|
118
|
-
- image: <PROJECT>-backend
|
|
119
|
-
context: ./backend
|
|
120
|
-
dockerfile: ./backend/Dockerfile.prod
|
|
121
|
-
- image: <PROJECT>-frontend
|
|
122
|
-
context: ./frontend
|
|
123
|
-
dockerfile: ./frontend/Dockerfile.prod
|
|
124
|
-
- image: <PROJECT>-caddy
|
|
125
|
-
context: .
|
|
126
|
-
dockerfile: ./Dockerfile.caddy
|
|
127
|
-
|
|
128
|
-
steps:
|
|
129
|
-
- uses: actions/checkout@v4
|
|
130
|
-
|
|
131
|
-
- name: Get version
|
|
132
|
-
id: version
|
|
133
|
-
run: echo "VERSION=$(node -p "require('./backend/package.json').version")" >> $GITHUB_OUTPUT
|
|
134
|
-
|
|
135
|
-
- uses: docker/login-action@v3
|
|
136
|
-
with:
|
|
137
|
-
registry: ${{ env.REGISTRY }}
|
|
138
|
-
username: ${{ github.actor }}
|
|
139
|
-
password: ${{ secrets.GITHUB_TOKEN }}
|
|
140
|
-
|
|
141
|
-
- uses: docker/build-push-action@v6
|
|
142
|
-
with:
|
|
143
|
-
context: ${{ matrix.context }}
|
|
144
|
-
file: ${{ matrix.dockerfile }}
|
|
145
|
-
push: true
|
|
146
|
-
tags: |
|
|
147
|
-
${{ env.REGISTRY }}/${{ env.OWNER }}/${{ matrix.image }}:latest
|
|
148
|
-
${{ env.REGISTRY }}/${{ env.OWNER }}/${{ matrix.image }}:${{ steps.version.outputs.VERSION }}
|
|
149
|
-
cache-from: type=gha
|
|
150
|
-
cache-to: type=gha,mode=max
|
|
151
|
-
|
|
152
|
-
deploy:
|
|
153
|
-
needs: build
|
|
154
|
-
runs-on: [self-hosted, <LABEL>]
|
|
155
|
-
steps:
|
|
156
|
-
- name: Pull new images and restart stack
|
|
157
|
-
working-directory: /opt/<PROJECT>
|
|
158
|
-
run: |
|
|
159
|
-
docker compose pull
|
|
160
|
-
docker compose up -d --wait
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Replace `<ORG>`, `<PROJECT>`, and `<LABEL>` with your values. `<LABEL>` must match the label set when registering the runner (Step 4 below).
|
|
164
|
-
|
|
165
|
-
**Notes:**
|
|
166
|
-
|
|
167
|
-
- `needs: build` ensures deploy only runs after all matrix jobs succeed.
|
|
168
|
-
- `--wait` blocks until all healthchecks pass. Remove it if services have no healthchecks.
|
|
169
|
-
- The version is read from `backend/package.json`. Adjust the path if your layout differs.
|
|
170
|
-
|
|
171
|
-
### Security scanning: `.github/workflows/security.yml`
|
|
172
|
-
|
|
173
|
-
Runs CodeQL SAST and Gitleaks secret detection on every push and PR.
|
|
174
|
-
|
|
175
|
-
```yaml
|
|
176
|
-
name: Security
|
|
177
|
-
|
|
178
|
-
on:
|
|
179
|
-
push:
|
|
180
|
-
branches: [main]
|
|
181
|
-
pull_request:
|
|
182
|
-
branches: [main]
|
|
183
|
-
|
|
184
|
-
jobs:
|
|
185
|
-
codeql:
|
|
186
|
-
name: SAST (CodeQL)
|
|
187
|
-
runs-on: ubuntu-latest
|
|
188
|
-
permissions:
|
|
189
|
-
security-events: write
|
|
190
|
-
actions: read
|
|
191
|
-
contents: read
|
|
192
|
-
steps:
|
|
193
|
-
- uses: actions/checkout@v4
|
|
194
|
-
- uses: github/codeql-action/init@v3
|
|
195
|
-
with:
|
|
196
|
-
languages: javascript-typescript
|
|
197
|
-
- uses: github/codeql-action/autobuild@v3
|
|
198
|
-
- uses: github/codeql-action/analyze@v3
|
|
199
|
-
|
|
200
|
-
secret-scan:
|
|
201
|
-
name: Secret Detection (Gitleaks)
|
|
202
|
-
runs-on: ubuntu-latest
|
|
203
|
-
steps:
|
|
204
|
-
- uses: actions/checkout@v4
|
|
205
|
-
with:
|
|
206
|
-
fetch-depth: 0
|
|
207
|
-
- uses: gitleaks/gitleaks-action@v2
|
|
208
|
-
env:
|
|
209
|
-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
---
|
|
213
|
-
|
|
214
|
-
## Part 3 — VPS Bootstrap
|
|
215
|
-
|
|
216
|
-
Run `lib/scripts/startup.sh` on a fresh Ubuntu 24.04 VPS to install all required dependencies:
|
|
217
|
-
|
|
218
|
-
- zsh, curl, git, make, unzip, openssl
|
|
219
|
-
- Docker CE + docker-compose-plugin
|
|
220
|
-
- GitHub CLI
|
|
221
|
-
- Oh My Zsh; zsh as default shell for root and UID 1000 user
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
bash lib/scripts/startup.sh
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Copy the compose file and secrets to the VPS (do this once manually; never automate `.env` copies):
|
|
228
|
-
|
|
229
|
-
```bash
|
|
230
|
-
scp docker-compose.yml root@<VPS_IP>:/opt/<PROJECT>/
|
|
231
|
-
scp .env.production root@<VPS_IP>:/opt/<PROJECT>/.env
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
The VPS only ever needs `docker-compose.yml` + `.env`. All other config (Caddyfile etc.) should be baked into the images.
|
|
235
|
-
|
|
236
|
-
---
|
|
237
|
-
|
|
238
|
-
## Part 4 — Self-Hosted Runner Setup
|
|
239
|
-
|
|
240
|
-
### Step 1 — Register the runner on GitHub
|
|
241
|
-
|
|
242
|
-
1. Go to **Settings → Actions → Runners → New self-hosted runner**
|
|
243
|
-
2. Select **Linux / x64**
|
|
244
|
-
3. Copy the registration token (single-use, expires in 1 hour)
|
|
245
|
-
|
|
246
|
-
On the VPS:
|
|
247
|
-
|
|
248
|
-
```bash
|
|
249
|
-
mkdir -p /opt/actions-runner && cd /opt/actions-runner
|
|
250
|
-
|
|
251
|
-
curl -fsSL -o runner.tar.gz \
|
|
252
|
-
https://github.com/actions/runner/releases/download/v2.331.0/actions-runner-linux-x64-2.331.0.tar.gz
|
|
253
|
-
tar xzf runner.tar.gz && rm runner.tar.gz
|
|
254
|
-
|
|
255
|
-
./config.sh \
|
|
256
|
-
--url https://github.com/<ORG>/<REPO> \
|
|
257
|
-
--token <REGISTRATION_TOKEN> \
|
|
258
|
-
--name <RUNNER_NAME> \
|
|
259
|
-
--labels <LABEL> \
|
|
260
|
-
--work /opt/actions-runner/_work \
|
|
261
|
-
--unattended
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
| Placeholder | Example |
|
|
265
|
-
|---|---|
|
|
266
|
-
| `<ORG>/<REPO>` | `acme/my-app` |
|
|
267
|
-
| `<REGISTRATION_TOKEN>` | Token from GitHub UI |
|
|
268
|
-
| `<RUNNER_NAME>` | `vps-prod` |
|
|
269
|
-
| `<LABEL>` | `prod` |
|
|
270
|
-
|
|
271
|
-
### Step 2 — Install as a systemd service
|
|
272
|
-
|
|
273
|
-
```bash
|
|
274
|
-
cd /opt/actions-runner
|
|
275
|
-
./svc.sh install
|
|
276
|
-
./svc.sh start
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
Verify:
|
|
280
|
-
|
|
281
|
-
```bash
|
|
282
|
-
systemctl status "actions.runner.*"
|
|
283
|
-
# Expected: active (running)
|
|
284
|
-
systemctl is-enabled "actions.runner.*"
|
|
285
|
-
# Expected: enabled
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
The runner appears as **Idle** under **Settings → Actions → Runners** in the GitHub UI.
|
|
289
|
-
|
|
290
|
-
### Step 3 — Authenticate Docker with GHCR
|
|
291
|
-
|
|
292
|
-
`docker compose pull` needs GHCR credentials persisted on the VPS.
|
|
293
|
-
|
|
294
|
-
**Option A — GitHub CLI:**
|
|
295
|
-
|
|
296
|
-
```bash
|
|
297
|
-
gh auth token | docker login ghcr.io -u <GITHUB_USER> --password-stdin
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
**Option B — Personal Access Token:**
|
|
301
|
-
|
|
302
|
-
Create a PAT with `read:packages` scope at **GitHub → Settings → Developer settings → Tokens (classic)**, then:
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
echo <PAT> | docker login ghcr.io -u <GITHUB_USER> --password-stdin
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
Credentials are stored in `/root/.docker/config.json`. Output should be `Login Succeeded`.
|
|
309
|
-
|
|
310
|
-
### Step 4 — Verify the first deploy
|
|
311
|
-
|
|
312
|
-
1. **Settings → Actions → Runners** — runner shows **Idle**
|
|
313
|
-
2. Push a commit to `main`
|
|
314
|
-
3. Runner status changes to **Running** while the deploy job executes
|
|
315
|
-
4. Deploy job shows a green checkmark in the Actions UI
|
|
316
|
-
5. On the VPS: `docker compose -f /opt/<PROJECT>/docker-compose.yml ps` — `STATUS` column shows `Up` or `healthy`
|
|
317
|
-
|
|
318
|
-
---
|
|
319
|
-
|
|
320
|
-
## Makefile Reference
|
|
321
|
-
|
|
322
|
-
Useful targets for day-to-day operations (keep a `Makefile` in the repo root):
|
|
323
|
-
|
|
324
|
-
```makefile
|
|
325
|
-
-include .env
|
|
326
|
-
export
|
|
327
|
-
|
|
328
|
-
GHCR_REPO = ghcr.io/<ORG>/<PROJECT>
|
|
329
|
-
DROPLET_IP ?= <VPS_IP>
|
|
330
|
-
PROJECT = $(shell basename $(CURDIR))
|
|
331
|
-
|
|
332
|
-
.PHONY: ports ps up dev push deploy deploy-pull ssh-alias login down
|
|
333
|
-
|
|
334
|
-
# --- Helpers ---
|
|
335
|
-
|
|
336
|
-
## ports — print all service URLs based on .env values
|
|
337
|
-
ports:
|
|
338
|
-
@echo "App (HTTPS): https://$(or $(CADDY_DOMAIN),localhost)$(if $(filter-out 443,$(or $(HTTPS_PORT),443)),:$(HTTPS_PORT),)"
|
|
339
|
-
@echo "Backend: http://localhost:$(BACKEND_PORT)"
|
|
340
|
-
@echo "Frontend: http://localhost:$(FRONTEND_PORT)"
|
|
341
|
-
@echo "Database: localhost:$(DB_PORT)"
|
|
342
|
-
|
|
343
|
-
## login — authenticate Docker with GHCR (run once locally and once on the VPS)
|
|
344
|
-
login:
|
|
345
|
-
gh auth token | docker login ghcr.io -u <GITHUB_USER> --password-stdin
|
|
346
|
-
|
|
347
|
-
## ps — show running container status
|
|
348
|
-
ps:
|
|
349
|
-
docker compose ps
|
|
350
|
-
|
|
351
|
-
## down — stop and remove containers
|
|
352
|
-
down:
|
|
353
|
-
docker compose down
|
|
354
|
-
|
|
355
|
-
# --- Local Development ---
|
|
356
|
-
|
|
357
|
-
## dev — build from source with hot-reload bind mounts (Dockerfile.dev)
|
|
358
|
-
dev:
|
|
359
|
-
docker compose -f docker-compose.yml -f docker-compose.build.yml up --wait
|
|
360
|
-
@$(MAKE) --no-print-directory ports
|
|
361
|
-
|
|
362
|
-
# --- Production / CI bypass ---
|
|
363
|
-
|
|
364
|
-
## up — pull latest GHCR images and start the production stack (no build)
|
|
365
|
-
up:
|
|
366
|
-
docker compose pull && docker compose up -d --wait
|
|
367
|
-
|
|
368
|
-
## push — build linux/amd64 prod images and push to GHCR (bypasses CI)
|
|
369
|
-
push:
|
|
370
|
-
docker buildx build --platform linux/amd64 \
|
|
371
|
-
-t $(GHCR_REPO)-backend:latest --push \
|
|
372
|
-
-f backend/Dockerfile.prod backend
|
|
373
|
-
docker buildx build --platform linux/amd64 \
|
|
374
|
-
-t $(GHCR_REPO)-frontend:latest --push \
|
|
375
|
-
-f frontend/Dockerfile.prod frontend
|
|
376
|
-
docker buildx build --platform linux/amd64 \
|
|
377
|
-
-t $(GHCR_REPO)-caddy:latest --push \
|
|
378
|
-
-f Dockerfile.caddy .
|
|
379
|
-
|
|
380
|
-
## deploy — sync compose file + Makefile to VPS then restart
|
|
381
|
-
deploy: deploy-sync
|
|
382
|
-
ssh $(PROJECT) "cd /opt/$(PROJECT) && make deploy-pull"
|
|
383
|
-
|
|
384
|
-
deploy-sync:
|
|
385
|
-
ssh $(PROJECT) "mkdir -p /opt/$(PROJECT)"
|
|
386
|
-
scp docker-compose.yml Makefile $(PROJECT):/opt/$(PROJECT)/
|
|
387
|
-
scp .env.production $(PROJECT):/opt/$(PROJECT)/.env
|
|
388
|
-
scp lib/scripts/setup-runner.sh $(PROJECT):~/setup-runner.sh
|
|
389
|
-
|
|
390
|
-
## setup-runner — upload and run the runner installer on the VPS
|
|
391
|
-
## Usage: make setup-runner RUNNER_TOKEN=<token>
|
|
392
|
-
setup-runner: deploy-sync
|
|
393
|
-
ssh $(PROJECT) "RUNNER_TOKEN=$(RUNNER_TOKEN) REPO_URL=$(REPO_URL) bash ~/setup-runner.sh"
|
|
394
|
-
|
|
395
|
-
## deploy-pull — pull new images and restart (run directly on the VPS)
|
|
396
|
-
deploy-pull: up
|
|
397
|
-
|
|
398
|
-
## ssh-alias — upsert ~/.ssh/config Host entry for the prod server (idempotent)
|
|
399
|
-
## Usage: make ssh-alias DROPLET_IP=1.2.3.4
|
|
400
|
-
ssh-alias:
|
|
401
|
-
@mkdir -p ~/.ssh && touch ~/.ssh/config
|
|
402
|
-
@if grep -q "^Host $(PROJECT)$$" ~/.ssh/config; then \
|
|
403
|
-
awk 'BEGIN{found=0} /^Host $(PROJECT)$$/{found=1} found && /^[[:space:]]+HostName /{sub(/^([[:space:]]+HostName ).*/, " HostName $(DROPLET_IP)"); found=0} {print}' \
|
|
404
|
-
~/.ssh/config > /tmp/.ssh_config_tmp && mv /tmp/.ssh_config_tmp ~/.ssh/config; \
|
|
405
|
-
echo "Updated: Host $(PROJECT) → $(DROPLET_IP)"; \
|
|
406
|
-
else \
|
|
407
|
-
printf "\nHost $(PROJECT)\n HostName $(DROPLET_IP)\n User root\n" >> ~/.ssh/config; \
|
|
408
|
-
echo "Added: Host $(PROJECT) → $(DROPLET_IP)"; \
|
|
409
|
-
fi
|
|
410
|
-
|
|
411
|
-
```
|
|
412
|
-
|
|
413
|
-
---
|
|
414
|
-
|
|
415
|
-
## Sizing Guide
|
|
416
|
-
|
|
417
|
-
| Scenario | VPS |
|
|
418
|
-
|---|---|
|
|
419
|
-
| Small app (≤4 containers, no ML) | $12/mo — 1 vCPU, 2 GB |
|
|
420
|
-
| Medium app (4–8 containers) | $24/mo — 2 vCPU, 4 GB |
|
|
421
|
-
| App with ML sidecars (TTS/STT) | $48/mo — 2 vCPU, 8 GB |
|
|
422
|
-
|
|
423
|
-
---
|
|
424
|
-
|
|
425
|
-
## Security Notes
|
|
426
|
-
|
|
427
|
-
- **Keep the repo private.** Self-hosted runners on public repos are dangerous — fork PRs can execute arbitrary code on the VPS. If the repo must go public, disable fork PR runs: **Settings → Actions → General → Fork pull request workflows from outside collaborators → Require approval**.
|
|
428
|
-
- **Registration tokens are short-lived.** The token from Step 1 is single-use and expires within one hour. The runner exchanges it for a long-lived credential stored in `/opt/actions-runner/.credentials`. To rotate, re-run `config.sh --replace` with a new token.
|
|
429
|
-
- **The runner runs as root** on a single-tenant VPS. If you want a lower-privilege setup, create a dedicated user: `useradd -m -G docker runner`, then re-run `config.sh` and `svc.sh install` as that user.
|
|
430
|
-
- **Never commit `.env` or credentials.** GitLab CI / GitHub Actions secret detection will flag them.
|
|
431
|
-
|
|
432
|
-
---
|
|
433
|
-
|
|
434
|
-
## Troubleshooting
|
|
435
|
-
|
|
436
|
-
| Symptom | Fix |
|
|
437
|
-
|---|---|
|
|
438
|
-
| Runner shows **Offline** | `systemctl restart "actions.runner.*"` |
|
|
439
|
-
| `docker compose pull` — 401 / permission denied | Re-run Step 3 (GHCR auth) |
|
|
440
|
-
| `docker compose pull` — 403 Forbidden (after successful login) | GHCR packages are **private** by default. Go to GitHub → your profile → Packages → each image → Package settings → Change visibility → Public. Or re-login as the **runner** OS user (not root): `su - runner && echo PAT \| docker login ghcr.io -u <user> --password-stdin`. Credentials in root's `~/.docker/config.json` are not visible to the runner service user. |
|
|
441
|
-
| Deploy job stays **Queued** indefinitely | Runner is offline or label mismatch — verify runner is **Idle** in GitHub UI and `runs-on` labels match |
|
|
442
|
-
| `docker compose up --wait` times out | A healthcheck is failing — `docker compose ps` and `docker compose logs <service>` |
|
|
443
|
-
| Images build but wrong version deployed | Confirm `:latest` tag is being pushed and `docker compose pull` is pulling `:latest`, not a pinned digest |
|
|
444
|
-
| `config.sh` — `Permission denied` on `.env` / `_diag` | Runner was configured as root, but `/opt/actions-runner` is owned by root. Create a non-root user first: `useradd -m -G docker runner && chown -R runner:runner /opt/actions-runner`, then `su - runner` before running `config.sh`. Install the service with `./svc.sh install runner` (pass the username). |
|
|
445
|
-
| Caddy container up but site shows `ERR_CONNECTION_REFUSED` — no ports in `docker ps` | Containers were started with a stale compose file that had no port bindings. Run `docker compose up -d --force-recreate` to restart all containers with the current compose config. |
|
|
446
|
-
| `cp: cannot create regular file '/opt/<PROJECT>/...': Permission denied` in deploy job | The runner OS user doesn't own `/opt/<PROJECT>`. Fix: `chown -R runner:runner /opt/<PROJECT>` (run as root on the VPS). |
|
|
447
|
-
| Gitleaks flags fake tokens in test/UAT docs | Add the file path glob and/or token regex to `.gitleaks.toml` under `[allowlist]`. Example: `paths = ['(?i)\.docs/uat/']` |
|
|
448
|
-
| Host-mounted config file causes `not a directory` error on container start | If the config file is baked into the image (e.g. via `COPY` in the Dockerfile), remove the bind-mount volume from `docker-compose.yml`. Docker creates a directory at the mount path when the host file doesn't exist, causing the error on the next start. |
|