docs: document coolify aio cleanup
This commit is contained in:
thibaud-leclere
parent
d01a384832
commit
3de3a14d06
2 changed files with 314 additions and 0 deletions
242
docs/superpowers/plans/2026-05-06-coolify-aio-cleanup.md
Normal file
242
docs/superpowers/plans/2026-05-06-coolify-aio-cleanup.md
Normal file
|
|
@ -0,0 +1,242 @@
|
||||||
|
# Coolify AIO Cleanup Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** Reduce this Hoppscotch fork to the packages and deployment files required for Coolify AIO.
|
||||||
|
|
||||||
|
**Architecture:** Keep the existing AIO Docker architecture and remove code outside that deployment path. The workspace remains a pnpm monorepo, but `pnpm-workspace.yaml`, root scripts, and compose services are narrowed to the retained packages.
|
||||||
|
|
||||||
|
**Tech Stack:** pnpm workspaces, Docker Compose, multi-stage Dockerfile, NestJS backend, Vue/Vite frontends, Prisma, Caddy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: Remove Non-AIO Packages
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Delete: `packages/hoppscotch-desktop`
|
||||||
|
- Delete: `packages/hoppscotch-agent`
|
||||||
|
- Delete: `packages/hoppscotch-cli`
|
||||||
|
- Delete: `packages/hoppscotch-relay`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Delete package directories**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -rf packages/hoppscotch-desktop packages/hoppscotch-agent packages/hoppscotch-cli packages/hoppscotch-relay
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: directories are absent from `find packages -maxdepth 1 -mindepth 1 -type d`.
|
||||||
|
|
||||||
|
- [ ] **Step 2: Verify retained package list**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
find packages -maxdepth 1 -mindepth 1 -type d -printf '%f\n' | sort
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected output contains only:
|
||||||
|
|
||||||
|
```text
|
||||||
|
codemirror-lang-graphql
|
||||||
|
hoppscotch-backend
|
||||||
|
hoppscotch-common
|
||||||
|
hoppscotch-data
|
||||||
|
hoppscotch-js-sandbox
|
||||||
|
hoppscotch-kernel
|
||||||
|
hoppscotch-selfhost-web
|
||||||
|
hoppscotch-sh-admin
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task 2: Narrow Workspace And Root Scripts
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `pnpm-workspace.yaml`
|
||||||
|
- Modify: `package.json`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Replace workspace glob**
|
||||||
|
|
||||||
|
Set `pnpm-workspace.yaml` to:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
packages:
|
||||||
|
- 'packages/codemirror-lang-graphql'
|
||||||
|
- 'packages/hoppscotch-backend'
|
||||||
|
- 'packages/hoppscotch-common'
|
||||||
|
- 'packages/hoppscotch-data'
|
||||||
|
- 'packages/hoppscotch-js-sandbox'
|
||||||
|
- 'packages/hoppscotch-kernel'
|
||||||
|
- 'packages/hoppscotch-selfhost-web'
|
||||||
|
- 'packages/hoppscotch-sh-admin'
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Simplify root scripts**
|
||||||
|
|
||||||
|
Keep scripts that make sense for the retained AIO deployment:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"dev": "pnpm -r do-dev",
|
||||||
|
"gen-gql": "cross-env GQL_SCHEMA_EMIT_LOCATION='../../../gql-gen/backend-schema.gql' pnpm -r generate-gql-sdl",
|
||||||
|
"generate": "pnpm -r do-build-prod",
|
||||||
|
"start": "http-server packages/hoppscotch-selfhost-web/dist -p 3000",
|
||||||
|
"lint": "pnpm -r do-lint",
|
||||||
|
"typecheck": "pnpm -r do-typecheck",
|
||||||
|
"lintfix": "pnpm -r do-lintfix",
|
||||||
|
"pre-commit": "pnpm -r do-lint && pnpm -r do-typecheck",
|
||||||
|
"test": "pnpm -r do-test"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Remove `generate-ui`, because it is not a Coolify deployment concern.
|
||||||
|
|
||||||
|
### Task 3: Simplify Docker Compose For Coolify AIO
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `docker-compose.yml`
|
||||||
|
- Delete: `docker-compose.deploy.yml`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Replace compose file with AIO deployment**
|
||||||
|
|
||||||
|
Keep only `hoppscotch-db` and `hoppscotch-aio`. Preserve the AIO command:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
hoppscotch-db:
|
||||||
|
image: postgres:15
|
||||||
|
user: postgres
|
||||||
|
environment:
|
||||||
|
POSTGRES_USER: postgres
|
||||||
|
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-testpass}
|
||||||
|
POSTGRES_DB: ${POSTGRES_DB:-hoppscotch}
|
||||||
|
volumes:
|
||||||
|
- hoppscotch-db:/var/lib/postgresql/data
|
||||||
|
healthcheck:
|
||||||
|
test:
|
||||||
|
[
|
||||||
|
"CMD-SHELL",
|
||||||
|
"sh -c 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}'",
|
||||||
|
]
|
||||||
|
interval: 5s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 10
|
||||||
|
|
||||||
|
hoppscotch-aio:
|
||||||
|
container_name: hoppscotch-aio
|
||||||
|
restart: unless-stopped
|
||||||
|
build:
|
||||||
|
dockerfile: prod.Dockerfile
|
||||||
|
context: .
|
||||||
|
target: aio
|
||||||
|
environment:
|
||||||
|
DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD:-testpass}@hoppscotch-db:5432/${POSTGRES_DB:-hoppscotch}
|
||||||
|
env_file:
|
||||||
|
- ./.env
|
||||||
|
depends_on:
|
||||||
|
hoppscotch-db:
|
||||||
|
condition: service_healthy
|
||||||
|
command:
|
||||||
|
[
|
||||||
|
"sh",
|
||||||
|
"-c",
|
||||||
|
"pnpm exec prisma migrate deploy && node /usr/src/app/aio_run.mjs",
|
||||||
|
]
|
||||||
|
ports:
|
||||||
|
- "3000:3000"
|
||||||
|
- "3100:3100"
|
||||||
|
- "3170:3170"
|
||||||
|
- "3200:3200"
|
||||||
|
- "3080:80"
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
hoppscotch-db:
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Delete internal deploy compose**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -f docker-compose.deploy.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: `test ! -f docker-compose.deploy.yml` exits with status 0.
|
||||||
|
|
||||||
|
### Task 4: Remove Non-Coolify Root Files And Update Docs
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Delete: `firebase.json`
|
||||||
|
- Delete: `firestore.indexes.json`
|
||||||
|
- Delete: `firestore.rules`
|
||||||
|
- Delete: `netlify.toml`
|
||||||
|
- Delete: `CODEOWNERS`
|
||||||
|
- Delete: `CODE_OF_CONDUCT.md`
|
||||||
|
- Delete: `CONTRIBUTING.md`
|
||||||
|
- Delete: `SECURITY.md`
|
||||||
|
- Delete: `TRANSLATIONS.md`
|
||||||
|
- Modify: `README.md`
|
||||||
|
- Modify: `.dockerignore`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Delete unused root files**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -f firebase.json firestore.indexes.json firestore.rules netlify.toml CODEOWNERS CODE_OF_CONDUCT.md CONTRIBUTING.md SECURITY.md TRANSLATIONS.md
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Replace README with Coolify-focused content**
|
||||||
|
|
||||||
|
Use a short README covering local compose and Coolify variables.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Keep Docker context lean**
|
||||||
|
|
||||||
|
Update `.dockerignore` so it excludes local files, build outputs, package test
|
||||||
|
artifacts, docs, and removed platform files while keeping source and lockfiles.
|
||||||
|
|
||||||
|
### Task 5: Validate And Commit
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Verify all modified files
|
||||||
|
|
||||||
|
- [ ] **Step 1: Check references to removed packages**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rg -n "hoppscotch-(desktop|agent|cli|relay)|@hoppscotch/cli|docker-compose.deploy|firebase|netlify" .
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: no deployment-relevant references remain. Historical references in
|
||||||
|
lockfile may remain until `pnpm install` updates the lockfile.
|
||||||
|
|
||||||
|
- [ ] **Step 2: Validate compose syntax**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose config
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: command exits 0 and prints a normalized compose config.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Update lockfile if possible**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm install --lockfile-only
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: command exits 0 and removes deleted packages from `pnpm-lock.yaml`.
|
||||||
|
|
||||||
|
- [ ] **Step 4: Commit**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A
|
||||||
|
git add -f docs/superpowers/specs/2026-05-06-coolify-aio-cleanup-design.md docs/superpowers/plans/2026-05-06-coolify-aio-cleanup.md
|
||||||
|
git commit -m "chore: trim repo for coolify aio"
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,72 @@
|
||||||
|
# Coolify AIO Cleanup Design
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Prepare this Hoppscotch fork as an internal AIO deployment repository for Coolify.
|
||||||
|
The repository should keep only the web app, backend, admin UI, database
|
||||||
|
migration path, and workspace packages required to build the all-in-one Docker
|
||||||
|
image.
|
||||||
|
|
||||||
|
## Keep
|
||||||
|
|
||||||
|
- `packages/hoppscotch-selfhost-web`: main self-hosted web app and webapp server.
|
||||||
|
- `packages/hoppscotch-backend`: NestJS backend, Prisma schema, migrations, and
|
||||||
|
backend Caddy config.
|
||||||
|
- `packages/hoppscotch-sh-admin`: self-host admin dashboard used by AIO.
|
||||||
|
- `packages/hoppscotch-common`: shared frontend UI/runtime code used by the app.
|
||||||
|
- `packages/hoppscotch-data`: shared data models and migrations used by frontend
|
||||||
|
packages and sandbox code.
|
||||||
|
- `packages/hoppscotch-kernel`: runtime abstraction used by the web app/common
|
||||||
|
package.
|
||||||
|
- `packages/hoppscotch-js-sandbox`: script/test sandbox used by the web app.
|
||||||
|
- `packages/codemirror-lang-graphql`: CodeMirror GraphQL language package used by
|
||||||
|
`hoppscotch-common`.
|
||||||
|
- Root Docker/Caddy/runtime files required by `prod.Dockerfile`.
|
||||||
|
|
||||||
|
## Remove
|
||||||
|
|
||||||
|
- Desktop-only code: `packages/hoppscotch-desktop`.
|
||||||
|
- Agent-only code: `packages/hoppscotch-agent`.
|
||||||
|
- CLI-only code: `packages/hoppscotch-cli`.
|
||||||
|
- Rust relay source: `packages/hoppscotch-relay`.
|
||||||
|
- Deprecated Docker services that build removed package Dockerfiles.
|
||||||
|
- Deployment/config files for platforms outside Coolify AIO: Firebase and Netlify.
|
||||||
|
- Upstream community repository documents that do not serve the internal fork.
|
||||||
|
|
||||||
|
## Docker Deployment Shape
|
||||||
|
|
||||||
|
Coolify should use the main `docker-compose.yml`. The compose file should expose
|
||||||
|
one supported deployment mode:
|
||||||
|
|
||||||
|
- `hoppscotch-aio`: built from `prod.Dockerfile` target `aio`.
|
||||||
|
- `hoppscotch-db`: local PostgreSQL 15 service for deployments that do not use an
|
||||||
|
external database.
|
||||||
|
|
||||||
|
The AIO command keeps the existing production behavior:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pnpm exec prisma migrate deploy && node /usr/src/app/aio_run.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
This preserves automatic migrations on container start while keeping Coolify
|
||||||
|
configuration small.
|
||||||
|
|
||||||
|
## Build Strategy
|
||||||
|
|
||||||
|
Keep the upstream multi-stage `prod.Dockerfile` structure for the first cleanup.
|
||||||
|
It is already tied to workspace postinstall scripts, Prisma generation, GraphQL
|
||||||
|
generation, the webapp server Go build, and Caddy. The aggressive cleanup comes
|
||||||
|
from removing packages and narrowing the workspace, not from rewriting the
|
||||||
|
Dockerfile copy/install strategy in the same change.
|
||||||
|
|
||||||
|
Add or keep a Docker ignore file that excludes VCS metadata, local caches,
|
||||||
|
dependency folders, build outputs, test artifacts, docs, and removed platform
|
||||||
|
files from the Docker build context.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
- Verify `pnpm-workspace.yaml` lists only retained packages.
|
||||||
|
- Verify root scripts do not invoke removed packages.
|
||||||
|
- Verify `docker-compose.yml` references only retained services and files.
|
||||||
|
- Verify the AIO Docker config is syntactically valid with `docker compose config`.
|
||||||
|
- Run a focused package install/build check if dependencies are available locally.
|
||||||
Loading…
Reference in a new issue