Smart Deploy

Highlights

Table of Contents

• Highlights
• The problem
• What Smart Deploy does
• Workflow
• Core experience
• Architecture overview
• Tech stack
• Quick start
• Production notes
• Access control
• Environment variables reference
• Repo guides
• Scripts
• License

The problem

Most deployment tools force an uncomfortable tradeoff:

• A PaaS is easy to use, but it hides too much of the real deploy.
• Raw cloud infrastructure gives full control, but it exposes too much surface area at once.
• Solo developers and small teams often need something in the middle.

Smart Deploy is built for that middle ground. The goal is not to hide infrastructure. The goal is to make it understandable enough that you can ship and learn at the same time.

What Smart Deploy does

• Lets you bring your own Dockerfile, docker-compose.yml, and Nginx config, or generate a starting point from the repo
• Shows a blueprint view before deploy so you can inspect the deployment path
• Explains how each generated or existing infrastructure file is used in the deploy
• Keeps logs, health, status, and preview output connected to the same deployment workflow
• Supports AWS and GCP deployment paths while keeping the deploy surface grounded in real infrastructure concepts

Workflow

Smart Deploy is organized around three steps:

1. Define it Write or generate the infrastructure files for your app.
2. Preview it Inspect the blueprint view and review the deployment path before anything runs.
3. Deploy it Start the deploy once the plan makes sense, then follow logs, health, and preview output.

Core experience

Where it fits

Smart Deploy targets the gap between convenience and control:

• A PaaS is easy to use, but it hides too much of the real deploy.
• Raw cloud infrastructure gives full control, but it exposes too much surface at once.
• Smart Deploy sits in the middle: ship from a guided workflow without losing sight of containers, compose, and routing.

Blueprint view

The blueprint view is the center of the product. It exists to answer one question before deploy:

What exactly is going to happen to this app?

It shows:

• which services will run
• how containers are built and started
• how services connect
• how traffic is routed
• which generated artifacts are part of the deploy

Generated infrastructure review

Smart Deploy treats infrastructure files as first-class product output, not hidden implementation details.

• Dockerfile shows how images are built
• docker-compose.yml shows how services run together
• nginx.conf shows how requests are routed

The product makes these files visible so the deployment stays inspectable.

Architecture overview

The Next.js app hosts sign-in, the repository and dashboard UI, API routes, and the orchestration that drives deploys end to end.

Tech stack

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS 4
• shadcn/ui
• Supabase
• Better Auth
• GraphQL + REST API routes
• WebSocket worker for long-running deploy operations
• AWS SDK and GCP integrations
• Vitest and Playwright

Quick start

1. Clone the repo

git clone https://github.com/anirudh-makuluri/smart-deploy.git
cd smart-deploy

2. Install dependencies

npm install

3. Set up Supabase

Create a Supabase project and run supabase/schema.sql.

Detailed guide:

• docs/SUPABASE_SETUP.md

4. Configure environment variables

cp .env.example .env

Minimum variables for local access:

Variables needed for scan and artifact flows:

Variables needed for AWS deploys:

5. Approve a user

Sign-in is allowlist-based. Add your email to approved_users before signing in.

insert into public.approved_users (email, name)
values ('you@example.com', 'Your Name')
on conflict (email)
do update set name = excluded.name;

Unapproved sign-in attempts are stored in waiting_list.

6. Start the app and worker

npm run start-all

Or run them separately:

npm run dev
npm run ws

Then open http://localhost:3000.

Production notes

Docker Compose

cp .env.example .env
docker compose up --build -d

The default Compose setup starts:

• app on port 3000
• websocket on port 4001

Split deployment

One supported setup is:

• deploy the Next.js app to Vercel
• deploy the WebSocket worker to Render with Dockerfile.websocket
• set NEXT_PUBLIC_WS_URL to the worker URL
• set WS_ALLOWED_ORIGINS on the worker
• keep BETTER_AUTH_SECRET identical in both services
• PostHog browser traffic goes through /ph by default; only override NEXT_PUBLIC_POSTHOG_HOST if you need a different proxy target

The browser no longer falls back to the app host in production, so NEXT_PUBLIC_WS_URL must be set to the actual worker endpoint.

Health endpoints:

• /health for infrastructure liveness
• /healthz for authenticated app-aware checks

Access control

• Allowed users are stored in approved_users
• Rejected sign-in attempts are stored in waiting_list
• Browser access to the worker uses short-lived signed WebSocket tokens
• WS_ALLOWED_ORIGINS can further restrict which frontends can connect to the worker

Environment variables reference

See .env.example for the full template.

Repo guides

• docs/SUPABASE_SETUP.md
• docs/AWS_SETUP.md
• docs/GCP_SETUP.md
• docs/CUSTOM_DOMAINS.md
• docs/SELF_HOSTING.md
• docs/TROUBLESHOOTING.md
• docs/FAQ.md
• docs/MULTI_SERVICE_DETECTION.md

Scripts

License

MIT