refactor: rename hub-guide → code-guide, remove project-specific content
- Rename all references from hub-guide to code-guide - Remove project-specific hub-guide skill (100% Asepharyana Hub specific) - Genericize examples in monorepo, docker, ci-cd, engineering-principles skills - Use generic service names (frontend, api, worker instead of hub, scraper) - Use generic registry paths instead of ghcr.io/asepharyana/asepharyana-hub - Remove project-specific deployment and infrastructure references
This commit is contained in:
asepharyana
@@ -55,16 +55,16 @@ jobs:
|
||||
build:
|
||||
strategy:
|
||||
matrix:
|
||||
service: [scraper, hub]
|
||||
service: [frontend, api]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: |
|
||||
docker build \
|
||||
-f infra/docker/${{ matrix.service }}.Dockerfile \
|
||||
-t ghcr.io/.../${{ matrix.service }}:sha-${{ github.sha }} \
|
||||
-t ghcr.io/.../${{ matrix.service }}:latest \
|
||||
-t ghcr.io/myorg/myproject/${{ matrix.service }}:sha-${{ github.sha }} \
|
||||
-t ghcr.io/myorg/myproject/${{ matrix.service }}:latest \
|
||||
.
|
||||
- run: docker push --all-tags ghcr.io/.../${{ matrix.service }}
|
||||
- run: docker push --all-tags ghcr.io/myorg/myproject/${{ matrix.service }}
|
||||
```
|
||||
|
||||
**Deploy (after build)**
|
||||
@@ -101,7 +101,7 @@ jobs:
|
||||
build:
|
||||
strategy:
|
||||
matrix:
|
||||
service: [scraper, hub, api]
|
||||
service: [frontend, api, worker]
|
||||
fail-fast: false # Let others complete even if one fails
|
||||
```
|
||||
|
||||
@@ -149,10 +149,10 @@ secrets:
|
||||
6. **Security scan** (<5 min) — CodeQL, dependency audit, secret scan
|
||||
7. **Deploy** (<2 min) — SSH, pull, restart
|
||||
|
||||
## Deployment (this repo's pattern)
|
||||
## Deployment Pattern
|
||||
|
||||
1. SSH to VPS (`orangevps`)
|
||||
2. Pull latest images from GHCR
|
||||
1. SSH to deployment target
|
||||
2. Pull latest images from container registry
|
||||
3. Restart specific container (not all)
|
||||
4. Health check after restart
|
||||
5. Rollback if health check fails
|
||||
|
||||
+10
-12
@@ -76,12 +76,11 @@ networks:
|
||||
external: true
|
||||
```
|
||||
|
||||
### Typical Services Layout (this repo)
|
||||
- **Redis:** `shared.yml` — always first
|
||||
- **NATS:** `nats.yml` — JetStream-enabled
|
||||
- **Dapr:** `dapr.yml` — placement service
|
||||
- **Traefik:** `traefik.yml` — reverse proxy
|
||||
- **App + Sidecar:** `app.yml` — service + daprd sidecar
|
||||
### Typical Docker Compose Order
|
||||
- **Data layer:** `db.yml`, `redis.yml` — stateful services first
|
||||
- **Messaging:** `nats.yml`, `rabbitmq.yml` — message brokers
|
||||
- **Infrastructure:** `traefik.yml`, `nginx.yml` — reverse proxy
|
||||
- **Application:** `app.yml` — service containers
|
||||
|
||||
## Security
|
||||
|
||||
@@ -99,17 +98,16 @@ networks:
|
||||
sha-<short-sha> # Immutable — for deterministic rollbacks
|
||||
latest # Mutable — convenience
|
||||
|
||||
# Example (from this repo's CI)
|
||||
ghcr.io/asepharyana/asepharyana-hub/<service>:sha-a1b2c3d
|
||||
ghcr.io/asepharyana/asepharyana-hub/<service>:latest
|
||||
# Example
|
||||
ghcr.io/myorg/myproject/<service>:sha-a1b2c3d
|
||||
ghcr.io/myorg/myproject/<service>:latest
|
||||
```
|
||||
|
||||
## Networking
|
||||
|
||||
- **All containers** join `app-shared-net` (external Docker bridge).
|
||||
- **All containers** join the same Docker network (external bridge).
|
||||
- **DNS resolution** via Docker DNS (container name = hostname).
|
||||
- **Cross-VPS** via Tailscale (`100.64.0.0/10`).
|
||||
- **Expose only needed ports** — Traefik handles external traffic on port 443.
|
||||
- **Expose only needed ports** — reverse proxy handles external traffic on port 443.
|
||||
|
||||
## Debugging
|
||||
|
||||
|
||||
@@ -312,4 +312,4 @@ Never guess, speculate, or assume. **Every claim, suggestion, or piece of code y
|
||||
✅ "I searched for .env and didn't find one. There's a .env.example — maybe that's the template. Could you check?"
|
||||
|
||||
❌ "Dockerfiles are usually in the root"
|
||||
✅ "I found the Dockerfile at: infra/docker/hub.Dockerfile"
|
||||
✅ "I found the Dockerfile at: infra/docker/app.Dockerfile"
|
||||
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
name: hub-guide
|
||||
description: Guide for the Asepharyana Hub monorepo — submodule workflow, infrastructure stack (Traefik, Dapr, NATS, Redis), CI/CD pipelines, adding new services, and debugging tips. Use when working in the asepharyana-hub monorepo, managing submodules, dealing with Docker/infra setup. Detects from code context and project files — not dependent on specific language keywords."
|
||||
---
|
||||
|
||||
# Hub Guide — Asepharyana Hub Monorepo
|
||||
|
||||
## Submodule Workflow
|
||||
|
||||
- Code changes go in the submodule repo, not here. The hub monorepo only tracks submodule pointers.
|
||||
- After pushing changes to a submodule repo, update the pointer here:
|
||||
```bash
|
||||
cd apps/<name> && git checkout main && git pull
|
||||
cd ../.. && git add apps/<name> && git commit -m "chore(deps): update <name> submodule"
|
||||
```
|
||||
- CI/CD auto-updates submodule pointers via `repository_dispatch`. Manual updates are fine for dev.
|
||||
|
||||
### Typical Submodule State
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| `(HEAD)` | Detached HEAD — submodule is at the committed pointer |
|
||||
| `(main)` | On the default branch — you've done `cd apps/name && git checkout main` |
|
||||
| Dirty | Uncommitted changes inside submodule |
|
||||
|
||||
To reset a submodule to its committed pointer:
|
||||
```bash
|
||||
git submodule update --init --recursive apps/<name>
|
||||
```
|
||||
|
||||
## Development Quickstart
|
||||
|
||||
```bash
|
||||
make init-submodules # After fresh clone — fetches all submodules
|
||||
make dev # Start Redis for local dev
|
||||
docker compose -f infra/compose/shared.yml up -d # Full infra stack
|
||||
```
|
||||
|
||||
## Local vs Production
|
||||
|
||||
| Aspect | Local | Production (VPS) |
|
||||
|--------|-------|------------------|
|
||||
| DB | None (or local) | PostgreSQL on `imrnes` via Tailscale |
|
||||
| Redis | `make dev` | Container on `orangevps` |
|
||||
| Traefik | Not running | TLS-terminated on `orangevps` |
|
||||
| DNS | `localhost` | `*.asepharyana.my.id`, `*.asepharya.web.id` |
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### Docker compose validation
|
||||
```bash
|
||||
for f in infra/compose/*.yml; do docker compose -f "$f" config >/dev/null && echo "OK $f"; done
|
||||
```
|
||||
|
||||
### YAML syntax check
|
||||
```bash
|
||||
python -c "import pathlib, yaml; [yaml.safe_load(open(p)) for p in pathlib.Path('infra').rglob('*.yml')]"
|
||||
```
|
||||
|
||||
### Check submodule pointers
|
||||
```bash
|
||||
git submodule status
|
||||
# Leading `-` = not initialized, `+` = different from committed hash, ` ` = matches
|
||||
```
|
||||
|
||||
### Traefik route not working?
|
||||
1. Check `infra/traefik/dynamic/apps.yaml` — router rule + service definition present?
|
||||
2. Container labels in compose file include Traefik config?
|
||||
3. Container on `app-shared-net`?
|
||||
|
||||
## Adding a New Service — Checklist
|
||||
|
||||
1. [ ] Create separate repo for app code
|
||||
2. [ ] `git submodule add <url> apps/<name>`
|
||||
3. [ ] Create Dockerfile in `infra/docker/`
|
||||
4. [ ] Create compose file in `infra/compose/` (app + Dapr sidecar)
|
||||
5. [ ] Add Traefik router in `infra/traefik/dynamic/apps.yaml`
|
||||
6. [ ] Add build job in `.github/workflows/docker-build-push.yml`
|
||||
7. [ ] Verify: `docker compose -f infra/compose/<name>.yml config`
|
||||
|
||||
See `docs/add-new-app.md` for full guide.
|
||||
|
||||
## Monitoring
|
||||
|
||||
- **Dashboard**: `/dashboard` on the hub site (auto-refresh 15s)
|
||||
- **Dashboard API**: `/api/dashboard` — JSON with containers, traces, metrics
|
||||
- **Prometheus**: Auto-discovers containers with `prometheus.io/scrape=true` label via Docker SD
|
||||
- **Jaeger**: Traces via OTLP — check for cross-service latency
|
||||
|
||||
## Infrastructure Files Map
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `infra/compose/*.yml` | One Docker Compose file per service |
|
||||
| `infra/dapr/components/` | Dapr pub/sub, state store component configs |
|
||||
| `infra/docker/*.Dockerfile` | Build files per service |
|
||||
| `infra/traefik/dynamic/apps.yaml` | Traefik route definitions |
|
||||
| `infra/traefik/traefik.yml` | Traefik static config (entrypoints, providers) |
|
||||
| `.github/workflows/` | CI/CD pipelines |
|
||||
| `docs/` | ADRs, deployment guide, new-app guide |
|
||||
|
||||
## Git Hook Scripts
|
||||
|
||||
Located in `scripts/`:
|
||||
- `scripts/cleanup.sh` — prune old Docker images, clean temp files
|
||||
- `scripts/update-deps.sh` — bump dependencies across submodules
|
||||
- `scripts/setup-hooks.sh` — install local git hooks
|
||||
+10
-10
@@ -19,8 +19,8 @@ description: Monorepo best practices — tooling, workspace configuration, share
|
||||
|
||||
```
|
||||
├── apps/
|
||||
│ ├── hub/ # Next.js app (submodule)
|
||||
│ └── scraper/ # Rust API (submodule)
|
||||
│ ├── app1/ # Application (submodule)
|
||||
│ └── app2/ # Another application (submodule)
|
||||
├── packages/ # Shared libraries (when not submodules)
|
||||
├── infra/ # Shared infra config
|
||||
├── pnpm-workspace.yaml
|
||||
@@ -61,13 +61,13 @@ pnpm -r run build
|
||||
- **Explicit `dependencies`** — never rely on hoisting.
|
||||
- **Lock file** (`pnpm-lock.yaml`) committed — immutable installs.
|
||||
|
||||
## Git Submodules (this repo's pattern)
|
||||
## Git Submodules
|
||||
|
||||
```
|
||||
asepharyana-hub/
|
||||
my-monorepo/
|
||||
├── apps/
|
||||
│ ├── hub/ → asepharyana/asepharyana-hub-hub
|
||||
│ └── scraper/ → asepharyana/asepharyana-hub-scraper
|
||||
│ ├── app1/ → org/app1-repo
|
||||
│ └── app2/ → org/app2-repo
|
||||
```
|
||||
|
||||
### Submodule Workflow
|
||||
@@ -79,8 +79,8 @@ git submodule update --init --recursive
|
||||
git submodule foreach git pull origin main
|
||||
|
||||
# Update one submodule
|
||||
cd apps/hub && git checkout main && git pull
|
||||
cd ../.. && git add apps/hub && git commit -m "chore(deps): update hub submodule"
|
||||
cd apps/app1 && git checkout main && git pull
|
||||
cd ../.. && git add apps/app1 && git commit -m "chore(deps): update app1 submodule"
|
||||
git push
|
||||
```
|
||||
|
||||
@@ -107,8 +107,8 @@ on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'apps/hub/**'
|
||||
- 'infra/docker/hub.Dockerfile'
|
||||
- 'apps/app1/**'
|
||||
- 'infra/docker/app1.Dockerfile'
|
||||
```
|
||||
|
||||
### Affected Commands (Nx/Turborepo/Moon)
|
||||
|
||||
Reference in New Issue
Block a user