ahmido
ce0615a9c1
## Summary - move the Laravel application into `apps/platform` and keep the repository root for orchestration, docs, and tooling - update the local command model, Sail/Docker wiring, runtime paths, and ignore rules around the new platform location - add relocation quickstart/contracts plus focused smoke coverage for bootstrap, command model, routes, and runtime behavior ## Validation - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PlatformRelocation` - integrated browser smoke validated `/up`, `/`, `/admin`, `/admin/choose-workspace`, and tenant route semantics for `200`, `403`, and `404` ## Remaining Rollout Checks - validate Dokploy build context and working-directory assumptions against the new `apps/platform` layout - confirm web, queue, and scheduler processes all start from the expected working directory in staging/production - verify no legacy volume mounts or asset-publish paths still point at the old root-level `public/` or `storage/` locations Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #213
175 lines
6.4 KiB
Markdown
175 lines
6.4 KiB
Markdown
# Quickstart: Platform Relocation to apps/platform
|
|
|
|
## Purpose
|
|
|
|
Use this guide after implementation to verify that the relocated platform app boots, serves assets, runs queue workers, passes focused tests, and still works with repo tooling.
|
|
|
|
## Prerequisites
|
|
|
|
1. Start from a clean checkout on `182-platform-relocation`.
|
|
2. Ensure the relocated app exists at `apps/platform`.
|
|
3. Ensure the app env has the compose bridge configured if Sail requires it, for example through `SAIL_FILES` pointing to the repo-root `docker-compose.yml`.
|
|
|
|
## File Placement Contract Check
|
|
|
|
Before runtime validation, confirm the published topology contract is still true:
|
|
|
|
1. Repo root owns repo-wide docs, specs, scripts, editor settings, agent config, and `docker-compose.yml`.
|
|
2. `apps/platform` owns Laravel runtime files, application code, tests, build inputs, public entry files, and app-local env files.
|
|
3. Reviewed root-level exceptions such as `.gitignore`, `.dockerignore`, and `scripts/platform-sail` are documented as orchestration or compatibility-only concerns rather than a second application root.
|
|
|
|
## Timing And Evidence Capture
|
|
|
|
Use this protocol when validating the time-based success criteria:
|
|
|
|
1. For setup timing, start the clock at the first documented setup command with no `apps/platform/.env`, `apps/platform/vendor/`, `apps/platform/node_modules/`, or app build artifacts present.
|
|
2. Stop the setup clock when the CLI smoke passes and `http://localhost/admin/choose-workspace` returns the expected pre-move auth or workspace-selection response.
|
|
3. For rollback timing, start the clock at the first documented rollback command and stop when rollback cleanup is complete and the restored local workflow reaches its documented sanity state.
|
|
4. Record the operating system, container runtime, whether Docker images were already available locally, and any intentionally skipped optional checks.
|
|
|
|
## Canonical Setup Flow
|
|
|
|
```bash
|
|
cd apps/platform
|
|
composer install
|
|
cp .env.example .env
|
|
./vendor/bin/sail up -d
|
|
./vendor/bin/sail artisan key:generate
|
|
./vendor/bin/sail artisan migrate
|
|
```
|
|
|
|
Compatibility-only root helper for repo tooling:
|
|
|
|
```bash
|
|
./scripts/platform-sail up -d
|
|
```
|
|
|
|
## CLI Smoke
|
|
|
|
```bash
|
|
cd apps/platform
|
|
./vendor/bin/sail artisan --version
|
|
./vendor/bin/sail artisan migrate:status
|
|
./vendor/bin/sail artisan about
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- Laravel boots from `apps/platform`.
|
|
- Artisan resolves the relocated app without manual path overrides.
|
|
- Database connectivity is intact.
|
|
|
|
## Build Smoke
|
|
|
|
```bash
|
|
cd apps/platform
|
|
./vendor/bin/sail npm run build
|
|
```
|
|
|
|
Optional dev-server check:
|
|
|
|
```bash
|
|
cd apps/platform
|
|
./vendor/bin/sail npm run dev
|
|
```
|
|
|
|
Expected outcome:
|
|
|
|
- Vite builds without missing manifest or path-resolution failures.
|
|
- Filament theme assets still resolve from the relocated app.
|
|
|
|
## Web And Panel Smoke
|
|
|
|
Check these routes in a browser after the stack is up:
|
|
|
|
1. `http://localhost/up`
|
|
2. `http://localhost/`
|
|
3. `http://localhost/admin`
|
|
4. `http://localhost/admin/choose-workspace`
|
|
5. One representative entitled tenant route such as `http://localhost/admin/t/{tenant}/backup-sets`
|
|
6. One representative non-member or wrong-scope tenant route that should still deny as not found (`404`)
|
|
7. `http://localhost/system`
|
|
|
|
Expected outcome:
|
|
|
|
- No 500 error caused by base-path, manifest, or storage path resolution.
|
|
- Auth redirects remain consistent with pre-move behavior.
|
|
- Choose-workspace navigation and a representative tenant navigation path resolve without broken assets or stale root-path assumptions.
|
|
- Tenant authorization semantics remain consistent with pre-move behavior, including preserved `404` versus `403` outcomes for the validated route fixtures.
|
|
- Admin, tenant, and system shells load with the expected assets.
|
|
|
|
## Auth, Workspace, And Route-Semantics Smoke
|
|
|
|
Validate these behaviors explicitly as part of the smoke pack:
|
|
|
|
1. `/admin` reaches the same login or auth-gate behavior as before the move.
|
|
2. `/admin/choose-workspace` preserves the existing chooser or redirect behavior.
|
|
3. A representative entitled tenant route loads through the relocated app without route or asset regressions.
|
|
4. Automated route smoke preserves deny-as-not-found (`404`) for non-member tenant access and preserves capability-only (`403`) denials where those fixtures already exist.
|
|
|
|
## Queue Smoke
|
|
|
|
```bash
|
|
cd apps/platform
|
|
./vendor/bin/sail ps
|
|
./vendor/bin/sail logs queue --tail=50
|
|
```
|
|
|
|
Then execute one representative queue-backed platform flow and verify that the queue worker handles it without root-path errors.
|
|
|
|
## Test Smoke
|
|
|
|
Run the smallest focused relocation regression pack available after implementation. At minimum, execute a compact Pest smoke run from `apps/platform`:
|
|
|
|
```bash
|
|
cd apps/platform
|
|
./vendor/bin/sail artisan test --compact
|
|
```
|
|
|
|
If the implementation introduces a smaller relocation-focused pack in `tasks.md`, run that first and then decide whether a full compact run is necessary.
|
|
|
|
## Tooling Smoke
|
|
|
|
Validate at least one repo-level tool flow after the move:
|
|
|
|
1. One repaired VS Code task that delegates to `apps/platform`
|
|
2. One MCP flow via `.vscode/mcp.json` or `opencode.json`
|
|
|
|
Expected outcome:
|
|
|
|
- The tool resolves the relocated app path explicitly.
|
|
- No hidden root-relative `vendor/bin/sail` or `artisan` assumption remains.
|
|
|
|
## Rollback Flow
|
|
|
|
```bash
|
|
# Preserve any local app env changes you still need
|
|
cp apps/platform/.env /tmp/tenantatlas.platform.env.backup
|
|
|
|
# Stop and clean local runtime state
|
|
cd apps/platform
|
|
./vendor/bin/sail down -v
|
|
cd ../..
|
|
rm -rf apps/platform/vendor apps/platform/node_modules apps/platform/public/build
|
|
rm -f apps/platform/public/hot
|
|
```
|
|
|
|
Then revert the relocation commit on your working branch, restore the correct env file for the restored topology, and rerun the documented setup flow for that revision.
|
|
|
|
## Rollback Readiness Check
|
|
|
|
Before rollout approval, confirm the documentation covers:
|
|
|
|
1. Git rollback steps
|
|
2. `.env` recovery
|
|
3. `vendor/`, `node_modules`, and build artifact cleanup
|
|
4. Docker cleanup or volume recovery
|
|
5. Open-branch communication for rebases or merges
|
|
6. Timing evidence for setup and rollback success criteria
|
|
|
|
## External Rollout Questions
|
|
|
|
1. Does Dokploy build from repo root while running Laravel commands from `apps/platform`?
|
|
2. Which working directory do the staging and production web, queue, and scheduler processes use after the move?
|
|
3. Do any existing Dokploy volume mounts or asset-publish steps still point at the pre-move root `public/` or `storage/` trees?
|