Setup
Create a VitNode app with create-vitnode-app, start PostgreSQL, run the development server and sign in to the AdminCP as the first administrator.
This page takes you from an empty folder to a running VitNode app, with you signed in to the AdminCP as its administrator. It is the first lesson of the beginner path; the next one creates a plugin inside this app.
Before you begin
- Node.js
22.18or newer in the 22 line,24.11or newer in the 24 line, or26and later. The generator and every generated package refuse older versions. - A package manager: pnpm, bun or npm.
- PostgreSQL. The easiest local option is Docker, which the generator can configure for you. Your own PostgreSQL server works too.
Scaffold the app
Run the generator from the folder that should contain your project:
bun create vitnode-app@canaryIt asks for a project name (default my-vitnode), then these questions. The recommended answers set you up for the rest of the beginner path:
| Question | Recommended | Why |
|---|---|---|
| Package manager | the one you use | The generator offers only the managers you have installed. |
| App type | Single App | One TanStack Start app with the Hono API mounted at /api. Monorepo App splits web and API into two apps; Only API has no front end. |
| Use Turborepo? | Yes | Required to create plugins. A Monorepo App always gets it, so the generator skips the question. |
| Oxlint & Oxfmt? | your choice | Adds lint and format scripts. |
| Docker container? | Yes, unless you run PostgreSQL yourself | Adds docker-compose.yml with PostgreSQL 17 and Redis on 127.0.0.1. |
| Git repository? | your choice | |
| Install dependencies? | Yes | Installs packages and generates the first migrations. |
With Turborepo, the app lives in apps/web (plus apps/api for a Monorepo App) and your plugins will go in plugins/. Without it, the app sits at the project root and you cannot create plugins later.
Open the project
cd my-vitnodeRun every command in this lesson, and in the lessons after it, from this folder. If you answered No to "Install dependencies?", install them now with bun install, pnpm install or npm install.
Configure the environment
The app reads its settings from .env. A Monorepo App already has apps/web/.env; a Single App ships only .env.example. Copy it next to itself:
cp apps/web/.env.example apps/web/.envFor a Monorepo App / Single API:
cp apps/api/.env.example apps/api/.envThe defaults match the Docker services:
- PostgreSQL at
postgresql://root:root@localhost:5432/vitnode. Using your own PostgreSQL? ChangePOSTGRES_URLto its connection string. - Redis at
redis://localhost:6379with the passwordroot. Redis is optional. DeleteREDIS_URLto run without it, and VitNode falls back to an in-process cache.
Start PostgreSQL
With Docker, start the database and Redis in the background:
bun run docker:devWithout Docker, make sure the server in POSTGRES_URL is running and the database exists.
Start the development server
bun run devBefore the server starts, dev builds your plugins, generates any pending migrations, applies them and seeds the default roles. You never run migrations by hand on this path. When it is ready, it prints the addresses:
Web http://localhost:3000
AdminCP http://localhost:3000/admin
API http://localhost:3000/apiCreate the administrator account
VitNode has no installer. The first account that registers becomes the administrator. It gets the root Administrator role and a verified email. Every later account is a regular member.
Open http://localhost:3000/register and create your account. Then open http://localhost:3000/admin and sign in with the same email and password. The AdminCP has its own sign-in, separate from the site's.
Check the result
http://localhost:3000shows the public site, and the header has your avatar.http://localhost:3000/adminshows the AdminCP dashboard after you sign in.- Staff ā Administrators in the AdminCP lists the Administrator role as unrestricted.
If dev stops with a database error, PostgreSQL is not reachable at POSTGRES_URL. Check that the containers are up (docker ps) or that your own server accepts the connection.