Skip to content

Self-hosting ​

The exported code of a Luna Park application (see Compilation) is a standard Node.js project. You can run it on any server: a VPS, a dedicated server, or a container platform.

What you need ​

  • Node.js 24 or newer, and pnpm.
  • A PostgreSQL database. Tables are created and kept in sync automatically at each start (see Database schema), with the rows you entered in the editor as initial data.

Project structure ​

FolderContent
frontendThe Vue application (Vite).
backendThe API server (Fastify): your routes, crons, and database access. It also serves the frontend.
utilsAn interactive tool to configure and launch the server.
.envThe server configuration.

Configuration ​

The .env file at the root of the project holds the configuration:

VariableDefaultDescription
DATABASE_URLPostgreSQL connection string (postgresql://user:password@host:5432/database). Required.
HOST127.0.0.1Address the server listens on. Use 0.0.0.0 to accept outside connections.
PORT3080Port of the server.
PREFIX/apiPath prefix of the routes.
STATICfrontend/distFolder of the built frontend, served by the backend. Leave it empty to host the frontend elsewhere.
COOKIE_SECRETgeneratedSecret used to sign cookies. Keep it private.
UPLOAD_MAX_SIZE10Maximum size of an uploaded file, in MB.
UPLOAD_MAX_FILES10Maximum number of files in one request.
DATABASE_BACKUPtrueSet to false to turn off the automatic backups.

Plugins can add their own variables (OAuth or SMTP secrets, for example).

HTTPS

Cookies are secure: serve your app over HTTPS, otherwise browsers won't keep them (sessions, for example).

Run with the utils tool ​

From the project folder:

bash
pnpm install
pnpm run utils

The menu lets you:

  • Configure server: port, database URL, and the backend URL used by the frontend;
  • Launch server, or Launch dev server (watch mode);
  • Launch permanent server (using PM2), which keeps it running and restarts it on failure, and Stop permanent server.

On Windows, launch-windows.bat installs the requirements and opens this menu.

Run manually ​

bash
pnpm install
pnpm build
pnpm start

The server prints its address on start. GET /api/health answers { "status": "ok" } when it is running.

Run with Docker ​

The export contains a run_basic.dockerfile that builds the app and serves it with nginx on port 80:

bash
docker build -f run_basic.dockerfile -t my-app .
docker run -p 80:80 --env-file .env my-app

Updating ​

Download or generate the new code, replace the files (keep your .env and the .backup folder), then build and restart the server.

Database schema ​

At each start, the server compares the database with the tables of the project and updates it:

  • new tables and columns are created, renamed tables and columns are renamed (their data is kept);
  • tables and columns removed from the project are deleted, with their data;
  • columns whose type changed are converted: values that can't be converted are emptied;
  • constraints and indexes are added or removed. When Required is turned on, empty values get the default value of the type. A constraint that can't be applied is logged, and the server keeps running.

The rows entered in the editor are only inserted when a table is created. Existing tables keep their data.

WARNING

Removing a Database file or a column from the project deletes its data on the next start. A backup is taken just before (see below).

Backups ​

The server backs up the database to the .backup folder, next to .env:

  • at each start, before updating the schema;
  • every day, as long as the server runs.

Each backup is a SQL file named after its date and time (UTC). The server keeps the backups of the last 7 days that have some, and at most 5 per day.

Set DATABASE_BACKUP=false to turn backups off, for example when your host already backs up the database. If a backup fails at startup, the server doesn't start.

With Docker, the .backup folder is inside the container: mount a volume on /app/.backup to keep the backups when the container is replaced.

To restore a backup, run it on an empty database, for example with psql "$DATABASE_URL" -f .backup/<file>.sql.