Deploying a Full-Stack App
Environment variables, managed databases, builds, preview deployments, domains, and post-deploy checks on common platforms.
Know Which Pieces Run Where
A full-stack app can run its Next.js interface and server routes on a platform such as Vercel, while a Node and Express API may run on a long-lived application platform such as Render. PostgreSQL can run as a managed database on a provider that handles backups and operations. These are examples, not endorsements or requirements: compare regional availability, operational needs, pricing, support, and data-handling obligations before choosing.
Draw the request path before deploying: a student's browser requests the web app, the web server reads or writes the database, and a server-only AI route calls the model provider. Each service needs a network path, a secure configuration, observability, and an owner. Avoid exposing a database directly to a public browser.
| Component | Typical responsibility | Configuration to protect |
|---|---|---|
| Web frontend / Next.js | Pages, server rendering, route handlers | Auth secrets, provider key, database URL |
| Express API | REST services and business rules | Session secret, database URL, allowed origin |
| Managed PostgreSQL | Durable application records | Database credentials and network access |
| Model provider | AI generation service | Provider API key and usage controls |
Separate Local, Preview and Production Settings
Keep configuration separate by environment. Local development may use a local database, previews should use isolated test data, and production should use its own database and provider credentials. Environment variables configure services without embedding deployment-specific values into the source. Store secrets in the platform's secret manager, limit who can read them, and rotate credentials if exposure is suspected.
DATABASE_URL=postgresql://user:password@localhost:5432/study_planner
SESSION_SECRET=replace-with-a-long-random-secret
APP_ORIGIN=http://localhost:3000
OPENAI_API_KEY=add-a-server-side-provider-key
LLM_MODEL=select-a-model-configured-for-your-accountThis example file documents required variable names and placeholder values only. Keep real local files out of version control. Do not put secret values in variables intended to be exposed to the browser. Preview and production environments should not accidentally share a production database or a developer's personal API key.
Make Builds and Startup Behavior Predictable
Before deploying, make sure the application builds from a clean checkout, reads required configuration at startup, and has a clear start command. Pin dependencies through the package manifest and lockfile, run checks in continuous integration, and ensure the runtime listens on the host and port expected by the platform. Keep build-time and run-time secrets distinct where the platform supports that separation.
# Run the checks used by this repository before release
npm ci
npx tsc --noEmit
npm run lint
npm run build
# Confirm the app responds to its health endpoint after startup
curl -i "$APP_URL/health"Use the actual scripts available in your repository; this sequence is illustrative and does not imply every project has a lint script or health endpoint. A health check should report whether the process can serve requests and, if it checks dependencies, distinguish readiness from liveness so a temporary database interruption does not trigger a restart loop.
Provision PostgreSQL and Apply Migrations Safely
Create a managed PostgreSQL instance in a region appropriate to your users and operational constraints. Configure network access and credentials narrowly, enable backups, and understand how to restore a backup before you need one. Verify connection limits and pooling behavior, especially if your app creates many short-lived server instances.
Apply reviewed migrations as part of a controlled release, then deploy code compatible with the new schema. For changes that cannot be applied atomically while old and new code run together, use an expand-and-contract sequence: add compatible structures first, migrate data, switch code, and remove old structures in a later release.
- Create isolated development, preview, and production database targets.
- Store each environment’s connection string in its secret manager.
- Review migration SQL and run it against a representative non-production database.
- Back up production and define a rollback or forward-fix plan before a risky change.
- Deploy, verify migration completion, then check an authenticated read and write path.
Use Preview Deployments Without Production Data
A preview deployment lets a team review an isolated change before it reaches production. Give it its own environment settings and test records. Do not use production student data in previews unless a documented, approved process permits it and protects the data. Review authentication callbacks, allowed origins, and any provider webhook URLs for each environment.
Vercel is commonly used for Next.js deployments, and Render can host web services and related application components. Deployment workflows and platform features change, so follow current provider documentation for build commands, runtime settings, custom domains, and network configuration. A successful platform deploy is not the same as a product acceptance test.
# Use non-sensitive test data in a preview environment
curl -i "$APP_URL/health"
curl -i "$APP_URL/api/plans"
# Confirm a rejected request does not disclose private records
curl -i "$APP_URL/api/plans/unknown-test-id"Smoke tests should confirm expected status codes, safe headers, and basic dependencies without printing secrets. A protected endpoint should reject unauthenticated access; a test that expects private data should use an explicitly provisioned test account.
Observe Errors, Latency and Resource Use
Production work continues after launch. Capture structured logs with a request or trace identifier, timestamp, severity, route, and safe context. Do not log passwords, cookies, authorization headers, full prompts, or sensitive database rows. Track request error rates, latency, database connection pressure, migration outcomes, and model usage. Set alerts that lead to an actionable response rather than generating noise.
Have a rollback plan for the application and a separate recovery plan for data. Backups are useful only if restore has been tested. For model calls, log safe usage and latency metadata, enforce provider budgets and per-user limits, and retain enough identifiers to investigate failures without retaining unnecessary prompt content.
| Signal | What it can reveal | First response |
|---|---|---|
| HTTP error rate | A broken route or upstream dependency | Check deploy version and correlated request IDs |
| Request latency | Slow database, provider, or overloaded runtime | Trace the slow dependency and compare by route |
| Database connections | Pooling or concurrency pressure | Review instance count and connection strategy |
| AI usage and failures | Unexpected spend or provider instability | Check limits, model configuration, and provider status |
Common Mistakes
Using one database and key for every environment
Why: Preview tests can alter real records or spend production quota.
Fix: Separate settings, credentials, and data for local, preview, and production.
Committing a real .env file
Why: Secrets persist in repository history and can be copied by others.
Fix: Commit a placeholder example, ignore real files, and rotate any exposed credential.
Deploying code before its schema is compatible
Why: Old and new app instances can fail while a migration is incomplete.
Fix: Plan compatible migrations and coordinate release ordering.
Assuming deploy success proves the app works
Why: The app can still lack secrets, database access, auth callbacks, or valid domains.
Fix: Run smoke tests and review logs and health signals after release.
Ship the Study Planner with a Safe Release Checklist
Practice
A repeatable production deployment
- Choose a hosting layout for Next.js, any separate Express API, managed PostgreSQL, and the model provider.
- Create an environment-variable inventory and separate local, preview, and production values.
- Prepare a reviewed database migration and document backup and restore checks.
- Add a health endpoint and smoke tests for public, authenticated, and rejected requests.
- Configure structured logs and alerts for errors, latency, database pressure, and model usage without recording secrets.
- Write a short rollback procedure and identify who responds to a failed deployment.
Hint: Use current Vercel, Render, and database-provider documentation for platform-specific setup. Do not run deployment commands against production while experimenting.
🎯 Key Takeaways
- ✓Map the web, API, database, and AI-provider request path before choosing hosting.
- ✓Separate local, preview, and production secrets and data.
- ✓Review migrations and database recovery plans as part of deployment, not as an afterthought.
- ✓Use preview deployments with isolated test data and environment-specific callbacks.
- ✓Verify the live app with smoke tests after each release.
- ✓Monitor errors, latency, database capacity, and AI usage while keeping sensitive data out of logs.
- Use the current official Vercel, Render, PostgreSQL, and managed database documentation for provider-specific deployment and networking steps.
Next
What comes next
Plan and build a small SaaS app with authentication, a database, an AI feature, tests and deployment, and present it as a portfolio project.
Lesson 14 · Full-Stack Capstone — AI-Powered SaaS App →HELP US IMPROVE
How was this lesson?
Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.
Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.
Discussion
0Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.
