Tutorials

SaaS Part 1: Deploy Your App and Database

A complete Next.js SaaS with sign-up, teams, an admin panel and billing, live on Light Cloud with its PostgreSQL database in about 15 minutes.

SaaS Part 1: Deploy Your App and Database
Published

To deploy a SaaS with a database on Light Cloud, fork the tutorial-saas-starter repository, create a PostgreSQL database, and deploy the repository from GitHub. Then set two environment variables: DATABASE_URL with the database's connection string, and AUTH_SECRET with a long random string. The app creates its own tables when it starts, so the first sign-up works straight away, with no email provider or Stripe account yet.

In my run the app was live 6 minutes after I clicked Deploy, and its first sign-up worked straight away.

What you will build

A complete SaaS app, live on a Light Cloud URL:

  • sign-up, sign-in and password reset;
  • teams, called workspaces, with owner, admin and member roles;
  • an onboarding stepper after the first sign-up;
  • an admin panel at /admin;
  • a pricing page and billing, which stay switched off until part 3.

The Rota Planner dashboard on Light Cloud, signed in as Sarah Jones in the Bristol Care Homes workspace, with the Get started checklist and the Free plan

This is part 1 of Start a SaaS on Light Cloud. The series takes the same app all the way to launch:

  1. Deploy your app and database (this part)
  2. Send sign-up emails with Resend
  3. Take payments with Stripe, in test mode
  4. Add your own domain
  5. Add a password-protected staging site
  6. Preview every pull request
  7. Go live with real payments

Source code: github.com/light-cloud-com/tutorial-saas-starter. The app is our Next.js SaaS Starter Kit: Next.js 16, React 19, TypeScript, Better Auth, Drizzle ORM, Tailwind CSS and shadcn/ui.

Before you start

  • A Light Cloud account on the Lite plan or higher. The Free plan has no databases.
  • A GitHub account, connected to Light Cloud. Deploy from GitHub shows how.
  • A terminal with OpenSSL, to make a random secret. It comes with macOS and Linux. On Windows, use Git Bash, which comes with Git for Windows.

You don't need Node.js on your laptop for this part. Light Cloud builds the app.

Step 1: Fork the repository

Open github.com/light-cloud-com/tutorial-saas-starter and click Fork, then Create fork. You get your own copy, so later parts can push changes to it.

Step 2: Create the database

  1. In the Light Cloud console, click New..., then New Database.
  2. Name it saas-db, keep Size at Dev (a shared instance) and Storage at 1 GB, and click Create database. It was ready a few seconds later in my run.

The Create page with the Database tile chosen, the name saas-db, Size Dev, Storage 1 GB, Region Belgium, and the Create database button highlighted

  1. Open the Credentials tab. Under Connection String, choose Connect from: Node.js and click Copy.

The Credentials tab with the user, password and database name hidden, Connect from Node.js and Copy highlighted

The Node.js version of the string already ends with ?sslmode=require&uselibpqcompat=true, which makes the app encrypt its connection, as the database requires. With your own user, password and database name where the dots are, it looks like this:

text
postgresql://u_••••••:••••••••@saas-db-yourworkspace.db.light-cloud.io:5432/db••••••?sslmode=require&uselibpqcompat=true

This is your DATABASE_URL. Keep it private, because it contains the password.

Step 3: Make a session secret

AUTH_SECRET signs sign-in sessions and the links in emails. Any long random string works. Make one:

terminal
$ openssl rand -hex 32
cfd128d18c3df4f1d951527e89d771dc134ad90a77ccf22bbf09dd0a1719f747

On Windows, run it in Git Bash. Yours will be different: use your own, not this one. Anyone who has it can forge a session, so keep it as private as the database password.

Step 4: Deploy the app with its variables

  1. In the console, click New..., then Deploy from GitHub, search for tutorial-saas-starter and pick your fork.

The repository search with tutorial-saas-starter found and highlighted

  1. Light Cloud reads the repository and shows Next.js / Fullstack, with SSR mode (like Vercel) in the reasons and Runs on a server on the app. The size is Micro (512 MB), and the app scales between 0 and 3 instances.

The detection banner Next.js Fullstack and the application card with Name, Root directory, Framework Next.js and Size Micro

  1. Open Advanced - build settings, environment variables, domain, scaling. Under Environment variables, Light Cloud has already listed every variable from the repository's .env.example, each with its comment. Fill in three:
NameValue
DATABASE_URLthe string from step 2. Replace the localhost example value that's there
AUTH_SECRETthe output from step 3
APP_NAMEyour product's name. I used Rota Planner

The environment variables on the create form: DATABASE_URL and AUTH_SECRET filled with their values hidden, APP_URL empty, APP_NAME set to Rota Planner

Leave the others empty. Empty variables aren't sent, and later parts fill in the email and Stripe ones.

  1. Click Deploy. Light Cloud asks Deploy without these variables? and lists the empty ones. They're optional for this app, so click Deploy anyway.

The console opens the app's Production environment and shows each build stage as it runs. The first build installs the dependencies and runs next build in a container, which is the slow part: in my run Building container image took most of the 6 minutes.

The Production environment while deploying, with the build stages Enabling Cloud APIs, Setting up container registry, Cloning repository and Preparing container done, and Building container image running

When it's done, the badge says Deployed and the URL card has your app's address:

The Production overview of tutorial-saas-starter with the Deployed badge and the URL main-tutorial-saas-starter-examples.light-cloud.io

When the app starts, it applies the database migrations before Next.js starts. Open the Logs tab and you'll find this line:

The Logs tab with the line Database migrations are up to date highlighted, followed by Next.js 16 starting and Ready

Step 5: Sign up

Open your app's URL from the Overview tab. Mine is https://main-tutorial-saas-starter-examples.light-cloud.io, and yours ends with your workspace's name instead of examples. The landing page already uses the APP_NAME you set:

The Rota Planner landing page: Launch your SaaS this week, not this quarter, with Get started free and See pricing

  1. Click Get started, enter your name, email and a password, and click Create account. I signed up as a test user, Sarah Jones.

The Create your account form with Name Sarah Jones, an email address and a hidden password

  1. The onboarding stepper asks for a workspace name. I used Bristol Care Homes. Click Continue.

Onboarding step 1, Name your workspace, with Bristol Care Homes entered

  1. It offers to invite teammates. Click Skip for now, then Go to dashboard.

The first account to sign up becomes the admin, so open /admin now. It lists every user and workspace, and lets you disable a user or sign in as one.

The admin panel listing one user, Sarah Jones (you), with the Admin role, one workspace and joined 18 Nov 2026

The app normally sends a welcome email when someone signs up. It has no email provider yet, so it prints the email to the logs instead. Search the Logs tab for email:

The Logs tab searched for email, with the line Not sent, RESEND_API_KEY is not set highlighted

text
[email] Not sent, RESEND_API_KEY is not set. To: sarah.jones@example.com
Subject: Welcome to Rota Planner
Hi Sarah Jones,
Thanks for signing up to Rota Planner. Your dashboard has a short checklist to get you going.
[email] end

Part 2 connects Resend, so those emails reach real inboxes and new accounts have to verify their address.

Check the health endpoint

The app has a health check that also tests the database:

terminal
$ curl https://main-tutorial-saas-starter-examples.light-cloud.io/api/health
{"status":"ok","database":"ok"}

What it costs

The app scales to zero: with nobody using it, no instance runs, and the Warm Instances card on the overview says idle is not billed. The price of that is a cold start. My first request after the deploy took 3.1 seconds while an instance started, and the next one 0.6 seconds. Pricing lists the plan and the Dev database.

How many connections?

Every running instance of the app opens its own pool of database connections. The tutorial repository keeps that pool at 3, in src/lib/db/index.ts, because a Dev database allows 10 connections per user. Three instances use 9 and leave one for you. If you raise Max instances, lower the pool size to match. Too many connections? explains the numbers.

Troubleshooting

If the app doesn't start, open the Logs tab and look for one of these errors.

DATABASE_URL is not set

The variable is missing. Add it under Production, Settings, Environment Variables, and save. Saving deploys the app again.

pg_hba.conf rejects connection ... no encryption

DATABASE_URL has no SSL setting. Add ?sslmode=require&uselibpqcompat=true to the end.

unable to verify the first certificate

DATABASE_URL ends with ?sslmode=require only. Add &uselibpqcompat=true.

Signing in works, then you're signed out after a redeploy

AUTH_SECRET changed, so the old sessions no longer match it. Set it once and keep it.