> For the complete documentation index, see [llms.txt](https://voyzu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyzu.gitbook.io/docs/installation-and-operation/installation-and-setup.md).

# Production installation and setup

This guide describes an end-user Voyzu installation intended to be built and run as a production application.

{% hint style="info" %}
This is a production-style installation. Voyzu and installed packages are downloaded and copied into an isolated `.run` runtime.

To develop Voyzu packages using a `.run` development runtime, directory links and hot reload, see [Development setup](/docs/extending-voyzu/development-setup.md).
{% endhint %}

## Prerequisites

Install:

* **Node.js**: Node.js 20 or later. Voyzu is currently developed and tested with Node.js 24.
* **npm**: installed with Node.js.
* **PostgreSQL**: a local or network PostgreSQL server accessible to the application.
* **Git**: used by the installer and package update commands.

Confirm the commands are available:

```shell
node -v
npm -v
psql --version
git --version
```

## Create the PostgreSQL database

Create an empty PostgreSQL database for the installation. The examples in this guide use the name `voyzu`:

```shell
createdb voyzu
```

Record the database host, port, database name, username and password. The installation command does not create the PostgreSQL database itself.

Do not point a new installation at a database containing unrelated or important data.

## Create the Voyzu installation

Choose a parent directory, then run:

```shell
npm exec --yes --package=github:chrisjameslennon/create-voyzu#main -- create-voyzu install my-voyzu
```

The command is the same in PowerShell, macOS and Linux shells.

It:

1. creates a `my-voyzu` directory. Modify with the direcotry name of your choice;
2. shallow-clones Voyzu into `.run/voyzu`;
3. creates the empty installed-package directory `.run/packages`;
4. shallow-clones the official package repository into `voyzu-package-repos/voyzu-packages`;
5. creates the runtime npm workspace and installs its dependencies;
6. creates the project-local Voyzu CLI; and
7. initializes `my-voyzu` as a new Git repository.

The resulting structure is:

```
my-voyzu/
├─ .run/
│  ├─ voyzu/
│  ├─ packages/
│  └─ package.json
├─ voyzu-package-repos/
│  └─ voyzu-packages/
├─ .env.local
├─ package.json
├─ README.md
└─ voyzu.instance.config.ts
```

Move into the generated project:

```shell
cd my-voyzu
```

No global Voyzu CLI installation is required. Voyzu operations are exposed as npm scripts in the generated root `package.json`.

## Configure the environment

Open `.env.local` in the generated project root. Replace `CHANGE_ME` in `VOYZU_DATABASE_URL`:

```env
VOYZU_DATABASE_URL=postgresql://postgres:your-password@localhost:5432/voyzu
```

If the database password contains reserved URL characters, URL-encode it.

The installer has already generated a unique authentication secret:

```env
VOYZU_AUTH_SECRET=<generated-base64url-value>
```

Voyzu uses this value to sign and verify authentication session cookies. If it is omitted or does not decode to at least 32 bytes, Voyzu refuses to authenticate requests. Do not replace it with a memorable password or reuse it between Voyzu instances.

Do not commit `.env.local` or disclose its contents. Restrict access to the database account and use a secret-management mechanism appropriate to the deployment environment.

The installer creates `.env.local` and `voyzu.instance.config.ts` only during the virgin installation. Voyzu package and update commands do not overwrite them.

## Initialize Voyzu

After configuring `.env.local`, initialize the preinstalled Authentication and Audit database objects:

```shell
npm run voyzu:initialize
```

This is a one-time initialization step for a new database. Package installation does not initialize the Voyzu platform.

## Install Voyzu packages

The virgin installation contains the Voyzu platform, including Authentication, Users and Audit, but it does not automatically install optional business packages.

Install the packages required by this Voyzu instance using their npm package names. For example:

```shell
npm run voyzu:install -- https://github.com/chrisjameslennon/voyzu-packages.git @voyzu/ice-creams
```

The official package repository has already been cloned, so the command refreshes it and then installs the named package.

Production installation uses copy mode by default. The command:

1. finds the active package in a cloned package repository;
2. copies it into `.run/packages/<npm-package-name>`;
3. installs runtime npm workspace dependencies;
4. applies the package SQL and seed SQL declared by `voyzu.package.ts`;
5. generates the combined navigation, page and API registrations; and
6. clears the Next.js build cache.

`--link` is deliberately unavailable in a production `.run` runtime.

To install a package from another Git repository, supply both the repository and package name:

```shell
npm run voyzu:install -- https://github.com/example/fred-packages.git @fred-packages/example
```

Package discovery uses package metadata and does not require a particular internal repository folder structure.

## Create the bootstrap administrator user

After `npm run voyzu:initialize` has created the Authentication tables, seed the bootstrap administrator:

```shell
npm --prefix .run exec -- tsx --env-file=.env.local .run/voyzu/scripts/db/seed/seed-users.ts
```

The npm prefix resolves `tsx` from `.run/node_modules` while the command remains in the generated project root.

This creates:

```
User code: ADMIN
Password:  password
```

{% hint style="danger" %}
The bootstrap administrator is only for initial setup. Sign in, create a named administrator with a strong unique password, verify that account can sign in, and delete the `ADMIN` user before exposing Voyzu to other users or a network.
{% endhint %}

## Start the production application

Run:

```shell
npm run voyzu:start
```

The generated root `package.json` retains `npm start` and defines `npm run voyzu:start` as an alias. The root `prestart` hook performs a production build (`npm run voyzu:build`) before starting Next.js.

By default the application listens on:

```
http://localhost:3000
```

Browse to `http://localhost:3000` and sign in using the bootstrap administrator. Voyzu will display its minimal Hello World page. Organization and Finance navigation appears only after installing the Core package.

If you are hosting a Voyzu instance you will want to run Voyzu behind the platform's process manager and HTTPS reverse proxy. See [Deployment](/docs/installation-and-operation/deployment.md).

## Install the Voyzu Core package

Having installed the Voyzu Platform, the next step is to install the Core Voyzu Organization and Finance package.

The official `voyzu-packages` repository was downloaded when the Voyzu installation was created. Pull its latest package source and install Core:

```shell
npm run voyzu:refresh-repo -- voyzu-packages
npm run voyzu:install -- https://github.com/chrisjameslennon/voyzu-packages.git @voyzu/core
```

The install command copies Core into `.run/packages/@voyzu/core`, applies its database installation, installs its npm dependencies and recomposes the application.

Restart Voyzu after installation:

```shell
npm run voyzu:start
```

## Install the Voyzu sample package

Voyzu provides the Ice Creams sample package as a compact example of package structure, navigation, pages, API routes, database installation, reporting and auditing.

Ensure the official package repository is current, then install the package:

```shell
npm run voyzu:refresh-repo -- voyzu-packages
npm run voyzu:install -- https://github.com/chrisjameslennon/voyzu-packages.git @voyzu/ice-creams
```

If the repository was pulled immediately before installing Core, the repeated pull command can be omitted.

Install the optional Ice Creams sample records:

```shell
npm run voyzu:run -- @voyzu/ice-creams sampleData
```

Restart Voyzu to build and run the newly composed application:

```shell
npm run voyzu:start
```

## Updating package repositories and installed packages

Update all cloned package source repositories:

```shell
npm run voyzu:refresh-repos
```

Or update one repository:

```shell
npm run voyzu:refresh-repo -- voyzu-packages
```

Pulling only updates package source. Refresh installed copies and recompose:

```shell
npm run voyzu:install-package
```

Then rebuild and restart:

```shell
npm run voyzu:build
npm run voyzu:start
```

Because `npm run voyzu:start` builds automatically, the explicit `npm run voyzu:build` can be omitted when that behaviour is preferred.

## Updating the Voyzu platform

`.run/voyzu` is a shallow Git checkout. Platform updates should be tested before being applied to a production instance. Back up the database and project configuration, then run:

```shell
npm run voyzu:refresh
```

The command fast-forwards the downloaded Voyzu checkout with `git pull --ff-only` and builds the updated application. It does not run package SQL or package scripts. Restart the web server after it completes.

Package repository update commands do not update the Voyzu platform checkout.

## Common checks

If installation, build or startup fails, check:

* PostgreSQL is running and accepts connections from the application host.
* The database named in `VOYZU_DATABASE_URL` exists.
* The database username, password, host and port are correct.
* `.env.local` is in the generated project root.
* GitHub and the npm registry are reachable during installation.
* Package installation completed before the bootstrap user seed was run.
* `npm run voyzu:build` succeeds before the production process is restarted.
* Commands are being run from the generated project root.

For the complete command reference, see [Voyzu commands](/docs/extending-voyzu/commands.md).