---
title: Operating an installation
section: Install and operate
order: 43
summary: Upgrade, back up, recover and monitor the application and its stored evidence.
---

These instructions concern the Balsa application. This documentation site is a static export and has no customer database or financial background jobs.

## Before an upgrade

Record the application revision and review its schema and configuration changes. Back up PostgreSQL and the source-file storage together, and retain the matching configuration securely. Verify that the backup can be restored into an isolated environment.

A database dump without uploaded files can leave evidence references unusable. A copy of uploaded files without the database loses their accounting and review context. A saved financial-review download is not an installation backup.

## Apply an upgrade

Use your deployment’s normal source-update process, then from the application root:

```bash
pnpm install --frozen-lockfile
pnpm db:migrate
pnpm run doctor
pnpm build
```

Start the web package using your deployment manager. The application root does not define a `pnpm start` script; the web package provides `pnpm --filter @finance/web start`. For a packaged deployment, prefer the repository’s full Docker profile and entrypoint, which handle its standalone build and migrations.

Do not remove migrations or hide a missing schema to make a new feature load. If rollback is necessary, treat code and database compatibility as a coordinated recovery task rather than assuming an old binary can read a new schema.

## Persistent storage

Keep `FILE_STORAGE_PATH` outside the web root with appropriate filesystem permissions and capacity. In the full Docker profile, uploads and PostgreSQL use persistent volumes. Stopping the profile retains them; removing volumes destroys data.

Keep credentials out of source control, support requests and financial exports. Preserve necessary secrets securely during recovery rather than silently replacing them.

## Health and scheduled work

`GET /api/health` checks database connectivity. When `HEALTHCHECK_SECRET` is configured, supply its bearer token privately. In production, a missing secret or invalid authorization returns 404; database unavailability returns 503.

Scheduled financial work uses a separate `CRON_SECRET`. The current scheduled route is `GET /api/jobs/reconciliation`; verify its behavior against your installed revision before scheduling it. A successful job request is not proof that every accounting exception was resolved; inspect exceptions, freshness and relevant application logs.

The calculation outbox provides durable recalculation requests. Diagnose and recover pending work through the installed job path rather than deleting outbox records to hide a stale result.

## Restore and inspect

Restore into an isolated installation first. Check database connectivity, migration compatibility, file permissions and access to source attachments. Verify representative journal balances, preserved review history and company selection before switching traffic.

Run synthetic accounting and isolation checks only against a disposable database. The isolation script creates and deletes companies; it must not use a customer installation as its fixture.

## Deployment limits

Authentication and application rate limiting are currently process-local. A multi-instance deployment needs shared rate limiting, trusted proxy handling and scheduled outbox recovery. Those changes are not supplied merely by running several app containers.

See [Security](/docs/security/), [Configuration](/docs/configuration/) and [Troubleshooting](/docs/troubleshooting/).