From ed44d3544028785f5a1b03f5e842f3af04901167 Mon Sep 17 00:00:00 2001 From: "gpt-engineer-app[bot]" <159125892+gpt-engineer-app[bot]@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:28:31 +0000 Subject: [PATCH 1/3] Changes --- README.md | 130 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 85 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 70b7c82..b9bdf62 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,113 @@ -# Welcome to your Lovable project +# madewithlovable -## Project info +A step-by-step guide to de-risking your [Lovable](https://lovable.dev) project for production use. -**URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID +Lovable is excellent for agility and speed-to-market, but shipping AI-generated code to production without guardrails introduces structural risks — from unreviewed changes breaking infrastructure to vendor lock-in on hosting. This project provides a repeatable playbook to mitigate those risks while keeping the benefits of rapid AI-assisted development. -## How can I edit this code? +**Live app:** [made-with.lovable.app](https://made-with.lovable.app) -There are several ways of editing your application. +--- -**Use Lovable** +## What This Is -Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting. +An interactive wizard that walks you through six steps to establish ownership, safety, and operational independence over a Lovable-built application. Each step is optional (except the first), so you can adopt only what makes sense for your project. -Changes made via Lovable will be committed automatically to this repo. +--- -**Use your preferred IDE** +## The Six Steps -If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable. +### 1. Project URL -The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating) +Enter your Lovable project URL. The wizard extracts the project UUID and uses it to generate context-aware links throughout the remaining steps (e.g., direct links to your project's GitHub settings, Knowledge configuration, etc.). -Follow these steps: +### 2. Connect to GitHub -```sh -# Step 1: Clone the repository using the project's Git URL. -git clone +Export your Lovable project to a GitHub repository. This is the foundation of everything else — without version control, you can't review changes, run CI/CD, or deploy independently. Lovable syncs commits bidirectionally, so you keep the AI editor workflow while gaining full Git history. -# Step 2: Navigate to the project directory. -cd +### 3. Guardrails -# Step 3: Install the necessary dependencies. -npm i +Add a `LOVABLE.md` file to your repository root that scopes what the AI is allowed to modify. This file acts as a contract: Lovable (and any other AI agent) should only touch application source code inside `src/`, frontend build configuration, and database migrations. Protected files include: -# Step 4: Start the development server with auto-reloading and an instant preview. -npm run dev -``` +- Infrastructure (`Dockerfile`, `docker-compose.yml`, `terraform/`) +- CI/CD pipelines (`.github/`) +- The guardrails file itself (`LOVABLE.md`) + +The guardrails are enforced in two ways: +1. **At authoring time** — by registering `LOVABLE.md` as custom knowledge in your Lovable project settings, so the AI respects the boundaries while generating code. +2. **At merge time** — by the CI/CD pipeline's automated review (see Step 6). + +### 4. Local Development Setup + +Run the full application locally using Docker, independent of Lovable's preview environment. This enables: + +- Working in your preferred IDE or with other AI coding agents (Cursor, Claude Code, etc.) +- Offline development +- Running the test suite locally +- Building production artifacts + +The setup is a single command: `docker-compose up`, which starts a development server on `localhost:8081` with hot-reloading and volume-mounted source code. + +### 5. Production Self-Hosting -**Edit a file directly in GitHub** +Decouple your production environment from Lovable's hosting. The guide covers: -- Navigate to the desired file(s). -- Click the "Edit" button (pencil icon) at the top right of the file view. -- Make your changes and commit the changes. +- **Creating a `production` branch** in GitHub to separate what's deployed from what's being developed. +- **AWS S3 + CloudFront** as the hosting infrastructure (private S3 bucket as origin, CloudFront for delivery). Terraform configuration is provided, but manual setup via the AWS Console works too. +- **Building and deploying** — running `npm run build` (locally or via Docker) and uploading the `dist/` folder to S3. +- **Lovable Cloud (Supabase) considerations** — by default, self-hosted frontends share the same backend. For a dedicated production database, a manual migration to a managed Supabase instance is required. -**Use GitHub Codespaces** +**Key technical notes:** +- CloudFront must have `index.html` set as the Default root object. +- Lovable occasionally desyncs `package-lock.json` from `package.json`. If `npm ci` fails, use `npm install` and commit the updated lock file. -- Navigate to the main page of your repository. -- Click on the "Code" button (green button) near the top right. -- Select the "Codespaces" tab. -- Click on "New codespace" to launch a new Codespace environment. -- Edit files directly within the Codespace and commit and push your changes once you're done. +### 6. CI/CD Pipeline -## What technologies are used for this project? +Three GitHub Actions workflows automate the release process: -This project is built with: +| Workflow | Trigger | Purpose | +|---|---|---| +| `initiate-release.yml` | Manual (workflow_dispatch) | Creates a PR from `main` → `production` with an auto-generated changelog | +| `ci-guardrails.yml` | PR to `production` | Claude reviews the diff against `LOVABLE.md` guardrails — approves and merges if clean, requests changes if violations are found | +| `deploy.yml` | Push to `production` | Builds the app, syncs to S3, and invalidates the CloudFront cache | -- Vite -- TypeScript -- React -- shadcn-ui -- Tailwind CSS +**Required setup:** +- Install the [Claude GitHub app](https://github.com/apps/claude) on your repository +- Add the `ANTHROPIC_API_KEY` secret (from [Anthropic Console](https://console.anthropic.com/settings/keys)) +- Add AWS IAM credentials as secrets (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) with permissions for S3 and CloudFront +- Add GitHub Actions **variables**: `S3_BUCKET` and `CLOUDFRONT_DISTRIBUTION_ID` +- If using Lovable Cloud: add `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLISHABLE_KEY` as secrets +- Enable "Allow GitHub Actions to create and approve pull requests" in your organization/repository settings -## How can I deploy this project? +**The release flow:** +1. A non-technical user (or anyone) triggers the "Move main to production" workflow manually. +2. Claude generates a release PR with a summary of changes. +3. The guardrails workflow automatically reviews the PR diff — if all changes are within scope, it approves and merges. If guardrail violations are detected, it requests changes with inline comments. +4. On merge to `production`, the deploy workflow builds and publishes to AWS. -Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish. +--- -## Can I connect a custom domain to my Lovable project? +## Tech Stack -Yes, you can! +- [React](https://react.dev) + [TypeScript](https://www.typescriptlang.org) +- [Vite](https://vitejs.dev) +- [Tailwind CSS](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com) +- [Framer Motion](https://www.framer.com/motion/) for step transitions -To connect a domain, navigate to Project > Settings > Domains and click Connect Domain. +--- + +## Getting Started + +```sh +git clone +cd +npm install +npm run dev +``` + +Or with Docker: + +```sh +docker-compose up +``` -Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain) +The app will be available at `http://localhost:8081`. From 1efe7be4282ab80700e7c9c7007929f99d1cdc09 Mon Sep 17 00:00:00 2001 From: "gpt-engineer-app[bot]" <159125892+gpt-engineer-app[bot]@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:29:09 +0000 Subject: [PATCH 2/3] Changes --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b9bdf62..1e70bd9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ A step-by-step guide to de-risking your [Lovable](https://lovable.dev) project f Lovable is excellent for agility and speed-to-market, but shipping AI-generated code to production without guardrails introduces structural risks — from unreviewed changes breaking infrastructure to vendor lock-in on hosting. This project provides a repeatable playbook to mitigate those risks while keeping the benefits of rapid AI-assisted development. -**Live app:** [made-with.lovable.app](https://made-with.lovable.app) +- **Lovable-hosted:** [made-with.lovable.app](https://made-with.lovable.app) +- **Self-hosted (AWS):** [d12vini1os6dc2.cloudfront.net](https://d12vini1os6dc2.cloudfront.net) --- From ac66e1acc491dea6bfbbfe606ad90db6da58979c Mon Sep 17 00:00:00 2001 From: "gpt-engineer-app[bot]" <159125892+gpt-engineer-app[bot]@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:51:00 +0000 Subject: [PATCH 3/3] Changes --- src/components/steps/StepProjectUrl.tsx | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/components/steps/StepProjectUrl.tsx b/src/components/steps/StepProjectUrl.tsx index 3fcbb09..5758d7d 100644 --- a/src/components/steps/StepProjectUrl.tsx +++ b/src/components/steps/StepProjectUrl.tsx @@ -41,9 +41,22 @@ export function StepProjectUrl() { ✓ Valid project detected

)} - +
+ + +
); }