Run the agency locally

Open every terminal where the commands below expect it: inside velra-real-estate-full-stack for the full stack, or next to the app's folder for a single-app package.

Start the API first: both frontends read all of their data from it.

Start the API

1. 01

   Install and configure

   .env.example works as it is for local development: SQLite on port 8000.

   TerminalCopy

   corepack enable
   cd back-end
   yarn install
   cp .env.example .env

   0:00 / 0:09

   Having trouble?

   I've done this step
2. 02

   Create the database

   yarn seed checks that every seeded photo is present, then creates database.sqlite, its tables and the demo agency: 31 permissions, the Super Admin and Agent roles, the two accounts, 11 agency settings, 6 neighborhoods, 17 properties (15 published, 2 drafts) with 38 gallery photos, 2 approved staging previews, 5 inquiries and 8 viewing requests. Running it again adds only what is missing and never resets a password.

   Terminalin back-endCopy

   yarn seed

   I've done this step
3. 03

   Start the server

   Terminalin back-endCopy

   yarn dev

   Expected result: localhost:8000/api/healthLocal answers with "status":"ok" and "database":"up".

   Having trouble?

   I've done this step

Start the API

1. 01

   Install and configure

   .env.example works as it is for local development: SQLite on port 8000.

   TerminalCopy

   corepack enable
   cd velra-backend
   yarn install
   cp .env.example .env

   0:00 / 0:09

   Having trouble?

   I've done this step
2. 02

   Create the database

   yarn seed checks that every seeded photo is present, then creates database.sqlite, its tables and the demo agency: 31 permissions, the Super Admin and Agent roles, the two accounts, 11 agency settings, 6 neighborhoods, 17 properties (15 published, 2 drafts) with 38 gallery photos, 2 approved staging previews, 5 inquiries and 8 viewing requests. Running it again adds only what is missing and never resets a password.

   Terminalin velra-backendCopy

   yarn seed

   I've done this step
3. 03

   Start the server

   Terminalin velra-backendCopy

   yarn dev

   Expected result: localhost:8000/api/healthLocal answers with "status":"ok" and "database":"up".

   Having trouble?

   I've done this step

Start the public website

In a second terminal:

1. 01

   Install and configure

   The copied .env points the website at the API on port 8000.

   TerminalCopy

   cd storefront
   yarn install
   cp .env.example .env

   0:00 / 0:07

   I've done this step
2. 02

   Start it

   Terminalin storefrontCopy

   yarn dev

   Expected result: localhost:3030Local opens the website in English with the demo listings; Arabic is at /ar.

   Having trouble?

   I've done this step

Start the public website

The API is not part of this package. Start it first; the copied .env expects it at http://localhost:8000/api.

1. 01

   Install and configure

   If your API runs somewhere else, set NEXT_PUBLIC_API_BASE_URL in .env to its address, including /api.

   TerminalCopy

   corepack enable
   cd velra-website
   yarn install
   cp .env.example .env

   0:00 / 0:07

   Having trouble?

   I've done this step
2. 02

   Start it

   Terminalin velra-websiteCopy

   yarn dev

   Expected result: localhost:3030Local opens the website with the listings from your API; Arabic is at /ar.

   Having trouble?

   I've done this step

Start the agency dashboard

In a third terminal:

1. 01

   Install and configure

   The copied .env points the dashboard at the API and its live notifications on port 8000.

   TerminalCopy

   cd admin-dashboard
   yarn install
   cp .env.example .env

   0:00 / 0:07

   I've done this step
2. 02

   Start it and sign in

   yarn dev first copies the map library's worker into public/maplibre/, then starts the dashboard.

   Terminalin admin-dashboardCopy

   yarn dev

   Expected result: localhost:3031Local opens the sign-in form. Sign in with admin@velra.example and the password Admin@123.

   Having trouble?

   I've done this step

Start the agency dashboard

The API is not part of this package. Start it first; the copied .env expects it at http://localhost:8000/api.

1. 01

   Install and configure

   If your API runs somewhere else, set NEXT_PUBLIC_API_BASE_URL (with /api) and NEXT_PUBLIC_WEBSOCKET_BASE_URL (without it) in .env to its address.

   TerminalCopy

   corepack enable
   cd velra-agency-dashboard
   yarn install
   cp .env.example .env

   0:00 / 0:07

   Having trouble?

   I've done this step
2. 02

   Start it and sign in

   Terminalin velra-agency-dashboardCopy

   yarn dev

   Expected result: localhost:3031Local opens the sign-in form. Sign in with admin@velra.example and the password Admin@123, which a seeded API accepts.

   Having trouble?

   I've done this step

Other ports

Without Docker the ports are fixed in the files. The website's dev and start scripts in package.json pass -p 3030, and the dashboard's pass -p 3031: change the number there to move one, then add the new address to CORS_ORIGIN in the API's .env, and for the dashboard set FRONTEND_URL there to it too. To move the API, set PORT and PUBLIC_MEDIA_URL in its .env to the same number, and NEXT_PUBLIC_API_BASE_URL in both frontends (the dashboard's NEXT_PUBLIC_WEBSOCKET_BASE_URL too).

• A port is already in use

Production build

The same folders, built once and then started. First set the API's .env for production: with NODE_ENV=production the API never changes the tables on start, and it refuses to start while JWT_SECRET is empty or still the example value, or while CORS_ORIGIN is empty.

NODE_ENV=production
JWT_SECRET=paste-the-generated-secret-here
CORS_ORIGIN=http://localhost:3030,http://localhost:3031
FRONTEND_URL=http://localhost:3031
PUBLIC_MEDIA_URL=http://localhost:8000/media

Generate the secret with node -e "console.log(require('crypto').randomBytes(48).toString('hex'))". Then, in the API's folder, build it, create its tables once, and start it. yarn seed:prod adds the demo agency and its accounts; yarn db:sync:prod in its place creates empty tables with no accounts.

yarn build
yarn seed:prod
yarn start:prod

• Deploy it

Production build of the frontends

In each frontend's folder, build once and start. The website serves on 3030 and the dashboard on 3031.

yarn build
yarn start

The frontends compile their .env in at build time, so run yarn build again after changing it. Before you deploy anywhere public, read the deployment guide.

• Deploy it

Start over with fresh demo data

Stop the API, then delete the database file and seed it again, in the API's folder. This deletes everything you created.

rm -f database.sqlite* && yarn seed

In PowerShell:

Remove-Item database.sqlite*; yarn seed

Next

• Set your environment variables
• Run it with Docker instead
• Fix a setup problem