Installation

This guide covers installing Nanobox CRM when you self-host it. If you'd rather not run a server at all, skip this entirely. Hosted handles every step below for you. For everyone else, here's the high-level flow. Treat the specifics as something to confirm against the source you receive with your license, not as exact, copy-paste gospel.

Prerequisites

You'll want a Linux server (a small VPS is plenty to start) and these tools available on it:

• Docker and Docker Compose: the recommended way to run Nanobox, since the app ships as containers. See Deploying with Docker for the full deployment path.
• PostgreSQL: the database. You can run it as a container alongside the app or point at a managed Postgres instance you already have.
• Node.js: needed if you intend to build from source or run database migrations and scripts outside of Docker. [TODO: confirm the minimum supported Node version against the source.]

The install flow

At a high level, installing Nanobox looks like this:

1. Get the source. After purchase you receive the licensed source. [TODO: confirm exact delivery method (repository access or a download).]
2. Provision a database. Create an empty PostgreSQL database and a user with rights to it. Keep the connection string handy for the next step.
3. Set your configuration. Copy the example environment file and fill in your values: database URL, auth secret, app URL, and email settings. See Configuration for what each one does.
4. Run the migrations. Nanobox uses Drizzle ORM, so applying the schema is a single migration step. [TODO: confirm the exact migrate command shipped in the project's scripts.]
5. Start the app. Bring it up with Docker Compose, then open the app URL in a browser.
6. Create the first account. Register the first user through the sign-up flow; better-auth handles accounts and sessions.

Verifying it worked

Once the app is running, confirm three things: the homepage loads, you can register and log in, and a record you create persists after a refresh (proving the database connection is live). If any of those fail, the cause is almost always a missing or wrong environment variable. Start with the database URL and the auth secret in Configuration.

When you're ready to harden it for real traffic (a reverse proxy, TLS, and persistent storage), continue to Deploying with Docker.