Install BRAD CMS

This guide is for a downloaded production release on your own server. Review server requirements first. Source checkouts have a separate build step and should follow their repository instructions rather than being treated as a release archive.

1. Get your release and license

Sign in to the BRAD portal, open Services, and select your software license service. Copy the license key and download the appropriate release from Software Downloads. Review its release notes and SHA-256 checksum.

Download links expire. If a link has expired, return to the service and obtain a fresh one. See licenses and downloads.

2. Prepare PostgreSQL

Create an empty PostgreSQL database and a dedicated login that owns it. The application applies schema changes during installation and module startup, so read-only credentials will not work.

Record its connection string:

postgresql://brad_user:URL_ENCODED_PASSWORD@db.example.com:5432/brad_cms

Encode reserved characters in the username or password when building the URL. Use the database provider's required connection settings, and verify reachability from the application host.

3. Extract and install dependencies

Extract the archive into your chosen application directory. Locate the directory containing package.json, bin/server.js, prisma/, and modules/. Run the following commands from that directory; do not add another build/ level to the downloaded release unless its release instructions require it.

cd /srv/brad
bun install --production

The current distribution ships a compiled Prisma client. Do not run prisma generate over a downloaded production release: it can replace compiled JavaScript with TypeScript that the production entrypoint cannot load. Generating the client belongs to building from source.

4. Create the environment file

Create .env beside the release's package.json. The server reads this file; the current bootstrap does not create one for you. A useful production baseline is:

NODE_ENV=production
DATABASE_URL="postgresql://brad_user:URL_ENCODED_PASSWORD@db.example.com:5432/brad_cms"
HOST=127.0.0.1
PORT=3333
APP_URL=https://app.example.com
SESSION_DRIVER=cookie
DRIVE_DISK=fs
APP_ROOT=/srv/brad
TZ=UTC

For a container or external ingress that connects directly to the process, use HOST=0.0.0.0. Keep .env readable by the application user and outside publicly served paths.

DATABASE_URL is the only hard-required deployment input in the server bootstrap. The other values above make the public URL, network binding, and storage location explicit. At HTTP server startup, BRAD adopts an existing APP_KEY or creates one and persists it in the PostgreSQL app_runtime_secret table. Preserve that table in database backups. If you already have an APP_KEY, retain it during updates.

For multiple processes or production real-time workloads, configure REDIS_URL too. The configuration reference explains the settings.

5. Apply core migrations

From the release directory, with DATABASE_URL available:

bunx prisma migrate deploy

Wait for a successful result. Do not use prisma migrate reset or prisma db push on a production installation. Module migrations are managed by the module system during startup; review startup logs for failures.

6. Start and route traffic

bun run start

The downloaded release's start script runs node bin/server.js; Node must be installed even when Bun is your package manager. This foreground command is useful for the first boot. Put the same entrypoint under your hosting platform or service manager for ongoing operation.

Configure HTTPS ingress to forward to the chosen host and port and support WebSocket upgrades. Open the final public URL, not a temporary IP or localhost address, when activating the license. See production hosting for proxy and service examples.

7. Complete the browser installer

On a new database, the application directs you to the installation wizard:

1. Enter your license key and confirm the initial database setup.
2. Create the first administrator with a name, email, and strong unique password.
3. Enter your company name and complete installation.

Use the CMS sign-in screen to access the administration area when installation finishes. These are CMS credentials, separate from your portal login.

If installation stops partway through, read the error and logs before retrying. Keep the existing database intact; dropping it is not a troubleshooting step.

8. Verify the installation

• The intended domain loads over HTTPS and the administrator can sign in.
• /api/health responds, and Settings → System Health shows the expected database, storage, license, and module state.
• Startup logs contain no module-loading or migration failures.
• The intended paid modules are available.
• Storage remains writable after restarting the application.

Continue with CMS setup, then complete the launch checklist. For unattended provisioning, use the separate automated installation guide.