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