QueryLayer universal installation plan

Status: proposed

Last updated: September 3, 2026

This document is the proposed universal installation contract for QueryLayer. It replaces "Docker installation" as the default architecture with hosting-path adapters: shared-host ZIP, Vercel + Supabase, native shared-hosting MySQL, and VPS/Docker as the Advanced path. Until a path is verified, the public documentation labels it honestly as in development; the release acceptance matrix at the end of this document is the gate.

#1. Product objective

QueryLayer must install into infrastructure the customer already uses.

The customer chooses their hosting provider. QueryLayer detects its capabilities and selects the appropriate deployment method. Customers should not have to understand Docker, Node.js, PostgreSQL, environment variables, webhooks, or build pipelines.

"Self-hosted" means customer-controlled infrastructure and accounts. It does not mean "must operate a Docker server."

#2. Non-negotiable installation tests

#SiteGround shared hosting

A customer must be able to:

1. Download querylayer.zip.
2. Upload it to public_html using SiteGround File Manager.
3. Extract the archive.
4. Visit https://example.com/querylayer/setup/.
5. Pass an automatic hosting compatibility check.
6. Create the administrator account.
7. Connect or provision the required customer-owned services through browser authorization.
8. Connect the existing website and publishing destination.
9. Create, preview, and publish a page.
10. Sign in later at /querylayer/admin/.

No SSH, shell commands, Node.js, Docker, Git, or manual configuration-file editing may be required.

SiteGround does not support Node.js on ordinary shared or cloud hosting, so the installer and hosting bridge must run on PHP-compatible shared hosting. SiteGround compatibility reference

#Vercel and Supabase

A customer must be able to:

1. Click Deploy QueryLayer.
2. Sign in to Vercel.
3. Select an existing website project or create one.
4. Sign in to Supabase.
5. Select or create a Supabase project.
6. Approve installation.
7. Allow QueryLayer to configure migrations, functions, secrets, scheduled work, deploy hooks, and callbacks.
8. Complete the administrator wizard.
9. Publish a test page.

No separate server or Docker installation may be required.

#Hostinger

QueryLayer must support both:

• ZIP installation through File Manager for conventional PHP hosting.
• Native Node application deployment where the customer's plan supports it.

The wizard must detect the available path instead of asking the customer to determine it.

#3. Supported deployment profiles

#Profile A: Shared hosting with customer-owned Supabase

This is the first SiteGround-compatible release.

• QueryLayer's installer, administration shell, configuration bridge, and webhook endpoints run as PHP.
• The administration interface ships as prebuilt static assets.
• Database, authentication, governed APIs, and scheduled work run in the customer's Supabase project.
• Astro builds run through the customer's GitHub Actions account.
• Finished static files deploy to the existing host through SFTP or the provider's deployment API.
• Secrets remain server-side and are removed from installer state after provisioning.

This profile satisfies the upload → extract → wizard requirement without requiring Node on the web host.

#Profile B: Vercel with customer-owned Supabase

• The public Astro site and QueryLayer administration deploy to Vercel.
• Supabase provides the customer-owned database, authentication, functions, Vault, and scheduler.
• The installer configures preview deployments, production deploy hooks, webhook verification, and environment variables.
• The customer controls both accounts.

#Profile C: Native shared-hosting runtime

This profile removes the external Supabase requirement.

• PHP application runtime.
• MySQL or MariaDB storage adapter.
• Native password authentication and sessions.
• Host cron executes scheduled publishing and maintenance.
• The same governance, revision, approval, audit, and rollback contracts must hold.

This is required for customers who want every QueryLayer component inside their traditional hosting account.

#Profile D: VPS or Docker

The existing Docker Compose distribution remains available for developers, agencies, and operators who want full infrastructure control. It is labeled Advanced installation, not the default path.

#4. Distribution package

The public release must produce a signed querylayer.zip containing:

querylayer/
├── index.php
├── setup/
│   └── index.php
├── admin/
│   └── prebuilt application assets
├── api/
│   ├── setup.php
│   ├── webhook.php
│   ├── health.php
│   └── cron.php
├── runtime/
│   ├── hosting detection
│   ├── configuration storage
│   ├── Supabase connector
│   ├── MySQL connector
│   └── delivery adapters
├── migrations/
├── templates/
├── .htaccess
└── VERSION

The package must not require npm install, Composer, compilation, or shell access on the customer's server.

#5. Browser setup wizard

#Step 1: Hosting check

Automatically inspect:

• PHP version and extensions.
• HTTPS availability.
• Writable configuration and storage directories.
• Outbound HTTPS requests.
• Cron availability.
• Database availability.
• Maximum upload and execution limits.
• Existing website type and directory structure.

Show plain-language results such as:

Your SiteGround account can run QueryLayer using Supabase and GitHub builds.

Do not show infrastructure terminology unless the user opens advanced details.

#Step 2: Administrator

• Create the first local owner.
• Enforce strong password requirements.
• Store credentials using the selected authentication adapter.
• Prevent further setup access after completion.

#Step 3: Data location

Offer:

• Connect Supabase
• Create a Supabase project
• Use this hosting account's MySQL database
• Advanced Docker/VPS connection

The wizard performs migrations and verifies the resulting schema.

#Step 4: Website connection

Detect or request:

• Primary domain.
• Existing site directory.
• GitHub repository, when used.
• Astro project location.
• Current hosting provider.
• Preview and production destinations.

The website must remain at its existing host unless the customer explicitly chooses to move it.

#Step 5: Publishing connection

Configure the appropriate adapter:

• Vercel deploy hook and signed lifecycle webhook.
• GitHub Actions build followed by SFTP deployment.
• Hostinger deployment API.
• Local build for Node-capable hosting.
• Direct PHP rendering where supported.

#Step 6: Verification

The wizard must run a real acceptance flow:

1. Create an immutable draft.
2. Preview the exact revision.
3. Publish it.
4. Trigger the selected build pipeline.
5. Verify the production URL.
6. Confirm rollback readiness.

Setup is not complete until every required step passes or produces a clear, actionable blocker.

#6. Engineering workstreams

#Workstream 1: Correct the product contract

• Replace "Docker installation" as the default architecture.
• Define hosting providers as deployment adapters.
• Define customer-owned Supabase, native MySQL, and Docker storage profiles.
• Preserve identical governance semantics across every profile.
• Label unfinished installation paths honestly.

Exit criterion: Architecture, roadmap, installer, and public documentation describe the same product.

#Workstream 2: Extract portable application services

Move business rules out of Supabase-specific RPC and edge-function assumptions into portable service contracts:

• Authentication.
• Revisions and publishing pointers.
• Proposals and approvals.
• Audit history.
• Scheduled work.
• Forms and submissions.
• Integration secrets.
• Delivery lifecycle.
• Backup and recovery.

Provide PostgreSQL/Supabase and MySQL implementations.

Exit criterion: The same conformance suite passes against both data backends.

#Workstream 3: Build the PHP bootstrap runtime

Implement:

• Hosting capability detection.
• Secure configuration storage.
• Setup-session recovery.
• Supabase provisioning connector.
• MySQL provisioning connector.
• Signed cron endpoint.
• Signed publishing webhook.
• Installer lock and recovery token.
• Safe uninstall and backup preparation.

Exit criterion: The setup wizard loads on SiteGround without Node or Docker.

#Workstream 4: Produce the browser wizard

Build the complete host-first installation experience with:

• Provider detection.
• OAuth account connections.
• Resumable setup.
• Secret redaction.
• Clear compatibility messages.
• Automated acceptance testing.
• Recovery from interrupted OAuth, deployment, or migration steps.

Exit criterion: A test user can complete installation without consulting documentation.

#Workstream 5: Build publishing adapters

Implement and test:

• Vercel.
• GitHub Actions plus SFTP.
• Hostinger.
• Generic SFTP.
• Local Node build.
• Provider-neutral deployment receipts.

Every adapter must distinguish build acceptance from verified production delivery.

Exit criterion: Publishing, failure reporting, retry, and rollback work consistently across providers.

#Workstream 6: Package updates and recovery

Implement:

• Signed release manifests.
• In-browser update checks.
• Automatic backup before updates.
• Database migration preflight.
• Failed-update rollback.
• Installer integrity verification.
• Recovery without QueryLayer-operated infrastructure.

Exit criterion: An owner can update or recover QueryLayer without SSH.

#7. Delivery sequence

#Milestone 0: Documentation correction

• Replace the current universal Docker requirements.
• Add a hosting-path chooser before requirements.
• Mark Docker as advanced.
• Mark Vercel/Supabase and shared-host ZIP installation as in development until verified.

#Milestone 1: SiteGround ZIP proof

• Prebuilt admin assets.
• PHP setup entry point.
• Hosting checks.
• Customer-owned Supabase connection.
• GitHub Actions and SFTP delivery.
• First draft → preview → publish test.

#Milestone 2: Vercel/Supabase one-click path

• Account authorization.
• Project selection or creation.
• Automated Supabase provisioning.
• Automated Vercel configuration.
• Production verification.

#Milestone 3: Hostinger support

• PHP ZIP path.
• Native Node path when available.
• Provider-specific deployment configuration.

#Milestone 4: Native MySQL shared hosting

• MySQL storage implementation.
• Native authentication.
• PHP scheduled processing.
• Full conformance and migration testing.

#Milestone 5: Public universal installer

• Signed ZIP.
• Upgrade and recovery system.
• Compatibility matrix.
• Clean-room release verification.
• Nontechnical usability testing.

#8. Security requirements

• No service-role key, database password, OAuth token, deploy hook, or SFTP credential may reach browser storage or public assets.
• Setup secrets must be encrypted at rest and discarded when no longer needed.
• The setup wizard must permanently lock after owner creation.
• Webhooks and cron endpoints require signed, replay-resistant requests.
• Installer files must deny direct access to configuration and migration internals.
• Every provider mutation must be idempotent and auditable.
• Failed setup must be resumable without duplicating projects, users, hooks, or migrations.

#9. Release acceptance matrix

A release is not ready until all of these pass:

#10. Definition of done

QueryLayer's installation work is complete only when:

• A normal business owner can install it without infrastructure knowledge.
• The existing website remains on the customer's chosen host.
• Uploading and extracting a ZIP is sufficient to start shared-host setup.
• Vercel and Supabase users can connect their existing accounts directly.
• No terminal is required for normal installation, publishing, updates, backup, or recovery.
• A real production publish is verified before the wizard reports success.
• The same revision, governance, audit, security, and rollback guarantees hold across every supported hosting profile.