Install and verify your first instance

Start with a local evaluation of OpenQuoteStack before exposing it to customers. This guide takes you from an empty checkout to a running installation and explains what each service does. Use Node.js 24, pnpm 10 and Docker with the Compose plugin.

Know which project you are installing #

This documentation website is separate from the OpenQuoteStack application. The website needs only Next.js. The product needs PostgreSQL, a web process and a background worker. The commands below install the product.

Version 0.2.0-alpha.1 is an early public preview. Choose an evaluation environment where you can inspect its behavior and test restoration. Read production readiness before collecting real customer data.

Get the source and generate configuration #

git clone https://github.com/ReVG08/OpenQuoteStack.git
cd OpenQuoteStack
pnpm install --frozen-lockfile
pnpm setup:env

For a reproducible deployment, select a reviewed release or commit before building. A moving branch can contain changes beyond the version documented here.

setup:env creates a private .env file with unique database, authentication and encryption values. It refuses to replace an existing file. Keep it out of Git and preserve the encryption key with your backups.

For an HTTPS installation, generate the configuration with the intended public origin:

pnpm setup:env --url https://quotes.example.com

This is an alternative to the previous setup:env call, not a second invocation over an existing file. If configuration already exists, review and edit it rather than expecting the generator to overwrite it.

Start the services #

docker compose up -d --build
docker compose ps
docker compose logs --tail=100 migrate web worker
curl --fail http://localhost:3000/health

Compose coordinates four services:

A completed migration container is normal. A failed migration is not: read its logs before trying to use the application. The health response tests basic database connectivity; it does not prove SMTP credentials or webhook receivers work.

Create the first organization #

Open the configured origin, register an account and create an organization. Select the business name, locale, timezone and default currency. Choose Moving, Cleaning or Website design as a starting point. Optional branding can wait.

There are no installed default credentials. The fictional Acme Moving data is opt-in and requires an existing account. You do not need that seed to publish a calculator.

Next, follow Publish your first moving estimator. Do not share a draft editor URL with customers; publishing creates the public calculator link.

Check persistence before continuing #

Upload a small test logo, save a draft and restart the application services:

docker compose restart web worker
docker compose ps

Confirm that the account, organization, logo and draft remain available. PostgreSQL and local branding assets use named volumes. docker compose down retains those volumes; removing them destroys their contents.

If port 3000 is already occupied #

Set OQS_WEB_PORT to an unused host port and make BETTER_AUTH_URL match the exact browser-facing origin, including that port. Recreate the affected services after changing configuration. Container port 3000 stays unchanged.

For example, a local evaluation on port 3001 uses BETTER_AUTH_URL=http://localhost:3001 and OQS_WEB_PORT=3001. Changing only the port can cause authentication origin checks to fail.

Before making it public #

Compose binds its host ports to loopback. Add an HTTPS reverse proxy, preserve the original Host and protocol, and keep PostgreSQL private. The Linux and proxy reference contains Caddy and Nginx examples.

Test a complete quote, storage persistence and a backup restoration before directing customer traffic to the installation. Use the troubleshooting guide when a check fails.