Installation Guide

Tours installs as a single Next.js application — there is no separate API server to set up. Install dependencies, point it at a PostgreSQL database, start the app, and finish the guided install wizard at /install. This page covers both the manual setup and the wizard, end to end, including the full environment-variable reference.

In a hurry? The Quick Start is the four-command version. This guide is the detailed one.

Prerequisites

Confirm your Node version before continuing:

node -v   # must report v20 or higher

Step 1 — Install Dependencies

Unzip the download, then from the project root:

npm install

This also runs prisma generate (via the postinstall hook) to produce database client types. Runtime data access uses the tagged sql template, not an ORM — Prisma is only used for generated types and tooling.

Step 2 — Configure the Environment

Tours reads configuration from a .env file in the project root. The install wizard can create and write this file for you on a writable filesystem — it generates JWT_SECRET and CRON_SECRET automatically during the database step. On a read-only host (such as Vercel) you set the values manually instead.

To prepare it yourself, create .env with at least the core keys:

# Required — PostgreSQL connection (Neon recommended)
DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"

# Required — signs admin & customer session tokens (any long random string)
JWT_SECRET="replace-with-a-long-random-string"

# Recommended — AES-256-GCM key that encrypts integration secrets stored in the DB
SECRET_KEY="replace-with-a-long-random-string"

Generate strong secrets. Use something like openssl rand -base64 48 for JWT_SECRET and SECRET_KEY. Set SECRET_KEY once, before connecting any integrations — if you change it after integration credentials have been saved, those encrypted values can no longer be decrypted.

Full Environment Variable Reference

These are the only environment variables Tours reads. Anything not listed here is not used by the app.

* The R2_* variables are a fallback only. The recommended way to connect storage is Admin → Settings → Integrations → Storage, where keys are encrypted in the database with SECRET_KEY. See the Deployment Guide.

Step 3 — Initialise the Database

If you prefer to create the schema from the command line before running the wizard, use the init script (it reads DATABASE_URL from your .env):

npm run db:init

db:init runs two steps in order — the CMS tables (init-db), then the core / auth / vendor and Tours business schema (init-core). Related helper scripts:

The schema is idempotent and self-healing — it is created by ensure*() helpers (CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ADD COLUMN IF NOT EXISTS), not a migration framework. Running it again is safe. You can also skip this step entirely and let the install wizard create the schema during its database step.

Step 4 — Start the App

npm run dev

Open http://localhost:3000. On a fresh install (no DATABASE_URL and no .installed lock file) the app redirects to the install wizard at /install.

The first request to a freshly added or edited route can take a few seconds while the dev server compiles it on demand — that is normal, not a hang.

Step 5 — The Install Wizard (/install)

The wizard walks through six screens. It is the recommended path for a self-hosted Node setup, where it writes .env and creates the schema for you.

Read-only filesystem note: if .env cannot be written (e.g. on Vercel), the wizard returns the exact values it would have written so you can add them as environment variables in your host's dashboard, then redeploy.

Restart Once After Finishing

After the wizard completes on a self-hosted setup, restart the app once (stop and re-run npm run dev / npm run start, or restart it in your hosting panel) so the newly written environment variables load fully. Then sign in.

Step 6 — First Admin Login

Go to /admin/login and sign in with the admin email and password you created in step 4. From there you can configure payments, storage, and theme, and switch on the add-ons your license entitles.

Verify the Install

• The storefront at / renders with seeded content.
• /admin/login accepts your admin credentials.
• npm run type-check passes (runs tsc --noEmit).
• If uploads are needed, connect storage in Admin → Settings → Integrations → Storage before going live.

Next: ship it to production with the Deployment Guide, or pick a host with the Hosting Guide.

© CreativeCape Solutions · creative-cape.com · support@creative-cape.com