Requirements
What to install before you run your package, with Docker or without it.
For the Full Stack package
What each package contains
| Package | Apps in the download | Runs on its own |
|---|---|---|
| Full Stack | API, public website, agency dashboard | Yes, all three together |
| Public Website | Public website | No: it needs the Velra API running |
| Agency Dashboard | Agency dashboard | No: it needs the Velra API running |
| Backend API | API | Yes, serving the API only |
A single-app package does not include the other apps. The website and the dashboard read everything from the Velra API, and the API's code is only in the Full Stack and Backend API packages.
With Docker
- Docker Desktop on macOS or Windows, or Docker Engine with the Compose plugin on Linux, with Docker Compose 2.24 or newer, which every current Docker Desktop includes;
docker compose versionprints yours. The full stack starts with onedocker composecommand, anddocker-compose.ymlreadsback-end/.envonly when it exists, a setting older Compose versions reject. - An internet connection for the first build, which downloads the base images and the dependencies.
- Nothing else: Docker brings Node.js, and the database is a SQLite file inside a Docker volume.
With Docker
- Docker Desktop on macOS or Windows, or Docker Engine on Linux. Your app has its own
Dockerfile; Compose is not needed. - An internet connection for the first build, which downloads the base image and the dependencies.
Without Docker
- Node.js 22 or newer, the version every app declares in
engines. The Docker images run on Node.js 24. Check yours withnode -v. - Yarn 4, through Corepack. Run
corepack enableonce; each app pins its own Yarn version inpackageManager, soyarnpicks the right one. If your Node.js has no Corepack (Node.js 25 and newer leave it out), install it first withnpm install -g corepack. - No global packages.
Database
No database server. The API uses SQLite by default and yarn seed creates the file for you; Docker uses SQLite too. MySQL is supported as a configuration change, not a code change.
Ports
Each app listens on a fixed local port. Make sure nothing else uses them, or, with Docker, move one with SITE_PORT, ADMIN_PORT or API_PORT in a .env beside docker-compose.yml.
| App | Port |
|---|---|
| API | 8000 |
| Public website | 3030 |
| Agency dashboard | 3031 |
Port
The website listens on port 3030 and expects the API on 8000. Make sure nothing else uses them.
Port
The dashboard listens on port 3031 and expects the API on 8000. Make sure nothing else uses them.
Port
The API listens on port 8000, and by default accepts the website from 3030 and the dashboard from 3031. Make sure nothing else uses port 8000.
An API to connect
Your app has no data of its own. It needs the Velra API running and seeded, whose address you set in its .env or pass as a build argument. The API is sold as its own package, the Backend API, and is part of the Full Stack.
Optional services
None of these is needed to run the agency locally. Each is switched on by its variables in the API's .env; a variable left commented out keeps its feature off.
| Service | Without it |
|---|---|
| Cloudflare R2 or another S3-compatible bucket | Uploads are stored on the API's own disk (with Docker, in the data volume), and the API serves the seeded photos itself. |
| An AI key from Google Gemini, OpenAI or DeepSeek, any one | The AI assistant says it needs a provider key and lists the three it accepts, and nothing is billed. Everything else works. |
| A Google Gemini key, for the staging studio | The AI staging studio says it needs one and generates nothing, even when the assistant runs on an OpenAI or DeepSeek key. |
| A key for the MCP server | POST /api/mcp refuses every request. |
There is no mail or payment service to set up: inquiries and viewing requests arrive as notifications in the dashboard.
Maps
The dashboard's maps draw OpenFreeMap tiles, and the property editor's place search uses the public Photon service. Both need an internet connection and no key or account; neither promises availability, and you can point them at your own services.