You have the source code of Next.js Authentication with Better Auth and PostgreSQL. This guide takes it from the zip file to the app running on your own computer, with its database in Docker and your first account signed in.
By the end, the Bookshop app runs at http://localhost:3000, and you’ve created an account with an email address and a password.
Every command and output on this page is real, run with Node.js 26 and Docker Desktop on macOS. The commands are the same in Windows PowerShell, except where a step shows both.
Cost: free to run. Everything runs on your own computer, and the app needs no accounts or API keys. Docker Desktop is free for personal use, education, non-commercial open source projects and small businesses (fewer than 250 employees and less than $10 million in annual revenue); larger organizations and government entities need a paid subscription (Docker Desktop license agreement (opens in a new tab)).
Get the Source Code
Get the complete source code of Next.js Authentication with Better Auth and PostgreSQL on Dewiride Store → (opens in a new tab)
The archive holds the app this guide sets up and runs.
Prerequisites
- Node.js (opens in a new tab) 26 LTS. Check it with
node -v. - Docker Desktop (opens in a new tab), running.
Step 1: Unzip the Source Code
Open a terminal in the folder that holds the zip, such as Downloads, and unzip it:
unzip nextjs-authentication-better-auth-postgresql-1.0.0.zip
Expand-Archive -Path nextjs-authentication-better-auth-postgresql-1.0.0.zip -DestinationPath .
It creates a folder named nextjs-authentication-better-auth-postgresql. Go into it:
cd nextjs-authentication-better-auth-postgresql
The folder holds the app’s code (app, components and lib), compose.yaml for the database, .env.example with the settings, and a README.
Step 2: Install the Packages
npm install downloads the packages the app uses, at the exact versions listed in package-lock.json:
npm install
added 86 packages, and audited 93 packages in 6s
17 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
Step 3: Add Your Settings
The app reads its settings from a file named .env. Create it from the example file:
cp .env.example .env
Copy-Item .env.example .env
Better Auth needs a secret: a long random value it uses to sign and encrypt data, such as session cookies. Its command-line tool makes one (How to Generate a Better Auth Secret explains it):
npx auth@latest secret
The first time, npx asks to install auth: type y. It prints a new secret. Yours is a different value, so it’s hidden here:
npm notice run bookshop@1.0.0 npx
npm notice run 'auth' secret
Add the following to your .env file:
BETTER_AUTH_SECRET=<your-secret>
Open .env in your code editor and paste your secret after BETTER_AUTH_SECRET=. The file then looks like this:
# Settings for the Bookshop. Copy this file to .env and fill in the values.
# A random secret of at least 32 characters. Generate one with: npx auth@latest secret
BETTER_AUTH_SECRET=<your-secret>
# The address the app runs on
BETTER_AUTH_URL=http://localhost:3000
# The PostgreSQL database from compose.yaml
DATABASE_URL=postgres://bookshop:local-only-password@localhost:5435/bookshop
BETTER_AUTH_URL is the address the app runs on, and DATABASE_URL points to the database you start in Step 4. Keep both as they are.
Warning: Keep .env private and out of Git, because it holds your secret. The project’s .gitignore file already keeps it out.
Step 4: Start the Database
compose.yaml describes a PostgreSQL 18 database in Docker. Start it in the background (How to Run PostgreSQL in Docker with Docker Compose explains the file):
docker compose up -d
The first time, Docker downloads the PostgreSQL image first. Then it creates the database’s volume (its storage) and network, and starts it:
[+] up 3/3
✔ Volume better-auth-bookshop_db-data Created 0.0s
✔ Network better-auth-bookshop_default Created 0.0s
✔ Container better-auth-bookshop-db-1 Started 0.2s
The database accepts connections only from your own computer, on port 5435.
Step 5: Create Better Auth’s Tables
Better Auth keeps users, sessions, accounts and verification codes in four tables, and its migrate command creates them (Better Auth Database Tables Explained describes each one). When it asks Are you sure you want to run these migrations?, type y:
npx auth@latest migrate
npm notice run bookshop@1.0.0 npx
npm notice run 'auth' migrate
🔑 The migration will affect the following:
-> name, email, emailVerified, image, createdAt, updatedAt fields on user table.
-> expiresAt, token, createdAt, updatedAt, ipAddress, userAgent, userId fields on session table.
-> accountId, providerId, userId, accessToken, refreshToken, idToken, accessTokenExpiresAt, refreshTokenExpiresAt, scope, password, createdAt, updatedAt fields on account table.
-> identifier, value, expiresAt, createdAt, updatedAt fields on verification table.
✔ Are you sure you want to run these migrations? … yes
🚀 migration was completed successfully!
Step 6: Start the App
npm run dev
npm notice run bookshop@1.0.0 dev
npm notice run next dev
▲ Next.js 16.4.6 (Turbopack)
- Local: http://localhost:3000
- Network: http://192.168.x.x:3000
- Environments: .env
✓ Ready in 283ms
✓ Running next.config.ts took 2.0s
- Cache Components enabled
- Partial Prefetching enabled
Keep this terminal open: the app runs as long as it does. Open http://localhost:3000 in your browser. The Bookshop shows its books, with Sign in and Sign up in the top-right corner:

Step 7: Create Your First Account
Click Sign up. Enter your name, your email address and a password of at least 8 characters, then click Sign up:

Better Auth creates the account and signs you in. The header now shows your name:

To sign in again later, click Sign out, then Sign in, and enter the same email address and password.
Clean Up When You’re Done
- Stop the app: press Ctrl+C in the terminal that runs
npm run dev. - Stop the database and keep its data:
docker compose stop. Start it again later withdocker compose start.
To remove the database and delete every account in it, run:
docker compose down -v
Warning: docker compose down -v deletes the database’s data for good. Without -v, it removes the container and keeps the data.
Troubleshooting
| Problem | Fix |
|---|---|
npm run dev stops with An error occurred while loading instrumentation hook: The settings in .env are missing or invalid | The lines below the error name each setting to fix. Check .env against Step 3. |
npx auth@latest migrate prints ECONNREFUSED | The database isn’t running. Start Docker Desktop, then run docker compose up -d. |
docker compose up -d fails with ports are not available: exposing port TCP 127.0.0.1:5435 … bind: address already in use | Another program uses port 5435. In compose.yaml, change the first number in 127.0.0.1:5435:5432 to a free port, and change the port in DATABASE_URL to match. |
User already exists. Use another email. on the sign-up page | That email address already has an account: sign in instead. |
Invalid email or password on the sign-in page | Check both and try again. |
FAQ
How do I run the tests?
Run npm test. It runs the five tests of the settings check with the test runner built into Node.js, so it needs no database:
npm test
npm notice run bookshop@1.0.0 test
npm notice run node --test tests/
✔ accepts complete, valid settings (0.750041ms)
✔ reports every missing setting (0.091ms)
✔ rejects a secret shorter than 32 characters (0.117208ms)
✔ rejects an app address that isn't http or https (0.077417ms)
✔ rejects a database address that isn't PostgreSQL (0.069625ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 92.585625
Where are the accounts stored?
In the PostgreSQL database from Step 4. Better Auth keeps each person in the user table and a hash of their password in the account table, never the password itself.
Does it work on Windows and Linux?
The commands are the same on Windows and Linux, except the two in Steps 1 and 3, which this guide also shows for PowerShell. This guide was run on macOS with Docker Desktop.
Conclusion
You unzipped the code, installed it, added your settings, started PostgreSQL in Docker, created Better Auth’s tables and signed up in the running app. To learn how the code works, follow the free Better Auth Tutorial for Beginners: Part 2 sets up Better Auth in Next.js, and Part 3 builds the sign-up and sign-in pages.
Additional Resources
- Installation (opens in a new tab) and Email & Password (opens in a new tab) in the Better Auth documentation
- CLI (opens in a new tab) in the Better Auth documentation:
secretandmigrate - docker compose up (opens in a new tab) in the Docker documentation
- next CLI (opens in a new tab) in the Next.js documentation:
next dev - Expand-Archive (opens in a new tab) and Copy-Item (opens in a new tab) on Microsoft Learn
Related
- Better Auth Tutorial — Part 2: Set Up Better Auth in Next.js with PostgreSQL
- Better Auth Tutorial — Part 3: Sign Up and Sign In with Email and Password
Better Auth, Next.js and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Better Auth, Inc. or Vercel.
0 comments