Deploying a Full-Stack App

Environment variables, managed databases, builds, preview deployments, domains, and post-deploy checks on common platforms.

Est. 35 min Updated Suggest a fix
// Part 01 — Deployment model

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.

ComponentTypical responsibilityConfiguration to protect
Web frontend / Next.jsPages, server rendering, route handlersAuth secrets, provider key, database URL
Express APIREST services and business rulesSession secret, database URL, allowed origin
Managed PostgreSQLDurable application recordsDatabase credentials and network access
Model providerAI generation serviceProvider API key and usage controls
💡 Note
Choose the smallest architecture that meets your needs. Two app services may be appropriate when Next.js and Express have distinct responsibilities, but each extra service adds deployment, networking, monitoring, and failure modes.
// Part 02 — Environments

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.

.env.example
bash
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-account

This 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.

⚠️ Important
Environment variables are not automatically secret just because they are variables. A framework can inline public-prefixed variables into client assets; consult its current configuration rules and verify the built output.
// Part 03 — Prepare the app

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.

release-checks.sh
bash
# 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.

// Part 04 — Database deployment

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.

  1. Create isolated development, preview, and production database targets.
  2. Store each environment’s connection string in its secret manager.
  3. Review migration SQL and run it against a representative non-production database.
  4. Back up production and define a rollback or forward-fix plan before a risky change.
  5. Deploy, verify migration completion, then check an authenticated read and write path.
🎯 Pro Tip
A successful web build does not prove the database schema is current or reachable. Include migration status and a safe database connectivity check in release verification.
// Part 05 — Deploy and preview

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.

deployment-smoke-test.sh
bash
# 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.

// Part 06 — Operate

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.

SignalWhat it can revealFirst response
HTTP error rateA broken route or upstream dependencyCheck deploy version and correlated request IDs
Request latencySlow database, provider, or overloaded runtimeTrace the slow dependency and compare by route
Database connectionsPooling or concurrency pressureReview instance count and connection strategy
AI usage and failuresUnexpected spend or provider instabilityCheck limits, model configuration, and provider status
// Part 07 — Pitfalls

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.

// Part 08 — Practice

Ship the Study Planner with a Safe Release Checklist

Practice

A repeatable production deployment

  1. Choose a hosting layout for Next.js, any separate Express API, managed PostgreSQL, and the model provider.
  2. Create an environment-variable inventory and separate local, preview, and production values.
  3. Prepare a reviewed database migration and document backup and restore checks.
  4. Add a health endpoint and smoke tests for public, authenticated, and rejected requests.
  5. Configure structured logs and alerts for errors, latency, database pressure, and model usage without recording secrets.
  6. 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.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...