v1.0.0 is the first release of Posify. It needs Node.js 24.11 or newer (26 LTS recommended) and PostgreSQL 16 or newer.Read the 1.0 notes
Posify
DocsDocumentation
⌘ K
Documentation·Business setup

Posify Setup & Installation

Everything you need to install, configure, and deploy Posify - from your first pnpm install to PostgreSQL, the till, offline selling, printers, stock, accounting, and production hosting.

Overview

Posify 1.0 is a self-hosted point-of-sale and back-office system for one business with many branches and registers. You install it on your own server, with your own PostgreSQL database. It is built with Next.js 16, React 19, TypeScript, PostgreSQL with Drizzle ORM, and Tailwind CSS. This documentation takes you from the zip you downloaded to a working till, and then explains each feature's settings.

Read section

Choose Your Path

You can run Posify on your own computer to try it, or put it online as a prebuilt Docker image, through a deploy panel such as Dokploy, or on a Node server you run yourself. Every path ends at the same five-step install wizard in your browser. Pick one path, gather your values in Before You Install, then follow only your path's chapter. If you are not sure, start on your computer: the live business later gets its own database and its own wizard run.

Read section

Quickstart

This is the short local path for people who already have Node.js, pnpm and PostgreSQL. It gives you a private test business on your own computer. If any of these tools are new to you, follow Set Up Your Computer instead: it covers the same steps in more detail.

Read section

Requirements

Posify is one Node.js app that keeps running, one PostgreSQL database, and an S3-compatible bucket for uploads. This page lists the versions, what each path asks of the machine, and the optional extras. The build is the heaviest thing a server ever does for Posify, so where you build decides how much memory the server needs.

Read section

Chapter 01 · Overview

Welcome to Posify

Posify 1.0 is a self-hosted point-of-sale and back-office system for one business with many branches and registers. You install it on your own server, with your own PostgreSQL database. It is built with Next.js 16, React 19, TypeScript, PostgreSQL with Drizzle ORM, and Tailwind CSS. This documentation takes you from the zip you downloaded to a working till, and then explains each feature's settings.

What's in the package

The full source code, the SQL migrations that pnpm db:migrate applies, the install wizard, the demo and maintenance scripts, 18 language files and the test suites. Also deploy/Dockerfile and a GitHub Actions workflow for the prebuilt Docker image, and the guides: README.md, plus UPGRADE.md, DATABASE_COMMANDS.md, DEPLOYMENT.md, HARDWARE.md, FINANCE.md, INVENTORY.md, LOYALTY_GIFT_CARDS.md, MARKETING.md and OFFLINE.md in the docs folder.

One business, many branches

Each branch has its own registers, stock and staff, and reports show one branch or all of them. The install creates the first branch, Main Branch, with one register, Counter 1.

Point of sale

Cash, card and other tenders, deposits, credit sales, returns, voids, holds, cash in and out, and opening and closing the register with X and Z reports. Receipts print, or go out by email or text message (Point of Sale).

Selling offline

When the internet drops, the till keeps selling, prints a receipt with a provisional number, and sends the queued sales by itself when the connection comes back. It needs a production build and an https:// address (Offline Selling).

Products and inventory

Categories, brands, units, variants, barcodes, labels, and CSV import and export. Stock per branch at a moving average cost, with adjustments, transfers between branches, stock counts, a full movement history, low-stock lists and an opening stock import (Inventory).

Purchasing, suppliers and customers

Purchase orders, goods receipts, supplier bills, supplier payments and purchase returns. Customers and suppliers have balances, statements, credit limits and opening dues, with CSV export; customers also import from CSV.

Loyalty, store credit and gift cards

Loyalty points, store credit and gift cards, earned and spent at the till (Loyalty & Gift Cards).

Customers and marketing

Each customer's consent to offers by SMS and by email, with the history of every change. Segments built from rules, campaigns by SMS or email with quiet hours and a daily SMS limit, automations such as birthday wishes, and coupons at the till and on a back-office invoice. Every offer carries an unsubscribe link, and a reply of STOP is honoured. Messages go out through the SMS and email you set up in Settings; Posify has no sending service of its own (Background Jobs for the job campaigns need).

Accounting and tax

Double-entry books: every sale, purchase, payment and stock change posts a journal. Chart of accounts, manual journals, expenses (repeating ones too), cash and bank accounts, profit and loss, balance sheet, cash book, receivables and payables aging, and a books check (Accounting). Tax rates and groups, prices with or without tax, exemptions, and a tax report by month and rate (Tax).

Staff, roles and permissions

Nine built-in roles (Administrator, Manager, Cashier, Accountant, Stock Keeper, Purchaser, Supervisor, Read-only and External Accountant), roles of your own, staff limited to their branches and registers, two-factor sign-in and an activity log (Staff & Roles).

Reports and notifications

46 reports across sales, registers, stock, purchasing, profit, finance and loyalty, with CSV and PDF export. Notifications reach the in-app bell, email, and text messages through Twilio or another SMS provider with an HTTP API; Settings → Notifications decides who hears of what (Notifications).

Hardware

Barcode scanners (the device's camera too), receipt printers, label printers and a cash drawer opened through the receipt printer. Receipts print through the browser's print dialog, or straight to the printer through QZ Tray on the till's computer; the cash drawer needs QZ Tray (Hardware).

18 languages and two themes

English, Bengali, Arabic (right to left), Spanish, French, German, Turkish, Hindi, Dutch, Chinese (Simplified), Japanese, Zulu, Xhosa, Afrikaans, Swahili, Hausa, Yoruba and Igbo (Languages & RTL). Light and dark themes, and an installable app: Chrome and Edge offer Install app once the business has a logo or favicon, and Safari installs from its Share menu.

Start here

New to Posify? Go to Choose Your Path. It compares running Posify on your computer, as a prebuilt Docker image, through a deploy panel such as Dokploy, and on a Node server, and sends you to the right guide. Stuck at any point? Ask support, or request paid installation help.

Try the demo first

See Posify at work before you install it: the public demo is at posify-demo.neurolightstudio.com.

Installing a later release?

1.0 is the first release, so a new install has nothing to upgrade. When a newer release comes out, read Updates & Migrations before you install it: every change a release makes to the tables reaches your database only through pnpm db:migrate.

Chapter 02 · Choose Your Path

Pick how you will install Posify

You can run Posify on your own computer to try it, or put it online as a prebuilt Docker image, through a deploy panel such as Dokploy, or on a Node server you run yourself. Every path ends at the same five-step install wizard in your browser. Pick one path, gather your values in Before You Install, then follow only your path's chapter. If you are not sure, start on your computer: the live business later gets its own database and its own wizard run.

Try it on your computer

Try it

Run a private test copy of Posify on your Windows, Mac or Linux computer, with PostgreSQL on the same computer. Use it to look around before you choose hosting.

  • Suits: trying Posify before you go live
  • Costs: nothing extra; PostgreSQL runs on your computer
  • Skill: install Node.js and PostgreSQL, and type a few commands
  • Build: optional; pnpm dev runs without one
Open this guide

The prebuilt Docker image

Prebuilt image

GitHub Actions builds Posify from your private repository and pushes a ready image to GitHub's container registry. Your server only pulls the image and runs it, so it never needs the memory a build takes. Rolling back means running the previous image tag.

  • Suits: small servers, and quick rollbacks
  • Costs: a server with Docker, a domain, and a private GitHub repository
  • Skill: SSH, Docker commands and GitHub
  • Build: on GitHub Actions; none on your server
Open this guide

Dokploy or another deploy panel

Web panel

A deploy panel such as Dokploy runs the same prebuilt image from a web page. You add the variables, the port and a volume in the panel, and run commands in the container's terminal there. With three optional secrets set, the workflow asks Dokploy to redeploy after each build.

  • Suits: owners who prefer a web panel to the command line
  • Costs: a server for the panel, a domain, and a private GitHub repository
  • Skill: GitHub, a web panel, and a few commands in its terminal
  • Build: on GitHub Actions; none on your server
Open this guide

A Node server you run yourself

Full control

You install Node.js on the server, build Posify there, keep it running under systemd or pm2, and put nginx or Caddy with HTTPS in front. You control every part, and you maintain every part.

  • Suits: developers and agencies who manage servers
  • Costs: a server and a domain
  • Skill: the Linux command line (SSH, systemd or pm2, nginx or Caddy)
  • Build: on your server; several GB of RAM while it runs
Open this guide

Before you start

  • Before You Install walks you through every item below. Do it after you pick your path.
  • The zip you downloaded from CodeCanyon. The app folder inside it is the one that contains package.json.
  • A PostgreSQL database, version 16 or newer, with a user that owns it: on the same server, in Docker, or a managed one such as Neon, Supabase, AWS RDS or DigitalOcean.
  • For a live business: a domain with HTTPS, such as pos.your-domain.com. The offline till and the camera scanner work only on https://.
  • For the prebuilt Docker image and deploy panels: a private GitHub repository with the Posify files. GitHub Actions builds the image from it.
  • Six values you set on every path: DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL, INSTALL_TOKEN and CRON_SECRET.
  • An S3-compatible bucket for images, logos and documents, and an SMTP account for email. Both can wait until after the install (Storage & Media, Email / SMTP).

Compare the four paths

PathBackground jobsShell for commandsUpdating
Your computerNot set up, which is fine for testing. Without them, failed emails are not retried and no digests go out.Yes, your own terminalUnzip the new release into a new folder, copy .env across, install, build and run pnpm db:migrate
Prebuilt Docker imageThe host's crontab, or a hosted cron service, calls the 11 job URLs on your public addressYes: docker exec posify … on the serverPush the release to main and the workflow builds a new image. Pull it, stop the old container, run pnpm db:migrate in a one-off container, then start the new one.
Deploy panelThe panel's cron, or the host's crontab, calls the 11 job URLsYes, the container's terminal in the panelPush the release to main, then redeploy, or let the workflow do it. Run pnpm db:migrate in the terminal, with maintenance mode on.
Node serverYou add 11 crontab lines once (Background Jobs)Yes, over SSHUnzip into a new folder, copy .env, install, build, run pnpm db:migrate, then point the service at the new folder

Background jobs are 11 tasks Posify runs when a scheduler calls their URLs with your CRON_SECRET, such as retrying emails and texts, sending campaigns, the daily digests and the nightly books check (Background Jobs). Settings → Maintenance Mode → Background jobs shows the lines with your address, ready to copy. A shell is a command line on the machine that runs Posify; you need it for pnpm db:migrate and the other maintenance commands. What each path asks of the machine is in Requirements. Before you install a newer release on any path, read Updates & Migrations.

The offline till needs HTTPS

Browsers allow the offline till only on an https:// address, or on localhost on the same machine. A till opened by a plain http:// network address cannot sell offline, and the camera scanner does not work there either. Every live path puts a reverse proxy or a panel with HTTPS in front of Posify (Domain & HTTPS).

Create the tables and run the wizard right after the first deploy

Posify never creates its tables itself: run pnpm db:migrate before the first start, or the wizard's database check stays red. Until the business is set up, every page sends visitors to the install wizard. It asks for your INSTALL_TOKEN, so nobody without it can claim the business, but open it yourself as soon as the deploy finishes. See First Run & Installer.

Building takes several GB of memory

pnpm build is the heaviest thing a server ever does for Posify. On a server with 8 GB of RAM or less, or one that runs the app while it builds, set BUILD_MAX_CPUS=2, or use the prebuilt Docker image so the server never builds. More in Requirements.

Chapter 03 · Quickstart

Run a test business on your computer

This is the short local path for people who already have Node.js, pnpm and PostgreSQL. It gives you a private test business on your own computer. If any of these tools are new to you, follow Set Up Your Computer instead: it covers the same steps in more detail.

Before you start

  • Node.js 24.11.0 or newer; 26 (LTS) is the version .nvmrc names. node -v shows yours.
  • pnpm 10.24.0 through Corepack: after corepack enable, pnpm -v in the app folder prints 10.24.0.
  • PostgreSQL 16 or newer, with an empty database and a user that owns it, for example user posify and database posify. Set Up Your Computer has the commands for Windows, macOS, Linux and Docker.
  • The app folder from the zip, with its hidden files: the folder that contains package.json and .env.example.
  1. 1

    Install the packages

    Open a terminal in the app folder and install the packages Posify needs. The first install downloads a lot.

    1. 1Windows: open the app folder in File Explorer, click the address bar, type powershell and press Enter.
    2. 2macOS or Linux: open Terminal, type cd and a space, drag the app folder into the window, and press Enter.
    3. 3Run the two commands below. Corepack may ask whether to download pnpm: type Y and press Enter.
    bash
    corepack enable
    pnpm install --frozen-lockfile
    ERR_PNPM_LOCKFILE_CONFIG_MISMATCH means hidden files such as .pnpmfile.cjs were lost while copying the folder. A permission error from corepack enable, or corepack not found? Set Up Your Computer shows the fixes.

    Check: The output ends with a line like Done in … using pnpm v10.24.0. Yellow WARN lines are normal. A line with ERR_PNPM is not.

  2. 2

    Make three random values

    Posify needs three secrets: BETTER_AUTH_SECRET signs sessions, INSTALL_TOKEN proves to the install wizard that you own this copy, and CRON_SECRET protects the background jobs. Run the first openssl command once and the second twice, and copy each result. No openssl? Run the node command three times instead.

    With openssl
    bash
    openssl rand -base64 48   # BETTER_AUTH_SECRET
    openssl rand -hex 32      # INSTALL_TOKEN, CRON_SECRET
    No openssl (for example on Windows)? Node works everywhere
    bash
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    Copy the printed value, never the command itself. Keep all three in a password manager.

    Check: Each run prints a different line of 64 characters.

  3. 3

    Create the .env file

    .env holds your settings. Start from .env.example: it has the optional variables commented out. Mail and storage can wait; Settings has a page for each.

    1. 1Copy .env.example to .env with the first box below (macOS and Linux) or the second (Windows PowerShell).
    2. 2Open .env in a text editor: notepad .env on Windows, open -e .env on macOS, nano .env on Linux.
    3. 3Change the six lines in the third box. Put your database user, password and name in DATABASE_URL, and replace each <…> placeholder, the < and > too.
    4. 4Delete the ADMIN_PASSWORD=change-me line, so pnpm create-admin never falls back to that password. Save the file.
    macOS and Linux
    bash
    cp .env.example .env
    Windows (PowerShell)
    powershell
    Copy-Item .env.example .env
    .env: change these lines
    bash
    DATABASE_URL=postgresql://posify:a-strong-password@127.0.0.1:5432/posify
    BETTER_AUTH_SECRET=<the openssl rand -base64 48 value>
    BETTER_AUTH_URL=http://localhost:3000
    NEXT_PUBLIC_APP_URL=http://localhost:3000
    INSTALL_TOKEN=<the first hex value>
    CRON_SECRET=<the second hex value>
    Leave the SMTP and storage lines commented out (they start with #) unless you fill them with real values. Posify treats any value there as a real setting, the example ones too.

    Check: No CHANGE_ME, < or > is left, BETTER_AUTH_SECRET= and INSTALL_TOKEN= are no longer empty, and CRON_SECRET is no longer replace-with-a-long-random-secret.

  4. 4

    Create the tables

    Posify never creates or changes tables by itself. pnpm db:migrate creates every table in the empty database that DATABASE_URL names. Its first line names the database and the server it reached, so you can see it is the right one.

    bash
    pnpm db:migrate
    pnpm db:migrate --list
    password authentication failed means a wrong user or password in DATABASE_URL, or a password character that must be percent-encoded (@ : / # %). permission denied for schema public means the user does not own the database: run ALTER DATABASE posify OWNER TO posify; as the postgres user. More in Database Setup.

    Check: The first command ends with Done: … applied; … in place., and pnpm db:migrate --list ends with … applied, 0 pending. Running it again is harmless: it says The database is up to date. Nothing to apply.

  5. 5

    Build and start

    Build the production version, then start it. The build needs several GB of memory while it runs. Leave the terminal open while you use Posify; Ctrl+C stops it.

    Production build: the offline till works only here
    bash
    pnpm build
    pnpm start
    Or: the development server, with no build
    bash
    pnpm dev
    Port 3000 taken? Start on another one with PORT=3001 pnpm start (PowerShell: $env:PORT = "3001"; pnpm start), and set both URL lines in .env to http://localhost:3001 before you build. Running the App explains both ways to run.

    Check: The build ends with check:chunks — … preloaded chunk references, all in .next. Then pnpm start prints ✓ Ready in … and Posify answers on http://localhost:3000.

  6. 6

    Run the install wizard

    Open http://localhost:3000. Until the business is set up, every page sends you to the wizard at /install. Work through its five steps; First Run & Installer explains each one.

    1. 1System check: the Node.js, Database connection, Authentication secret and Installation token rows must pass; Application URL only warns. Paste your INSTALL_TOKEN value into Installation token, then press Continue.
    2. 2About your business: Business name, Business email (optional), Default language, Currency, Time zone, and whether Prices include tax.
    3. 3Create the owner account: Your name, Email and Password. The owner holds every permission and cannot be removed or suspended by anyone else.
    4. 4Where media is stored: choose your storage provider, paste the bucket's keys and press Test connection, or tick Set storage up later.
    5. 5Ready to install: keep Add sample data ticked for a sample catalogue, suppliers and customers, or untick it to start empty. Press Install.
    A row failed in the System check? Its line names the fix. Correct the value in .env, restart the app (and build again if you changed NEXT_PUBLIC_APP_URL), then press Check again.

    Check: You see "Your business is ready". Press Go to sign in, sign in with the owner account, and the dashboard opens.

This is a test business

Nothing calls the background jobs on your computer, so emails that fail their first try are not retried. When you are ready to go live, pick a path in Choose Your Path. The live business gets its own database and its own wizard run.

Prefer a demo business to the wizard?

Right after pnpm db:migrate, before you open the site, run pnpm db:seed --template=demo. It writes a demo business with 30 days of trading and three demo sign-ins, and closes the wizard. Then sign in as owner@example.com with Owner@123. Never run it on a live business (Database Setup).

Chapter 04 · Requirements

What Posify needs to run

Posify is one Node.js app that keeps running, one PostgreSQL database, and an S3-compatible bucket for uploads. This page lists the versions, what each path asks of the machine, and the optional extras. The build is the heaviest thing a server ever does for Posify, so where you build decides how much memory the server needs.

Software versions

ComponentVersionNotes
PostgreSQL16 or newer; tested on 17One empty database with UTF-8 encoding (the default almost everywhere) and a user that owns it. No extensions, and no superuser rights for the app. One server is enough. See Database Setup.
Node.js24.11.0 or newer; 26 (LTS) recommendedThe minimum is engines in package.json, and the wizard's System check refuses anything older. .nvmrc names 26, which the GitHub build and the Docker image use. Node 22 is no longer supported.
pnpm10.24.0Run corepack enable once; pnpm then uses the version package.json pins. Use pnpm only: the lockfile, pnpm-lock.yaml, is pnpm's.
Operating systemLinux, macOS or WindowsPosify's guides give commands for Debian and Ubuntu, macOS with Homebrew, and Windows PowerShell. The Docker image is based on node:24-bookworm-slim.
BrowserA modern browser on a computer, tablet or phoneThe till runs in the browser. Chrome and Edge offer Install app once the business has a logo or favicon (Settings → Branding); Safari installs from its Share menu. For offline selling, keep the browser's storage: no private windows on a till.
HTTPSRequired in productionBrowsers allow the offline till and the camera scanner only on https://, or on localhost on the same machine. Run Posify behind a reverse proxy with HTTPS, such as nginx or Caddy (Domain & HTTPS).
StorageOne S3-compatible bucketCloudflare R2, AWS S3, DigitalOcean Spaces or MinIO, for product images, logos and documents. You can add it after installing; uploads stay off until you do.
EmailAn SMTP accountFor password resets, emailed receipts and notifications. Set it in Settings → Email or with the SMTP_* variables (Email / SMTP).
Text messagesOptional: Twilio or another SMS gatewayFor receipts, notifications and marketing offers by text. Settings → SMS switches it on; texts go out only after one test message has been sent. Your SMS provider bills every message, and Posify has no sending service of its own (Text Messages).
ChromiumOptionalA headless Chrome or Chromium on the server prints PDF exports and the PDF copy of emailed receipts. Without one, CSV exports still work, the PDF button says "PDF export needs Chrome or Chromium on the server. The CSV works without it.", and receipt emails go out without the PDF.

What each path asks of the machine

PathWhere the build runsBuild memory on your serverNotes
Your computerOn your computerSeveral GB of RAM while pnpm build runs. pnpm dev needs no build.On 8 GB of RAM or less, set BUILD_MAX_CPUS=2 before you build.
Prebuilt Docker imageOn GitHub ActionsNoneThe server pulls the image and runs it. A volume at /app/.next/cache keeps the optimized images across deploys.
Deploy panelOn GitHub ActionsNoneThe panel runs the same image. Mount the same /app/.next/cache volume in the panel.
Node serverOn the serverSeveral GB of RAMOn a server with 8 GB of RAM or less, or one that runs the app while it builds, set BUILD_MAX_CPUS=2. The build is slower but stays within memory.

Uploads live in the bucket, not on the server's disk. Optimized images take up to IMAGE_CACHE_DISK_MB of disk (1024 MB by default), and the pages the app keeps ready take up to PAGE_CACHE_MEMORY_MB of memory (50 MB by default). If PostgreSQL runs on the same machine, it shares the memory with the app and with the build. Still choosing? Compare the paths in Choose Your Path.

The build is the heavy part

pnpm build needs several GB of RAM, on the same machine that may also run the database and serve the tills. On a small server, set BUILD_MAX_CPUS=2, which caps the workers the build starts, or let GitHub Actions build the prebuilt image so the server never builds (Docker Image).

The build needs no database

pnpm build makes no database connection, so the machine that builds needs no access to your PostgreSQL. It does build NEXT_PUBLIC_APP_URL into the app: one build serves one address, and a new address means a new build.

HTTPS for the till

Browsers allow the offline till only on an https:// address, or on localhost on the same machine, and give the camera only to a secure address. A till opened by a plain http:// network address cannot sell offline or scan with the camera.

Eleven background jobs

A scheduler (crontab, your panel's cron or a hosted cron service) must call 11 job URLs with your CRON_SECRET. They retry emails and texts, send marketing campaigns, send digests and reminders, expire store credit, record repeating expenses, clean up, and run the nightly books check (Background Jobs).

Database connections

Each app instance holds up to DATABASE_POOL_MAX connections (10 by default), and PostgreSQL allows 100 by default. With several instances, keep instances × pool size under that limit, with room for pnpm db:migrate and your own sessions, or put PgBouncer or your provider's pooler in between.

Optional extras

Chromium and fonts for PDFs, Twilio or another SMS gateway for text messages (your provider bills every message), and QZ Tray on each till's computer to print receipts with no dialog, open the cash drawer and send labels to a thermal printer (Hardware). Each one is off until you set it up.

Uploads need a bucket

Posify keeps product images, logos and documents in an S3-compatible bucket, not on the server's disk, and uploads stay off until one is set. You may tick Set storage up later in the install wizard; add the bucket under Settings → Storage Settings before you add products (Storage & Media).

PDFs on Linux need fonts

The PDFs use the server's fonts. Without Noto fonts, Bengali, Hindi, Arabic, Chinese and Japanese text prints as empty boxes. On Debian or Ubuntu, sudo apt-get install -y chromium fonts-noto-core fonts-noto-cjk installs Chromium and the fonts together. The shipped deploy/Dockerfile does not include Chromium (Docker Image).

Chapter 05 · Before You Install

Get these ready before you install

Your computer, the prebuilt Docker image, a deploy panel or a Node server: every path needs the same few things. Gather them once here and write each value down in one private place. Your path chapter then tells you where each one goes. Steps marked optional can wait until after the install.

Before you start

  • Your Posify purchase on CodeCanyon.
  • Node.js on your computer for the secret commands below, or openssl, which macOS and Linux usually have. "Install Node.js 26" in Set Up Your Computer shows how to install Node.js.
  • A domain for a live business, for example pos.your-domain.com, and access to its DNS records. You can test on your computer without one.
  • A GitHub account if you will use the prebuilt Docker image or a deploy panel: the image is built from your private repository (Docker Image).
  • A password manager, or another private place, for the values you gather in this chapter.
  1. 1

    Choose where PostgreSQL runs

    Posify keeps everything in one PostgreSQL database, version 16 or newer. It needs one empty database, a user that owns that database, and no extensions. Pick one place for it.

    On the same server
    Install PostgreSQL there, then create the user and the database with the commands below. The app connects to 127.0.0.1:5432.
    In Docker
    The postgres:17 image creates the user and the database itself. The command is in Set Up Your Computer.
    A managed database
    Neon, Supabase, AWS RDS, DigitalOcean and others: create a database on version 16 or newer and copy the connection string the provider gives you.
    Your computer, for testing
    The Linux, macOS, Windows and Docker set-ups are in Set Up Your Computer.
    Your own Linux server: a user and an empty database
    bash
    sudo -u postgres psql -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'"
    sudo -u postgres createdb --owner=posify posify
    Use a password of letters and digits only: it keeps the connection string simple. openssl rand -hex 24 makes one. Put it in place of a-strong-password in every command.

    Check: You have the database name, the user name and its password, and the server's address and port.

  2. 2

    Write down the connection string

    The connection string tells Posify where the database is and how to sign in to it. It goes into DATABASE_URL, which the app, pnpm db:migrate and every database script read.

    USER
    The database user, for example posify.
    PASSWORD
    Its password. Percent-encode @, :, /, # and % in it (see the note).
    HOST
    127.0.0.1 when PostgreSQL runs on the same machine; the container's name, such as posify-pg, when the app runs in another container on the same Docker network; or the host name your provider gives you.
    PORT
    5432, PostgreSQL's usual port.
    DATABASE
    The database name, for example posify.
    Options
    ?sslmode=require at the end for a server across the network. Managed databases usually include it: keep it.
    The finished string looks like this
    txt
    postgresql://posify:a-strong-password@127.0.0.1:5432/posify
    A password with @, :, /, # or % must be percent-encoded in the string, or the user and host are read wrong: @ becomes %40, : %3A, / %2F, # %23 and % %25. Or give the user a password of letters and digits only.

    Check: Your string starts with postgresql://, has no < or > left, and ends with the database name (plus ?sslmode=require for a managed database).

  3. 3

    Generate your secrets

    Posify needs three long random values. One signs sign-in sessions, one proves to the install wizard that you own the server, and one protects the background jobs. The openssl commands work on macOS and Linux; the node command works everywhere.

    1. 1Open a terminal. Windows: press Start, type powershell and press Enter. macOS: Applications → Utilities → Terminal.
    2. 2Run openssl rand -base64 48 and save the line it prints as BETTER_AUTH_SECRET.
    3. 3Run openssl rand -hex 32 and save the line as INSTALL_TOKEN.
    4. 4Run openssl rand -hex 32 again and save the new line as CRON_SECRET.
    5. 5No openssl? Run the node command instead, once for each of the three.
    macOS and Linux
    bash
    openssl rand -base64 48   # BETTER_AUTH_SECRET
    openssl rand -hex 32      # INSTALL_TOKEN, CRON_SECRET
    Windows, macOS and Linux (uses Node.js)
    bash
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    Save the line the command prints, never the command itself, and use a new value for each variable. A hex value suits CRON_SECRET best: crontab treats % as a special character, and a hex secret has none.

    Check: You have three different values of 64 characters each. The two hex values use only the digits 0–9 and the letters a–f.

  4. 4

    Decide the address

    BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL both hold the one address people open Posify on, and links in emails and texts are built from them. Write it exactly as people will type it: https://www.your-domain.com and https://your-domain.com are two different addresses, so pick one.

    Your computer
    http://localhost:3000, as .env.example ships it.
    A live business
    Your domain or subdomain with https://, for example https://pos.your-domain.com. Point it at your server and give it HTTPS before you open the wizard: Domain & HTTPS.
    NEXT_PUBLIC_APP_URL is built into the app when it is built, so changing it later means building again. The prebuilt image takes it from a GitHub variable, and one image serves one address: a second business on another domain needs its own build.

    Check: You have one address written down. It starts with https:// (or is http://localhost:3000), with nothing after the domain name.

  5. 5

    Create a storage bucket

    Product images, logos and documents live in a bucket: online file storage that works like Amazon S3. Posify works with Cloudflare R2, AWS S3, DigitalOcean Spaces and MinIO. Create a bucket and an access key with your provider, then note the values the wizard asks for. Storage & Media has the steps for each provider.

    Cloudflare R2
    Account ID, Bucket name, Access key ID, Secret access key, and Public URL: the bucket's r2.dev address or your own domain. Without a Public URL, every product image returns 403.
    AWS S3
    Region (for example us-east-1), Bucket name, Access key ID, Secret access key, and a Public URL from a bucket policy that allows public reads, or from CloudFront.
    DigitalOcean Spaces
    Datacenter region (for example nyc3), Bucket name, Access key ID and Secret access key. Public URL can stay blank, or hold the Space's CDN endpoint.
    MinIO
    Endpoint URL (the API address on port 9000, not the console), Bucket name, Access key ID, Secret access key and Public URL. Region can stay us-east-1.
    The wizard lets you tick Set storage up later, and you can add the bucket under Settings → Storage Settings after the install. Until a bucket is set, uploads stay off.

    Check: You have every value your provider's row lists.

  6. 6

    Get your SMTP details

    Posify sends password resets, emailed receipts and notifications through your own SMTP account. You can enter the details in Settings → Email after the install, or put them in the SMTP_* variables.

    Host
    Your provider's SMTP server.
    Port
    587 uses STARTTLS; 465 uses TLS.
    User name and password
    The SMTP login your provider gives you.
    From
    The sender, for example Your Business <no-reply@your-domain.com>.

    Check: You have the four values. After the install, send a test email from Settings → Email.

  7. 7

    Optional: a Twilio account for text messages

    Receipts, notifications and marketing offers can go out as text messages through your own Twilio account. Twilio bills every message, per segment. Settings → SMS (Twilio) can also send through another SMS gateway with an HTTP API instead; then gather that provider's details, and expect it to bill you for each message too. Skip this step if you will not send texts.

    Account SID
    It starts with AC.
    Auth token
    Your Twilio auth token.
    Sender
    A Messaging Service SID (it starts with MG, and is preferred when you have one), or a Twilio number in international form such as +15551234567, or a sender ID.
    Credentials alone send nothing. Text messages go out only after SMS is switched on in Settings → SMS (Twilio) and one test message has been sent from there (Text Messages).
  8. 8

    Optional: a QZ Tray key and certificate

    QZ Tray is a small program on the till's computer that prints receipts with no dialog, opens the cash drawer and sends labels to a thermal printer. It takes jobs only from a site it can verify, so Posify signs each job with a key of yours. Make the pair once, on any computer with OpenSSL.

    bash
    openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
      -keyout qz-private-key.pem -out qz-certificate.pem -subj "/CN=Your Business"
    Keep qz-private-key.pem secret: whoever has it can send jobs to every till that trusts the certificate. Hardware shows how to put both into .env and set up each till.

    Check: You have two files, qz-private-key.pem and qz-certificate.pem.

  9. 9

    Write down your environment values

    Environment variables are the settings Posify reads when it starts: each one is a NAME=value line. You start from a copy of .env.example. Put your own values into your notes in the form below. Your path chapter says where they go, and Environment Variables lists every variable.

    Your values (a live business)
    bash
    DATABASE_URL=postgresql://posify:a-strong-password@127.0.0.1:5432/posify
    BETTER_AUTH_SECRET=<the openssl rand -base64 48 value>
    BETTER_AUTH_URL=https://pos.your-domain.com
    NEXT_PUBLIC_APP_URL=https://pos.your-domain.com
    INSTALL_TOKEN=<a 64-character hex value>
    CRON_SECRET=<another 64-character hex value>
    Copy your finished .env into a panel, never .env.example as it is: its placeholders count as real values. ADMIN_PASSWORD=change-me becomes the password pnpm create-admin gives, and the CRON_SECRET placeholder makes every background job answer 401.

    Check: Your notes have the six lines, with no < or > left and no spaces around =, and both URL lines hold the same address.

  10. 10

    Continue with your path

    You now have everything the install needs. Open the chapter for your path. After it, continue with First Run & Installer and the Go-Live Checklist.

    1. 1Your own computer, to try Posify: Set Up Your Computer.
    2. 2The prebuilt Docker image on your server: Docker Image.
    3. 3Dokploy or another deploy panel: Dokploy & Panels.
    4. 4A Node server you run yourself: Node Server.
    5. 5Not sure yet? Compare the paths in Choose Your Path.
    6. 6Prefer to have it installed for you? Request paid installation help.

Keep your values private

The secrets, the database password, the storage keys and the QZ Tray key give control of your business. Keep them in a password manager, not in email, chat, screenshots or support tickets. Never put them in Git: the bundled .gitignore keeps every .env file except .env.example out of the repository, and .dockerignore keeps them out of the image.

Testing first? Use a second database

The install wizard runs once per database, and pnpm db:seed refuses a database the wizard has set up. Give your tests their own database, for example posify_demo at the end of DATABASE_URL, and keep posify for the live business.

Chapter 06 · Set Up Your Computer

Install Node.js, pnpm, PostgreSQL and Posify

Do this once on the computer where you will try Posify. You install Node.js and turn on pnpm, install PostgreSQL and create its database, unzip the download with its hidden files, and install the packages the project needs. Deploying to a server instead? Your deploy chapter covers the server.

Before you start

  • The Posify download from CodeCanyon, or your CodeCanyon sign-in to download it.
  • A Windows, macOS or Linux computer where you may install programs.
  • An internet connection for the downloads.
  1. 1

    Install Node.js 26

    Node.js runs Posify. It needs version 24.11.0 or newer; install 26 (LTS), the version .nvmrc names and the one the Docker image uses.

    1. 1Open nodejs.org/en/download.
    2. 2Pick a version that starts with v24. The labels on the page may differ slightly.
    3. 3Windows: download the Windows Installer (.msi). macOS: download the macOS Installer (.pkg). Run it and keep the default options.
    4. 4Linux: follow the instructions the same page gives for your system, with version 24.
    5. 5Close every terminal window that is open, then open a new one. Windows: press Start, type powershell and press Enter. macOS: Applications → Utilities → Terminal.
    6. 6Run node -v.
    Check the version
    bash
    node -v
    Already have Node.js? If node -v prints v24.11.0 or higher, keep it and go to the next step.

    Check: node -v prints v26 and more numbers. Any version from v24.11.0 works; the install wizard's System check refuses an older one.

  2. 2

    Turn on pnpm

    pnpm installs Posify's packages. Corepack, a helper that comes with Node.js 26, fetches the exact pnpm version that package.json names: 10.24.0. You turn it on once.

    1. 1Run corepack enable in any terminal.
    2. 2Permission error? On Windows, press Start, type powershell, right-click Windows PowerShell → Run as administrator, and run it there. On macOS or Linux, run sudo corepack enable.
    3. 3corepack not recognized or not found? Node.js 25 and newer no longer include it. Run npm install -g corepack first, then corepack enable.
    bash
    corepack enable

    Check: corepack enable prints nothing when it works. You check the pnpm version in the app folder, in the last step.

  3. 3

    Install PostgreSQL on Linux (Debian, Ubuntu)

    Posify needs PostgreSQL 16 or newer. apt installs your distribution's version: Ubuntu 24.04 ships 16 and Debian 13 ships 17, which are fine. Then create a user posify and an empty database posify that the user owns. Put your own password in place of a-strong-password: letters and digits only keep the connection string simple.

    1. Install, then check the version
    bash
    sudo apt install postgresql
    psql --version
    2. Create the user and the database
    bash
    sudo -u postgres psql -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'"
    sudo -u postgres createdb --owner=posify posify
    Debian 12 (PostgreSQL 15) and Ubuntu 22.04 (14) are too old. Add the PostgreSQL project's own repository first (postgresql.org/download/linux), then run sudo apt install postgresql-17.

    Check: psql --version prints 16 or newer. The CREATE ROLE command prints CREATE ROLE, and createdb prints nothing.

  4. 4

    Install PostgreSQL on macOS (Homebrew)

    Homebrew installs PostgreSQL 17 and runs it in the background. Install Homebrew from brew.sh first if you do not have it. Homebrew makes your macOS user the database superuser, so the commands need no sudo.

    1. 1Run the two commands in the first box.
    2. 2postgresql@17 does not put its tools on your PATH. Run brew info postgresql@17, add the folder it names to your PATH, then open a new terminal.
    3. 3Run the commands in the second box, with your own password in place of a-strong-password.
    1. Install and start PostgreSQL 17
    bash
    brew install postgresql@17
    brew services start postgresql@17
    2. Create the user and the database
    bash
    psql postgres -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'"
    createdb --owner=posify posify

    Check: The psql postgres command prints CREATE ROLE, and createdb prints nothing.

  5. 5

    Install PostgreSQL on Windows

    Install PostgreSQL with the installer from postgresql.org/download/windows. It runs PostgreSQL as a Windows service (postgresql-x64-17 for version 17) and asks you for a password for the postgres superuser. Its tools are in C:\Program Files\PostgreSQL\17\bin, which it does not add to your PATH, so the commands below name that folder.

    1. 1Run the installer, and save the postgres password you set in it.
    2. 2Open PowerShell and run the three lines below, with your own password in place of a-strong-password.
    PowerShell: create the user and the database
    powershell
    $pg = "C:\Program Files\PostgreSQL\17\bin"
    & "$pg\psql.exe" -U postgres -h 127.0.0.1 -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'"
    & "$pg\createdb.exe" -U postgres -h 127.0.0.1 --owner=posify posify
    Each command asks for the postgres password you set in the installer.

    Check: psql.exe prints CREATE ROLE, and createdb.exe prints nothing.

  6. 6

    Or: run PostgreSQL in Docker

    If Docker Desktop is installed and running (get Docker Desktop), one command starts PostgreSQL 17 on 127.0.0.1:5432. The container creates the user and the database itself, and keeps the data in a volume named posify-pg-data.

    macOS and Linux
    bash
    docker run -d --name posify-pg --restart unless-stopped \
      -e POSTGRES_USER=posify -e POSTGRES_PASSWORD=a-strong-password -e POSTGRES_DB=posify \
      -p 127.0.0.1:5432:5432 -v posify-pg-data:/var/lib/postgresql/data \
      postgres:17
    Windows PowerShell: the same command on one line
    powershell
    docker run -d --name posify-pg --restart unless-stopped -e POSTGRES_USER=posify -e POSTGRES_PASSWORD=a-strong-password -e POSTGRES_DB=posify -p 127.0.0.1:5432:5432 -v posify-pg-data:/var/lib/postgresql/data postgres:17
    Keep the image on one major version (postgres:17, never latest): a newer major version cannot open the older one's data without an upgrade.

    Check: docker ps lists posify-pg with a status that starts with Up.

  7. 7

    Download and unzip Posify

    The app folder is the folder you install. It contains hidden files, whose names start with a dot, and they must stay with it wherever you copy or upload it.

    1. 1Sign in at codecanyon.net, open Downloads from your account menu, and next to Posify choose Download → All files & documentation. The labels may differ slightly.
    2. 2Unzip the file into a new folder. Windows: right-click it → Extract All… → Extract. macOS: double-click it. Linux: run unzip followed by the file name.
    3. 3If you find another zip inside, unzip that one too. Open folders until you see the app folder: the one that contains package.json, .env.example and next.config.ts.
    4. 4Move the app folder to a place you will keep, for example C:\posify on Windows or a posify folder in your home folder.
    5. 5Show hidden files. Windows 11: File Explorer → View → Show → Hidden items, and also File name extensions. macOS Finder: press Cmd+Shift+. (period). Linux file managers: Ctrl+H.
    Keep every hidden file when you copy, zip or upload the folder: .env.example, .nvmrc, .npmrc, .pnpmfile.cjs, .gitignore, .dockerignore and the .github folder, which holds the workflow that builds the Docker image. Keep pnpm-workspace.yaml and pnpm-lock.yaml too. Without .pnpmfile.cjs the install stops with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH.

    Check: Inside the app folder you see package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .pnpmfile.cjs, .nvmrc and .env.example. Files that start with a dot missing? Turn on hidden files and look again; still missing, download the zip again.

  8. 8

    Open a terminal in the app folder

    From here on, every command runs inside the app folder, the one with package.json.

    1. 1Windows: open the app folder in File Explorer, click the address bar, type powershell and press Enter. PowerShell opens in that folder.
    2. 2macOS: open Terminal, type cd and a space, drag the app folder from Finder into the window, then press Enter.
    3. 3Linux: right-click inside the folder in your file manager → Open in Terminal, or cd into it.
    Check that you are in the right folder
    bash
    # Windows (PowerShell)
    dir package.json
    
    # macOS or Linux
    ls package.json

    Check: The command lists package.json. Cannot find path or No such file or directory means you are in the wrong folder.

  9. 9

    Install the packages

    Check the pnpm version first. Then pnpm downloads everything Posify needs into a new node_modules folder; --frozen-lockfile installs exactly the versions in pnpm-lock.yaml. The first install downloads a lot.

    1. 1Run pnpm -v. The first time, Corepack may say it is about to download pnpm and ask Do you want to continue? [Y/n]. Type Y and press Enter.
    2. 2Run pnpm install --frozen-lockfile and wait until you can type again.
    bash
    pnpm -v
    pnpm install --frozen-lockfile
    ERR_PNPM_LOCKFILE_CONFIG_MISMATCH means hidden files such as .pnpmfile.cjs were lost while copying: unzip the download again with hidden files shown. If pnpm -v does not print 10.24.0, run corepack enable again and open a new terminal.

    Check: pnpm -v prints 10.24.0, and the install ends with a line like Done in … using pnpm v10.24.0. A node_modules folder now sits next to package.json. Yellow WARN lines are normal; a line with ERR_PNPM is not.

Use pnpm only

The lockfile, pnpm-lock.yaml, is pnpm's. Do not run npm install or yarn in the app folder: they do not read it, so they would install other package versions.

What comes next

Create your .env file in Environment Variables, create the tables in Database Setup, then start Posify in Running the App. The Quickstart does the same three in one page.

Chapter 07 · Environment Variables

Set your environment variables

Environment variables are the settings Posify reads when it starts: where the database is, the secret that signs sessions, and the address people open. On your computer and on a Node server they live in a plain text file named .env in the app folder; with the Docker image, in an env file on the server; with a deploy panel, in the panel. Six values are enough to install, and mail, texts and storage can come from Settings instead.

Before you start

  • For a local install: pnpm install --frozen-lockfile finished in the app folder (Set Up Your Computer).
  • Your three secrets and your connection string from Before You Install. The first step below shows the secret commands again.

The values every install needs

VariableLocal value (.env)Live value
DATABASE_URLpostgresql://posify:a-strong-password@127.0.0.1:5432/posifyYour server's string, or the one your provider gives you, usually ending with ?sslmode=require
BETTER_AUTH_SECRETA random value of 32+ characters, from openssl rand -base64 48The same kind of value
BETTER_AUTH_URLhttp://localhost:3000https://pos.your-domain.com: the exact address people open
NEXT_PUBLIC_APP_URLhttp://localhost:3000The same address as BETTER_AUTH_URL. Built into the app: rebuild after a change
INSTALL_TOKENA random value of 32+ characters, from openssl rand -hex 32The same kind of value
CRON_SECRET16+ random characters; openssl rand -hex 32 is betterThe same kind of value. Your scheduler sends it

All six are yours to fill in. On a public address, sign-in works only on the address in the two URL variables.

The groups in .env.example

GroupVariablesWhen you need them
DatabaseDATABASE_URL; commented out: DATABASE_POOL_MAX, DATABASE_DEBUG, RATE_LIMIT_STORE, TRUSTED_PROXIESAlways. The commented ones are optional.
Authentication and appBETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URLAlways.
InstallerINSTALL_TOKENFor a new business. Only the install wizard uses it.
Scheduled jobsCRON_SECRETFor the background jobs.
Demo modeDEMO_MODE, commented outOnly for a public demo.
Owner accountADMIN_NAME, ADMIN_PASSWORDFallbacks for pnpm create-admin.
Email (SMTP)SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, commented outFor email, unless you set it in Settings → Email.
SMS through TwilioTWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_MESSAGING_SERVICE_SID, TWILIO_FROM_NUMBER, commented outOptional; Settings → SMS (Twilio) can hold them instead.
Object storageThe STORAGE_* variables, commented outFor uploads, unless you set storage in the wizard or in Settings → Storage Settings.
QZ TrayQZ_TRAY_CERTIFICATE, QZ_TRAY_PRIVATE_KEY, commented outOptional, for printing with no dialog and for the cash drawer.
Build and cacheBUILD_MAX_CPUS, BUILD_SOURCE_MAPS, PAGE_CACHE_MEMORY_MB, IMAGE_CACHE_DISK_MB, commented outOptional; BUILD_MAX_CPUS=2 on small machines.

The full list, with the variables that are not in .env.example, is at the end of this chapter.

  1. 1

    Make the random values

    BETTER_AUTH_SECRET, INSTALL_TOKEN and CRON_SECRET need long random values. Use the ones you made in "Generate your secrets" in Before You Install, or make them now.

    With openssl
    bash
    openssl rand -base64 48   # BETTER_AUTH_SECRET
    openssl rand -hex 32      # INSTALL_TOKEN, CRON_SECRET
    No openssl (for example on Windows)? Node works everywhere
    bash
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    Run a command once for every value you need, and copy the line it prints, never the command. A hex value suits CRON_SECRET best: crontab treats % as a special character, and a hex secret has none.

    Check: Each run prints a different line of 64 characters.

  2. 2

    Copy .env.example to .env

    In a terminal in the app folder, copy the template. It has the optional variables commented out.

    macOS and Linux
    bash
    cp .env.example .env
    Windows (PowerShell)
    powershell
    Copy-Item .env.example .env
    Windows can hide file extensions, so a file saved as .env.txt still looks like .env in File Explorer. Posify ignores that file. The check below shows the real name.

    Check: dir .env (Windows) or ls -a .env (macOS and Linux) lists a file named exactly .env, next to package.json.

  3. 3

    Fill in your values

    Open .env in a text editor: notepad .env on Windows, open -e .env on macOS, nano .env on Linux. Change the six lines in the box below, replacing each <…> placeholder, the < and > too, and save.

    .env (local)
    bash
    DATABASE_URL=postgresql://posify:a-strong-password@127.0.0.1:5432/posify
    BETTER_AUTH_SECRET=<the openssl rand -base64 48 value>
    BETTER_AUTH_URL=http://localhost:3000
    NEXT_PUBLIC_APP_URL=http://localhost:3000
    INSTALL_TOKEN=<a 64-character hex value>
    CRON_SECRET=<another 64-character hex value>
    .env.example ships ADMIN_PASSWORD=change-me. Left in .env, change-me becomes the password pnpm create-admin gives when you type none. Delete the line, or change it to a strong password.

    Check: No CHANGE_ME, < or > is left, BETTER_AUTH_SECRET= and INSTALL_TOKEN= are filled, and CRON_SECRET is no longer replace-with-a-long-random-secret. Later, the wizard's System check shows the Authentication secret and Installation token rows passed.

  4. 4

    Leave the optional lines for later

    Email, text messages, storage and QZ Tray ship commented out with #. All but QZ Tray can also be set in Settings after the install, and a value saved in Settings wins over .env. To use .env instead, remove the # and put in your real values.

    Email
    The SMTP_* variables, or Settings → Email (Email / SMTP).
    Text messages
    The TWILIO_* variables, or Settings → SMS (Twilio). SMS stays off until you switch it on there (Text Messages).
    Storage
    The STORAGE_* variables, the wizard's storage step, or Settings → Storage Settings (Storage & Media).
    QZ Tray
    QZ_TRAY_CERTIFICATE and QZ_TRAY_PRIVATE_KEY, in the environment only: Settings has no page for them. Restart the app after setting them (Hardware).
    Never uncomment a line with its example value, such as smtp.example.com or your-bucket-name: Posify treats any value there as a real setting.
  5. 5

    Live: put the values where your path reads them

    On a server you use your live values from "Write down your environment values" in Before You Install. Each path reads them from its own place.

    Node server
    A .env file in the app folder on the server, made the same way as here. See Node Server.
    Prebuilt Docker image
    An env file on the server, for example /opt/posify/.env, passed with --env-file. It reads values literally, so write them without quotes. See Docker Image.
    Deploy panel
    The application's environment in the panel: copy every variable from your finished .env into it. See Dokploy & Panels.
    GitHub, for the image
    NEXT_PUBLIC_APP_URL also goes under the repository's Settings → Secrets and variables → Actions → Variables, because the image is built with it. Keep it equal to the value in your env file.
    Copy your finished .env, never .env.example as it is. Its placeholders count as real values: the CRON_SECRET placeholder makes every background job answer 401, and ADMIN_PASSWORD=change-me becomes the password pnpm create-admin gives.

    Check: Every variable from the first table is set, spelled exactly as shown, and no value still contains <, > or CHANGE_ME.

  6. 6

    Rebuild after changing NEXT_PUBLIC_APP_URL

    NEXT_PUBLIC_APP_URL is written into the app when it is built. Changing it in .env afterwards changes nothing until you build again.

    Your computer
    Stop the app with Ctrl+C, run pnpm build, then pnpm start. pnpm dev picks the new value up when you start it again.
    Node server
    Run pnpm build, then restart the service.
    Prebuilt image or panel
    Change the GitHub variable, run the workflow, then deploy the new image.
    BETTER_AUTH_URL must be the same address, but it is read when the app starts, so a restart is enough after changing it. The install wizard warns when either one differs from the address you opened it on.
KeyRequiredDescription
DATABASE_URLRequiredThe PostgreSQL connection string: postgresql://USER:PASSWORD@HOST:5432/DATABASE. The app, pnpm db:migrate and every database script read it. Percent-encode @ : / # % in the password (@ becomes %40), or use letters and digits only. A managed database gives you the string; most want ?sslmode=require at its end. Unset, the app fails with "Please define the DATABASE_URL environment variable inside .env".
DATABASE_POOL_MAXOptionalConnections one app instance may hold open; it caps how much the instance does at once. Default 10, or 3 on a serverless host. With several instances, keep instances × this value under PostgreSQL's max_connections (100 by default), with room for pnpm db:migrate and your own sessions. Commented out in .env.example.
DATABASE_DEBUGOptionaltrue logs every SQL statement and its parameters. Development only: never in production. Commented out in .env.example.
RATE_LIMIT_STOREOptionalWhere API rate-limit counters live. Unset, they are in the database and shared by every app instance. Set memory only if you run exactly one instance. Commented out in .env.example.
TRUSTED_PROXIESOptionalOnly when another CDN or a load balancer forwards from a public address: its IPs and CIDR ranges, comma-separated (the word cloudflare stands for Cloudflare's ranges). They decide which forwarded address counts as the visitor's for rate limits, the sign-in lockout and the maintenance allow-list. A proxy on the same machine or a private network (nginx, Caddy, Traefik, Docker) is trusted already, and Cloudflare needs nothing. Commented out in .env.example.
BETTER_AUTH_SECRETRequiredSigns sessions. 32 or more random characters (openssl rand -base64 48). In production, sign-in refuses to work while it is empty, a known placeholder or shorter than 32 characters, and the wizard's Authentication secret row blocks the install. The wizard checks only this name. .env.example leaves it empty.
BETTER_AUTH_URLRequiredThe public address of the app, for example https://pos.example.com (local: http://localhost:3000). Links in emails are built from it, and it must match the address people open: the wizard warns when it differs. Unset, it follows NEXT_PUBLIC_APP_URL. It is read when the app starts, so a restart is enough after a change.
NEXT_PUBLIC_APP_URLRequiredThe same public address. The server trusts sign-ins from it, and links in emails and texts use it. It is built into the app by pnpm build, so rebuild after changing it; for the prebuilt image, change the GitHub variable and run the workflow. Default http://localhost:3000.
INSTALL_TOKENRequiredRequired for a new business. 32 or more random characters (openssl rand -hex 32). The wizard's first step asks for it to prove that whoever runs the wizard owns the server, and every install step that writes or connects anywhere refuses without it. Restart the app after setting it. Not used once the business is installed. .env.example leaves it empty.
CRON_SECRETRequiredRequired for the background jobs. Your scheduler sends it as Authorization: Bearer followed by the secret. 16 or more random characters; a 64-character hex value (openssl rand -hex 32) is better, and has no % sign, which crontab treats as special. The .env.example placeholder, or a shorter value, is refused, and every job call answers 401.
DEMO_MODEOptionaltrue (or 1, yes, on) turns the site into a public demo: deletes, settings saves, profile changes and actions that reach outside services are refused, and the sign-in page lists the demo accounts. Never set it on a real business. Commented out in .env.example.
ADMIN_NAMEOptionalThe name pnpm create-admin gives a new account when you type none. Unset, the part of the email before @. .env.example sets Owner.
ADMIN_PASSWORDOptionalThe password pnpm create-admin uses when you type none on the command line. Unset, a new account gets a random password, printed once. .env.example ships change-me, which then becomes the real password: give the password on the command line, or change or delete this line.
SMTP_HOSTOptionalYour SMTP server, for password resets, emailed receipts and notifications. Settings → Email can hold it instead and wins over it. Default smtp.gmail.com. Commented out in .env.example: never uncomment it with the example value.
SMTP_PORTOptional587 uses STARTTLS, 465 uses TLS. Default 587.
SMTP_USEROptionalYour SMTP user name. Email from .env alone is sent only when SMTP_USER and SMTP_PASS are both set.
SMTP_PASSOptionalYour SMTP password.
SMTP_FROMOptionalThe sender, for example "Your Business <no-reply@example.com>". In a Docker env file, write it without the quotes.
TWILIO_ACCOUNT_SIDOptionalYour Twilio account SID (it starts with AC). The TWILIO variables only supply credentials: text messages go out only after SMS is switched on in Settings → SMS (Twilio) and one test message has been sent from there. Twilio bills every message, per segment. Commented out in .env.example.
TWILIO_AUTH_TOKENOptionalYour Twilio auth token.
TWILIO_MESSAGING_SERVICE_SIDOptionalA Twilio Messaging Service (it starts with MG). Set this or TWILIO_FROM_NUMBER; this one is preferred when you have one.
TWILIO_FROM_NUMBEROptionalA Twilio number in international form, for example +15551234567, or a sender ID. Used when you have no Messaging Service.
STORAGE_ACCESS_KEY_IDOptionalThe bucket's access key ID. Product images, logos and documents live in the bucket, and uploads stay off until storage is set. The wizard and Settings → Storage Settings can hold the same values and win over these. When STORAGE_BUCKET and both keys are set, the wizard's storage step says so and you can leave it alone. Commented out in .env.example: never uncomment the STORAGE lines with their example values.
STORAGE_SECRET_ACCESS_KEYOptionalThe bucket's secret key.
STORAGE_ACCOUNT_IDOptionalCloudflare R2 only: your R2 account ID.
STORAGE_ENDPOINTOptionalMinIO: your server's S3 API URL. Leave it blank for AWS S3.
STORAGE_REGIONOptionalAWS S3: the bucket's region, for example us-east-1. Cloudflare R2: auto, as .env.example sets it. DigitalOcean Spaces: the datacenter region, for example nyc3.
STORAGE_BUCKETOptionalThe bucket name.
STORAGE_PUBLIC_URLOptionalThe public base URL, or CDN, that uploaded files are served from. Cloudflare R2 needs one: without it, every product image returns 403. Images from your own domain (a CDN domain or a MinIO server) are optimized only when this variable, or STORAGE_ENDPOINT for MinIO, is set when you build; set only in Settings, they are shown at full size. For the prebuilt image, add it to the workflow's Build step.
QZ_TRAY_CERTIFICATEOptionalThe certificate each till's QZ Tray trusts: PEM text on one line, with \n for each line break. With both QZ Tray variables set, receipts can print straight to the printer and the cash drawer opens; unset, receipts print through the browser's dialog and the drawer stays shut. Restart the app after setting them. Commented out in .env.example.
QZ_TRAY_PRIVATE_KEYOptionalThe key that signs the tills' print jobs, in the same one-line form. Keep it secret: whoever has it can send jobs to every till that trusts the certificate.
BUILD_MAX_CPUSOptionalCaps the workers pnpm build starts; unset, one per CPU core. Set 2 when you build on the server that runs the app, or on any host with 8 GB of RAM or less: the build is slower but stays within memory. Commented out in .env.example.
BUILD_SOURCE_MAPSOptionaltrue adds server-side source maps to the build. Off by default.
PAGE_CACHE_MEMORY_MBOptionalMemory, in MB, for the pages and data the app keeps ready; they are kept in memory only, never on disk. Default 50; 0 keeps none. Read when the app starts.
IMAGE_CACHE_DISK_MBOptionalDisk, in MB, for optimized images in .next/cache/images. The least recently used go first. Default 1024.
CHROME_PATHOptionalNot in .env.example. The Chrome or Chromium that prints PDFs, when yours is not in a standard place. Unset, Posify looks in the usual install paths, such as /usr/bin/chromium or /usr/bin/google-chrome on Linux. Without a browser, CSV exports still work and PDFs are unavailable.
NEXT_PUBLIC_DEMO_MODEOptionalNot in .env.example. The same switch as DEMO_MODE: either one turns demo mode on. Never set it on a real business.
NEXT_PUBLIC_APP_NAMEOptionalNot in .env.example. The sender name in emails and texts while the business has no name in Settings → General Settings.
NEXT_PUBLIC_SUPPORT_EMAILOptionalNot in .env.example. An address the "no access" page offers for help.
CLOUDFLARE_R2_PUBLIC_URLOptionalNot in .env.example. An older name for a public bucket URL: images from it are allowed like those from STORAGE_PUBLIC_URL. Use STORAGE_PUBLIC_URL instead.
AUTH_SECRET / NEXTAUTH_SECRETOptionalNot in .env.example. Older names, read only when BETTER_AUTH_SECRET is empty. The install wizard checks BETTER_AUTH_SECRET only, so set that instead.

Two sources for credentials

SMTP, SMS and storage can be set in .env or in Settings. A value saved in Settings always wins, and the .env variable is a fallback for each field. So a server can start from .env, and you can change single fields in Settings later.

Keep .env out of Git and images

The bundled .gitignore ignores every .env file except .env.example, and .dockerignore keeps every .env file out of the Docker image. Leave both as they are, and never commit your .env.

Chapter 08 · Database Setup

Set up the database

Posify keeps everything in one PostgreSQL database: every sale, product, customer, journal and setting. The app never creates or changes its tables by itself; pnpm db:migrate does, once on a new install and again after every upgrade. This chapter covers the connection string, the migrations, demo data and emptying a test database.

Before you start

  • PostgreSQL 16 or newer with an empty database and a user that owns it, as in Set Up Your Computer, or a managed database.
  • A .env file in the app folder (Environment Variables).
  • pnpm install --frozen-lockfile finished in the app folder.

Where PostgreSQL can run

OptionDATABASE_URLNotes
On the same machinepostgresql://posify:a-strong-password@127.0.0.1:5432/posifyLinux, macOS or Windows, installed as in Set Up Your Computer.
Docker, app on the hostpostgresql://posify:a-strong-password@127.0.0.1:5432/posifyThe posify-pg container publishes port 5432 on 127.0.0.1 only.
Docker, app in another containerpostgresql://posify:a-strong-password@posify-pg:5432/posifyPut both containers on one Docker network (docker network create posify) and use the database container's name as the host. Inside a container, 127.0.0.1 is that container itself.
A managed databaseThe string the provider gives youNeon, Supabase, AWS RDS, DigitalOcean and others, on version 16 or newer. Keep the ?sslmode=require it usually ends with.

The database commands

CommandWhat it doesWrites?
pnpm db:migrateCreates and updates Posify's tablesYes; not with --list or --dry-run
pnpm db:seedA small demo business with three demo sign-insYes
pnpm db:seed --template=demoThe full demo business, with up to 30 days of tradingYes
pnpm db:seed:auditChecks a demo database's books and stockNo
pnpm db:resetDeletes every record in Posify's tablesYes, everything
pnpm create-adminCreates or restores an owner account (Backups & Recovery)Yes
pnpm accounting:reconcileChecks the books against the documents and posts what is missing (Backups & Recovery)Not with --dry-run

Run each from the app folder. pnpm db:migrate reads DATABASE_URL from the environment first, then from .env; the others read .env. Every one but pnpm db:migrate needs Posify's tables, and on a database without them it stops and asks you to run pnpm db:migrate first.

  1. 1

    Put the connection string in .env

    DATABASE_URL holds the connection string, in the form postgresql://USER:PASSWORD@HOST:PORT/DATABASE. Set it in .env and save. If the app is running, restart it.

    Port
    5432 is PostgreSQL's usual port.
    A password with special characters
    Percent-encode @, :, /, # and % in it (@ becomes %40, : %3A, / %2F, # %23, % %25), or the user and host are read wrong.
    A server across the network
    Add ?sslmode=require at the end: it usually wants TLS. Its listen_addresses and pg_hba.conf decide whether it accepts the app's connections. Keep it closed to the internet, and open it only to the app's address.
    .env
    bash
    DATABASE_URL=postgresql://posify:a-strong-password@127.0.0.1:5432/posify

    Check: The line starts with DATABASE_URL=postgresql://, has no spaces, and names your user, password, host, port and database.

  2. 2

    Managed database: pick the right string

    Some providers give two strings: a pooled one (PgBouncer, Supabase's pooler, Neon's -pooler host) and a direct one. The app works through either; use the pooled one when you run many app instances. Run pnpm db:migrate over the direct one, by putting it in front of the command.

    macOS and Linux
    bash
    DATABASE_URL="postgresql://…direct…" pnpm db:migrate
    Windows (PowerShell)
    powershell
    $env:DATABASE_URL = "postgresql://…direct…"; pnpm db:migrate
    In PowerShell the value stays set until you close that terminal or run Remove-Item Env:DATABASE_URL. Do one of the two before you run anything else there.
  3. 3

    Check the connection

    Before you create the tables, check that the string works and that the server is new enough. psql comes with PostgreSQL. On Windows it is in C:\Program Files\PostgreSQL\17\bin; on macOS, add Homebrew's folder to your PATH first, as in Set Up Your Computer.

    bash
    psql "postgresql://posify:a-strong-password@127.0.0.1:5432/posify" -c "SELECT version()" -c "SHOW server_encoding"
    Not UTF8? Create the database again with createdb --encoding=UTF8 --template=template0 --owner=posify posify.

    Check: You see PostgreSQL 16 or newer, and UTF8.

  4. 4

    See what will be applied

    Posify's tables come from the SQL migrations in lib/pg/migrations, one folder per change. pnpm db:migrate applies the ones your database does not have yet, oldest first, and records each one. These two flags look without writing anything.

    bash
    pnpm db:migrate --list      # every migration: applied (and when) or pending
    pnpm db:migrate --dry-run   # the pending ones; writes nothing

    Check: The first line reads like db:migrate — posify on 127.0.0.1:5432: the database and the server it reached, never the password. On a new database, every migration is pending.

  5. 5

    Create the tables

    Run pnpm db:migrate once on the empty database, before the first start. Every pending migration is applied in one transaction: all of them, or none.

    bash
    pnpm db:migrate
    The app never creates or changes tables when it starts. Until the migrations have run, the wizard's Database connection row says "The database is empty: the tables are not there yet. Run pnpm db:migrate, then check again."

    Check: The output ends with Done: … applied; … in place., and pnpm db:migrate --list now ends with … applied, 0 pending.

  6. 6

    Read what pnpm db:migrate printed

    Every run starts with the line that names the database. What follows tells you how it went.

    Done: … applied; … in place.
    Every pending migration was applied.
    The database is up to date. Nothing to apply.
    Nothing was pending. Running it twice is harmless.
    Another pnpm db:migrate is running on this database
    Two runs take turns: this one waits for the other to finish.
    A migration failed, so the transaction was rolled back
    Nothing was applied. The line below it names the cause: fix that and run the command again.
    This database has … migration(s) this code does not have
    A newer or a different build of Posify migrated it. Run that build, or restore the backup you took before upgrading. Nothing was applied.
    … was changed after this database applied it
    A warning, not a stop: a migration that already ran was edited since. A released migration is never changed. If you edited one yourself, put the original back and add a new migration instead.
    permission denied for schema public
    The user in DATABASE_URL must own the database: run ALTER DATABASE posify OWNER TO posify; as the postgres user.
    password authentication failed for user
    The user or the password is wrong, or the password holds a character that must be percent-encoded.
    DATABASE_URL is not set
    Put it in .env, or in the environment.
  7. 7

    Optional: load the small demo business

    pnpm db:seed sets up a small business to try Posify with, instead of the install wizard: the business settings (named "Demo Shop", or the name you give with --business), the built-in roles, three demo sign-ins, the branch Main Branch with its register Counter 1, the default units, the system accounts of the chart of accounts and the first expense categories. It writes no products and no sales, and it marks the business installed, so the wizard closes. The business's time zone comes from the TZ environment variable, else UTC; change it later in Settings → General Settings.

    bash
    pnpm db:seed
    pnpm db:seed --business "Corner Shop"
    It refuses a database that is already installed, by the wizard or by an earlier seed: This database is already installed. --force seeds it anyway; do that only on a copy you can throw away. The demo passwords are published, so never seed a live business.

    Check: The output ends with Sign in with: and the three sign-ins: owner@example.com / Owner@123 (Administrator, and the business's owner), manager@example.com / Manager@123 (Manager) and cashier@example.com / Cashier@123 (Cashier).

  8. 8

    Optional: load the full demo business

    pnpm db:seed --template=demo writes a demo business with a month of history, for demos and for checking reports and the books. It wants an empty database: on a new one, run pnpm db:migrate first instead of the reset. It makes the history through Posify's own services, as the till and the back office would, which takes a few minutes, then audits the result and fails if the books or the stock do not add up.

    1. 12 branches and 3 registers.
    2. 27 people in six of the built-in roles. Only the three demo sign-ins can sign in.
    3. 38 categories, 60 products and 26 variants, every one with a barcode, plus 2 units and 2 tax groups.
    4. 45 suppliers and 40 customers. Their phone numbers use the 010 prefix, which no mobile operator serves, so a text sent to one reaches nobody.
    5. 5Marketing already in use: customers with their consent to offers and their birthdays, three offer templates in English and Bangla, two segments, the coupon PLAT10 and two finished campaigns with their results. The automations are off. Nothing in the demo is really sent.
    6. 630 days of trading up to today, or what --days asks for (1 to 30): sales, returns, purchase orders, goods receipts, supplier bills and payments, expenses, transfers between branches and customer receipts.
    7. 7The settings: Bangladeshi taka (BDT), the Asia/Dhaka time zone, all 18 languages, every tender, deposits, loyalty and gift cards switched on. Change any of them in Settings.
    bash
    pnpm db:reset                          # it wants an empty database
    pnpm db:seed --template=demo           # 30 days of trading
    pnpm db:seed --template=demo --days 7  # or fewer days (1–30)
    Running a public demo site? Also set DEMO_MODE=true and restart: the sign-in page then lists the demo accounts, and deletes and settings saves are refused. Never set it on a real business.

    Check: Near the end you see ✓ Audit: the books balance, the stock adds up, no credential was written, then Sign in with: and the three demo sign-ins.

  9. 9

    Optional: check a demo database

    pnpm db:seed:audit checks a database made by pnpm db:seed --template=demo again: every demo record in place, no credential beyond the three demo sign-ins, stock levels equal to their movements, and books that balance. It reads only.

    1. 1--no-history: check only the demo records and the credentials, not the books, stock and history.
    2. 2--no-coverage: skip the check that every kind of event happened; useful after a short --days history.
    3. 3--json: print the whole report as JSON.
    bash
    pnpm db:seed:audit
    pnpm db:seed:audit --no-history
    pnpm db:seed:audit --json

    Check: Every line starts with ✓, and the command exits with code 0. A ✗ line names the check that failed, and the exit code is 1.

  10. 10

    Empty a test database

    pnpm db:reset deletes every record in Posify's own tables, sign-ins and sessions included. It keeps the tables, their indexes and the record of the migrations, so there is no need to run pnpm db:migrate again, and the document counters start again from the beginning. Any other table in the database is left untouched and listed at the end.

    bash
    pnpm db:reset
    It deletes data and does not ask first. Check which database DATABASE_URL in .env names before you press Enter. A listed table that is not Posify's usually means a shared database, or that .env names the wrong one.

    Check: The output ends with Database reset completed successfully! and Total rows deleted: …. Restart the app, and the install wizard opens again.

Never seed or reset a live business

Never point pnpm db:seed or pnpm db:reset at a live business. The seed writes demo sign-ins whose passwords are published in this guide. The reset deletes every sale, product, customer and journal without asking. Use a separate database, another name at the end of DATABASE_URL, for trying things out.

Run the migrations after every upgrade

Nothing but pnpm db:migrate changes a business's tables, and the app never does it when it starts. After you put a new release in place, back up, then run it before the new code starts (Updates & Migrations, Backups & Recovery). Never run drizzle-kit push or drizzle-kit generate against a business's database.

Chapter 09 · Running the App

Start Posify on your computer

Start Posify, open it in your browser and run the install wizard. pnpm dev runs a development server for trying Posify and changing the code. pnpm build and pnpm start run the production build, the only one with the offline till. A live business runs on a server: see your deploy chapter.

Before you start

  • Set Up Your Computer is done: Node.js, pnpm, PostgreSQL, and pnpm install --frozen-lockfile finished in the app folder.
  • Your .env file sits next to package.json, with the values from Environment Variables.
  • The tables exist: pnpm db:migrate ran against the database in DATABASE_URL (Database Setup).

Running the app

ScriptWhat it does
pnpm devA development server on http://localhost:3000. No offline till.
pnpm buildThe production build. It skips the type check on purpose, and ends by checking the pages' preload lists (check:chunks), repairing what it can.
pnpm startThe production server, on port 3000 unless PORT says otherwise.

Database and maintenance

ScriptWhat it does
pnpm db:migrateCreates and updates Posify's tables: applies every migration the database lacks, in one transaction. --list and --dry-run write nothing. Run it on a new install and after every upgrade.
pnpm create-adminpnpm create-admin <email> [password] [name] [--reset-2fa] creates or restores an owner account.
pnpm accounting:reconcileChecks the books against the documents and posts any journal that is missing. --dry-run writes nothing.
pnpm db:seedA small demo business with three demo sign-ins. Refuses a database the wizard has set up. Not for a live business.
pnpm db:seed --template=demoThe full demo business with 30 days of trading. Wants an empty database.
pnpm db:seed:auditChecks a demo database: the books balance and the stock adds up. Reads only.
pnpm db:resetDeletes every record in Posify's tables, and keeps the tables. Never on a live business.

Each reads DATABASE_URL. Details in Database Setup and Backups & Recovery.

For people who change the code

ScriptWhat it does
pnpm typecheckThe type check. pnpm build skips it, so run this before you ship a change.
pnpm lintESLint, errors only.
pnpm testThe unit tests (Vitest).
pnpm check:i18nEvery language file has every key of locales/en.json, with the same arguments.
pnpm check:chunksAfter a build: every script a page preloads exists.
pnpm check:build-dbBuilds with the database address pointed at a counter: the build must make no database connection.
  1. 1

    Start the development server

    The development server runs Posify on this computer while its terminal window stays open. Use it to look around or to work on the code.

    1. 1Open a terminal in the app folder, the folder with package.json.
    2. 2Run pnpm dev.
    3. 3Wait for the line that starts with ✓ Ready in, and leave the window open.
    bash
    pnpm dev
    Port 3000 is in use … using available port 3001 instead means another program has port 3000, often an older pnpm dev. Close it, press Ctrl+C here and run pnpm dev again: your .env addresses say port 3000.

    Check: The Local: line shows http://localhost:3000, the Environments: line lists .env, and ✓ Ready in … appears. No Environments: line? Posify did not find your .env: check that it sits next to package.json and is not named .env.txt.

  2. 2

    Open Posify in your browser

    Open http://localhost:3000. Type localhost, as in your .env. The development server prepares each page the first time you open it, so the first page can take a while.

    Not sent to /install? When the database server cannot be reached, pages show an error instead of sending you on. Open http://localhost:3000/install yourself: the Database connection row names the fix. If /install answers "not found", this database already holds a business, for example from pnpm db:seed: sign in at http://localhost:3000/login instead.

    Check: The address changes to http://localhost:3000/install, and the page says "Set up your business", with "System check" below it.

  3. 3

    Run the install wizard

    Complete the wizard's five steps as described in First Run & Installer. On this computer, the Application URL row passes when both URL values in .env are http://localhost:3000. No bucket yet? Tick Set storage up later on the storage step.

    Do not run pnpm create-admin or pnpm db:seed before the wizard. Both mark the business installed, and the wizard then closes for good.

    Check: You are signed in, and the dashboard opens. A card saying "Background jobs are not scheduled yet" is expected here: nothing calls the job URLs on your computer.

  4. 4

    Run the production build

    A server runs the production build, and only the production build has the offline till. You can run it here too.

    1. 1Stop pnpm dev with Ctrl+C: the production server needs port 3000 too.
    2. 2Run pnpm build and wait until it finishes.
    3. 3Run pnpm start, then open http://localhost:3000.
    Build, then start
    bash
    pnpm build
    pnpm start
    The build never connects to the database, so it works while PostgreSQL is stopped; start the database before pnpm start. pnpm start without a build stops with Could not find a production build.

    Check: The build ends with check:chunks — … preloaded chunk references, all in .next. pnpm start prints ✓ Ready in …, and http://localhost:3000 opens Posify.

  5. 5

    Use another port

    Posify listens on port 3000. To use another one, set PORT in the command itself: the port is chosen before .env is read, so a PORT line in .env does nothing.

    macOS and Linux
    bash
    PORT=3001 pnpm start
    Windows (PowerShell)
    powershell
    $env:PORT = "3001"; pnpm start
    Change both URL values in .env to the new address, for example http://localhost:3001, and run pnpm build again. Otherwise the wizard's Application URL row warns, and links in emails point at the old address.
  6. 6

    Check types and run tests (people who change the code)

    You need this only if you change the code. pnpm build skips the type check on purpose, so run these before you ship a change.

    bash
    pnpm typecheck
    pnpm lint
    pnpm test
    pnpm check:i18n
    Low on memory for the type check
    bash
    NODE_OPTIONS=--max-old-space-size=8192 ./node_modules/.bin/tsc --noEmit -p tsconfig.check.json

    Check: Each command finishes without listing errors.

  7. 7

    Stop the server

    Click the terminal window where Posify runs and press Ctrl+C. Your data stays in the database. To continue later, open a terminal in the app folder and start Posify again.

    On Windows you may see Terminate batch job (Y/N)?. Type Y and press Enter.

    Check: The terminal shows its prompt again, and http://localhost:3000 no longer opens.

Why the offline till needs a production build

The browser keeps its offline copy of the till through a service worker, and Posify registers it only in a production build. pnpm dev has none, so its till cannot open offline. Browsers also allow it only on https://, or on localhost on the same machine: here, http://localhost:3000 after pnpm build and pnpm start is enough. Open the till once while online; Offline Selling explains the rest.

Trying the till on a tablet or phone

Run the wizard on this computer first. Then open the Network: address the terminal shows on the other device: signing in works from a private network address. A plain http:// address has no offline till and no camera scanner, though; for those, the device needs an https:// address (Domain & HTTPS).

Chapter 10 · Docker Image

Run the prebuilt Docker image

GitHub Actions builds Posify into a ready image and keeps it in your GitHub account. Your server only pulls the image and runs it, so the build, which needs several GB of memory, never runs on the machine that also holds the database and serves the tills. You set GitHub up once; after that, every push to main makes a new image.

Read this first

One image serves one address

NEXT_PUBLIC_APP_URL is written into the app when GitHub builds the image. Changing it in the server's env file changes nothing: change the GitHub variable, run the workflow and deploy the new image. A second business on another domain needs its own build.

  • The build makes no database connection, so GitHub needs no access to your PostgreSQL.
  • deploy/Dockerfile never compiles. It only packages the build GitHub made, and refuses to make an image without one: use it through the workflow.
  • The app never creates or changes its tables. You run pnpm db:migrate in a one-off container before the first start and after every update.

Before you start

  • A GitHub account, and the unzipped Posify download (the folder with package.json).
  • A server with Docker Engine (Docker's install guide). It never builds, so it needs no build memory.
  • PostgreSQL 16 or newer that the container can reach: in a container on the same Docker network (step 7), or a managed database (Database Setup).
  • A domain you can point at the server, and nginx or Caddy for HTTPS (Domain & HTTPS).
  • Your values for the env file (Environment Variables).

What is in the download

FileWhat it does
.github/workflows/deploy-image.ymlOn every push to main, or when you run it by hand: installs, type-checks, builds, and pushes an image to the GitHub Container Registry as ghcr.io/<account>/<repo>:main and :<short commit SHA>.
deploy/DockerfileAssembles the image from the build GitHub made. Based on node:24-bookworm-slim; listens on port 3000; runs pnpm start. It sits under deploy/, not the root, so that a deploy panel does not pick it up for a build of its own.
.dockerignoreKeeps node_modules, .next/cache, every .env file, .git and the tests out of the image.

The image carries the migrations (lib/pg/migrations) and keeps the development tools (tsx), so pnpm db:migrate, pnpm create-admin and pnpm accounting:reconcile work from a terminal inside the container.

  1. 1

    Put Posify in a private GitHub repository

    The workflow runs in your own repository. Create a private repository on GitHub and push the unzipped Posify folder to its main branch, without .env, node_modules or .next.

    1. 1Show hidden files before you copy anything: the workflow is in .github, and .dockerignore starts with a dot too. Windows Explorer: View → Show → Hidden items. macOS Finder: Cmd+Shift+. (full stop).
    2. 2To build from other branches as well, add them under on: push: branches: in .github/workflows/deploy-image.yml.
    Never commit a .env file: it holds your secrets. The server keeps its own env file (step 6).

    Check: The repository's main branch shows .github, deploy and package.json at its top level.

  2. 2

    Set the NEXT_PUBLIC_APP_URL variable

    The workflow builds your public address into the image. On GitHub, open the repository → Settings → Secrets and variables → Actions → Variables, and add a repository variable.

    Name
    NEXT_PUBLIC_APP_URL
    Value
    Your public address, for example https://pos.example.com.
    Without it, the run stops at its Require NEXT_PUBLIC_APP_URL step with Set NEXT_PUBLIC_APP_URL under Settings -> Secrets and variables -> Actions -> Variables. Use the same address in the server's env file later.

    Check: The Variables tab lists NEXT_PUBLIC_APP_URL with your address.

  3. 3

    Add Chromium for PDF exports (optional)

    The deploy/Dockerfile as shipped does not include Chromium. Without it, CSV exports still work, the PDF buttons say PDF export needs Chrome or Chromium on the server, and receipt emails go out without the PDF. To add it, put these lines after RUN corepack enable in deploy/Dockerfile, and commit the change before the first build.

    1. 1The Noto fonts let Bengali, Hindi, Arabic, Chinese and Japanese text print instead of empty boxes.
    2. 2The image gets larger. The container runs as root; Posify then starts Chromium with --no-sandbox itself.
    3. 3Adding it later works the same way: change the file, push, and run the new image.
    deploy/Dockerfile
    dockerfile
    RUN apt-get update \
     && apt-get install -y --no-install-recommends chromium fonts-noto-core fonts-noto-cjk \
     && rm -rf /var/lib/apt/lists/*
    ENV CHROME_PATH=/usr/bin/chromium

    Check: Once the app runs: Statements → Profit and loss → PDF downloads a PDF.

  4. 4

    Build the first image

    Push to main, or open the Actions tab → Deploy image → Run workflow. The run installs the packages, runs pnpm typecheck, builds the app and pushes the image.

    1. 1Wait for the green check. If you changed the code and the type check fails, no image is pushed.
    2. 2Open your GitHub account's (or organization's) Packages: the image is there, private by default.
    3. 3Each run tags the image twice: main, and its short commit SHA, for example 8a45278. The SHA tags are your way back to an earlier build.

    Check: The Deploy image run has a green check, and Packages lists the image with the tag main.

  5. 5

    Log the server in to ghcr.io

    The image is private, so the server logs in once with a GitHub personal access token (classic) that has the read:packages scope.

    1. 1On GitHub: your profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Tick only read:packages, generate the token and copy it.
    2. 2On the server, run the command below with your token and your GitHub user name.
    bash
    echo "YOUR-TOKEN" | docker login ghcr.io -u YOUR-GITHUB-USER --password-stdin
    When the token expires, docker pull is refused. Make a new token and log in again.

    Check: Docker prints Login Succeeded.

  6. 6

    Write the env file

    The container reads its settings from an env file on the server: /opt/posify/.env in these examples. Start from .env.example in the download and fill it in as Environment Variables explains.

    1. 1--env-file reads each value literally. Write values without quotes: SMTP_FROM=Your Business <no-reply@example.com>, not SMTP_FROM="Your Business <no-reply@example.com>". The same goes for the one-line QZ_TRAY_* values.
    2. 2NEXT_PUBLIC_APP_URL must equal the GitHub variable from step 2, and BETTER_AUTH_URL must be the same address.
    3. 3DATABASE_URL must be reachable from inside the container. There, 127.0.0.1 is the container itself (step 7).

    Check: The file holds your own values, with no quotes around them and no placeholder left.

  7. 7

    Let the container reach PostgreSQL

    With a managed database, skip this step and use the connection string it gives you (keep its ?sslmode=require). For PostgreSQL in Docker on the same server, put it and Posify on one Docker network, and use the database container's name as the host.

    1. 1Replace a-strong-password in both places. Letters and digits only keep the connection string simple.
    2. 2Add --network posify to the docker run commands in steps 8 and 9.
    3. 3Keep the image on one major version (postgres:17, never latest): a newer major version cannot open the older one's data without an upgrade.
    A Docker network and PostgreSQL 17 on it
    bash
    docker network create posify
    docker run -d --name posify-pg --network posify --restart unless-stopped \
      -e POSTGRES_USER=posify -e POSTGRES_PASSWORD=a-strong-password -e POSTGRES_DB=posify \
      -v posify-pg-data:/var/lib/postgresql/data postgres:17
    The matching line in /opt/posify/.env
    bash
    DATABASE_URL=postgresql://posify:a-strong-password@posify-pg:5432/posify

    Check: docker ps lists posify-pg with a status that starts with Up.

  8. 8

    Pull the image and create the tables

    Run pnpm db:migrate once, in a one-off container, before the app starts. It reads DATABASE_URL from the env file, like the app does.

    1. 1Write your account and repository names in lowercase, as the Packages page shows them.
    2. 2With the network from step 7, write --network posify after --rm.
    bash
    docker pull ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main
    
    docker run --rm --env-file /opt/posify/.env ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main pnpm db:migrate

    Check: The first line names the database and server it reached, for example db:migrate — posify on posify-pg:5432, and the run ends with a Done: line.

  9. 9

    Start the app

    Run the container in the background. It restarts with Docker, listens only on the server itself, and keeps optimized images in a volume.

    1. 1With the network from step 7, add --network posify to the first line.
    2. 2-p 127.0.0.1:3000:3000 keeps the app's port private. Only a reverse proxy on the server reaches it.
    3. 3The volume at /app/.next/cache keeps optimized images across deploys, so they are not made again after every update.
    4. 4In PowerShell, put the whole command on one line, or end each line with a backtick instead of \.
    bash
    docker run -d --name posify --restart unless-stopped \
      --env-file /opt/posify/.env \
      -p 127.0.0.1:3000:3000 \
      -v posify-next-cache:/app/.next/cache \
      ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main
    Docker reads the env file when it creates the container. After you change the file, run docker rm -f posify and the docker run command again: docker restart keeps the old values.

    Check: docker ps shows posify with a status that starts with Up, and curl -I http://127.0.0.1:3000 answers 307 with a location that ends in /install.

  10. 10

    Put HTTPS in front

    Point your domain at the server and put a reverse proxy with HTTPS in front of 127.0.0.1:3000. Domain & HTTPS covers the domain. The nginx and Caddy configurations are in Node Server, step "Put nginx or Caddy in front": they work the same in front of the container.

    Check: https://pos.example.com opens with a padlock and shows the install wizard.

  11. 11

    Run the install wizard

    Open your address and finish the wizard right away: it creates the owner account. First Run & Installer explains each screen.

    Check: The wizard says "Your business is ready", and you can sign in.

  12. 12

    Schedule the background jobs

    Nothing calls Posify's eleven jobs until you add them. With the image, run the crontab on the host (or in your panel's cron), calling your public address with CRON_SECRET. Background Jobs has the ready crontab.

    Check: Settings → Maintenance Mode → Background jobs shows each job as Running after its first call.

  13. 13

    Run commands inside the container

    pnpm db:migrate reads DATABASE_URL from the container's environment. The other database commands read a .env file, which the image does not hold, so create an empty one first. The container's environment still supplies every value.

    1. 1posify is the app container's name in these examples.
    2. 2Each docker run makes a new container without the empty .env: run touch .env again after an update.
    3. 3The image has no pg_dump. Take backups from the host or from the database's own container (Backups & Recovery).
    bash
    docker exec posify pnpm db:migrate --list
    docker exec posify touch .env
    docker exec posify pnpm create-admin you@example.com "a-new-password"
    docker exec posify pnpm accounting:reconcile --dry-run

    Check: pnpm db:migrate --list ends with … applied, 0 pending.

  14. 14

    Update to a new release

    Turn on maintenance mode and back up the database first (Updates & Migrations). Put the new release into your repository and push. When the workflow's run is green, run these on the server.

    1. 1Add --network posify to both docker run commands if you use that network.
    2. 2The migrations run in the one-off container before the new app starts.
    3. 3Then turn maintenance mode off.
    bash
    docker pull ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main
    docker rm -f posify
    docker run --rm --env-file /opt/posify/.env ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main pnpm db:migrate
    docker run -d --name posify ...   # the same command as in step 9
    docker exec posify sh -c "touch .env && pnpm accounting:reconcile --dry-run"

    Check: The reconcile ends with Trial balance: … — balanced and Dry run: nothing was written.

  15. 15

    Roll back to an earlier image

    Every image is also tagged with its short commit SHA. To go back, run the previous SHA's tag instead of main, with the same command as in step 9.

    bash
    docker rm -f posify
    docker run -d --name posify --restart unless-stopped \
      --env-file /opt/posify/.env \
      -p 127.0.0.1:3000:3000 \
      -v posify-next-cache:/app/.next/cache \
      ghcr.io/YOUR-ACCOUNT/YOUR-REPO:PREVIOUS-SHA
    If the new release's migrations already ran, the old code may not run on the new tables. Restore the backup you took before upgrading too (Backups & Recovery).

Building deploy/Dockerfile on its own fails

A panel or a docker build that uses deploy/Dockerfile on the source alone stops with ERROR: no prebuilt .next/ in the build context. Build images through the workflow, or build on the server as Node Server shows.

Images served from your own domain

Images are optimized when they come from R2 (r2.dev), S3, CloudFront or Spaces addresses. If you serve them from your own domain (a CDN, or a MinIO server), STORAGE_PUBLIC_URL (or STORAGE_ENDPOINT for MinIO) must be set when the app is built: for the image, add the variable to the workflow's Build step environment. Set only in Settings, such images are shown at full size (Storage & Media).

Chapter 11 · Dokploy & Panels

Run the image in Dokploy or another panel

A deploy panel such as Dokploy runs the prebuilt image on your own server and shows its environment, domain and logs in the browser. GitHub still builds the image; the panel pulls it and starts it. The panel does not create Posify's tables or call its background jobs, so this chapter covers those as well.

Read this first

Run the image, not a build of your own

Point the panel at the image the workflow pushes, ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main. A panel that builds deploy/Dockerfile from the repository stops with ERROR: no prebuilt .next/ in the build context. To build on the server instead, use Node Server.

  • Panels name their screens differently. The steps say what to set; find the matching field in your panel.
  • You run pnpm db:migrate in the container's terminal after the first deploy, and after each update that brings migrations.
  • Nothing calls the background jobs until you schedule them (step 9).

Before you start

  • The image is built: steps 1 to 4 of Docker Image (a private repository, the NEXT_PUBLIC_APP_URL variable, Chromium if you want PDFs, and a green Deploy image run).
  • A panel on your server that runs Docker images, for example Dokploy.
  • A GitHub personal access token (classic) with the read:packages scope (step 5 of Docker Image).
  • PostgreSQL 16 or newer that the app's container can reach: a database service in the same panel, or a managed database (Database Setup).
  • Your filled-in .env values (Environment Variables), and a domain you can point at the server (Domain & HTTPS).
  1. 1

    Add ghcr.io as a registry

    The image is private, so the panel logs in to the GitHub Container Registry for you.

    Registry
    ghcr.io
    User name
    Your GitHub user name.
    Password
    The token with the read:packages scope.
    When the token expires, deploys can no longer pull the image. Make a new token and update the registry's password.

    Check: The panel lists the ghcr.io registry.

  2. 2

    Create the application from the image

    Create an application whose source is a Docker image, not a Git repository or a Dockerfile.

    Image
    ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main, in lowercase, as the Packages page shows it.
    Registry
    The ghcr.io registry from step 1.
    If the panel has a field for the container's command, leave it empty. The image starts the app with pnpm start; anything typed there replaces it.

    Check: The application shows the image with the tag main.

  3. 3

    Copy the runtime variables

    Copy every runtime variable from your .env into the application's environment in the panel. The container reads its settings from there: the image holds no .env file.

    1. 1NEXT_PUBLIC_APP_URL must equal the GitHub variable. Changing it in the panel does not change the image: change the GitHub variable, run the workflow, then redeploy.
    2. 2BETTER_AUTH_URL must be the same address.
    3. 3DATABASE_URL must be reachable from inside the container, where 127.0.0.1 is the container itself. Use the address the panel gives its database service, or your managed database's connection string.
    4. 4Leave out the SMTP and storage lines you do not fill in. Posify treats any value there as a real setting, example values included.

    Check: The environment lists DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL, INSTALL_TOKEN and CRON_SECRET, with your values.

  4. 4

    Set the port and the cache volume

    The container listens on port 3000. A volume at /app/.next/cache keeps optimized images across deploys, so they are not made again after every update.

    Container port
    3000
    Volume mount path
    /app/.next/cache

    Check: The application shows port 3000 and a volume mounted at /app/.next/cache.

  5. 5

    Add your domain with HTTPS

    Point the domain at the server first (Domain & HTTPS). Then add it to the application in the panel, with HTTPS on and traffic sent to port 3000. Use exactly the address in NEXT_PUBLIC_APP_URL.

    A proxy on the same machine or a private network (nginx, Caddy, Traefik, Docker) is trusted already when Posify works out each visitor's IP address, so TRUSTED_PROXIES stays unset.

    Check: After the first deploy (next step), https://pos.example.com answers with a padlock.

  6. 6

    Deploy

    Start the first deploy. The panel pulls the image and starts the container: nothing is built on the server.

    Check: The application's log shows Ready in …, and the container keeps running.

  7. 7

    Create the tables in the container's terminal

    Open the container's terminal in the panel and run pnpm db:migrate. Until it has run, the wizard's Database connection row fails with "The database is empty: the tables are not there yet".

    bash
    cd /app
    pnpm db:migrate

    Check: The first line names the database and server it reached, and the run ends with a Done: line.

  8. 8

    Run the install wizard

    Open your address. Every page sends you to the wizard until the business is set up; First Run & Installer explains each screen.

    Check: The wizard says "Your business is ready", and you can sign in.

  9. 9

    Schedule the background jobs

    The panel calls none of Posify's eleven jobs by itself. Use the server's crontab, calling your public address, or your panel's schedules if it has them. The image has no curl, so a schedule that runs inside the container uses Node instead. Background Jobs has both.

    Check: Settings → Maintenance Mode → Background jobs shows each job as Running after its first call.

  10. 10

    Redeploy after each new image

    Every push to main builds a new image. Redeploy in the panel once the workflow's run is green, or let the workflow ask Dokploy to do it: add these three repository secrets on GitHub, under Settings → Secrets and variables → Actions → Secrets.

    DOKPLOY_URL
    Your Dokploy panel's address, for example https://panel.example.com, with no / at the end: the workflow adds /api/application.deploy to it.
    DOKPLOY_API_KEY
    An API key you create in Dokploy.
    DOKPLOY_APPLICATION_ID
    The ID of the Posify application in Dokploy.

    Check: After the next green run, its Trigger Dokploy redeploy step has run, and Dokploy shows a new deployment. Without all three secrets, that step is skipped.

  11. 11

    Run the migrations after an update

    An update that brings migrations needs pnpm db:migrate in the container's terminal, with maintenance mode on. With automatic redeploys, the new code starts as soon as its image is ready, so turn maintenance mode on before you push.

    1. 1Settings → Maintenance Mode: turn on Enable Maintenance Mode, add your own IP address under Allowlisted IP addresses, and click Save Maintenance Settings.
    2. 2Back up the database (Backups & Recovery).
    3. 3Push the release, and redeploy once the run is green (or let the workflow do it).
    4. 4In the container's terminal: cd /app && pnpm db:migrate, then touch .env && pnpm accounting:reconcile --dry-run.
    5. 5Turn maintenance mode off.

    Check: pnpm db:migrate --list ends with … applied, 0 pending., and the reconcile ends with Dry run: nothing was written.

  12. 12

    Run other commands in the terminal

    pnpm create-admin and pnpm accounting:reconcile read a .env file, which the image does not hold. Create an empty one first; the panel's environment still supplies every value. Each deploy starts a new container, so do it again after a redeploy.

    bash
    cd /app
    touch .env
    pnpm create-admin you@example.com "a-new-password"
    pnpm accounting:reconcile --dry-run
    The image has no pg_dump. Back up from the database's own container or service (Backups & Recovery).

Rolling back in a panel

Every image is also tagged with its short commit SHA. Set the application's image to ghcr.io/YOUR-ACCOUNT/YOUR-REPO:PREVIOUS-SHA and redeploy. If the new release's migrations already ran, restore the backup you took before upgrading too.

PDF exports need Chromium in the image

The shipped image has no Chromium, so the PDF buttons are off and receipt emails go out without the PDF. Add it as step 3 of Docker Image shows, push, then redeploy the new image.

Chapter 12 · Node Server

Build and run Posify with Node.js

Build Posify on your own server and run it with Node.js. systemd or pm2 keeps it running and starts it again after a reboot, and nginx or Caddy in front of it adds HTTPS. The build needs several GB of memory on the server itself; on a small server, limit it as below, or run the prebuilt Docker image instead.

Read this first

Every command runs on the server, in the app's folder

The examples use /opt/posify as the app's folder, posify as the account that runs it, and pos.example.com as the domain. Put your own in their place.

  • Run pnpm db:migrate before the first start and after every update: the app never creates or changes its tables.
  • NEXT_PUBLIC_APP_URL is built into the app. After you change it, run pnpm build again, then restart.
  • On a server with 8 GB of RAM or less, or one that runs the app while it builds, set BUILD_MAX_CPUS=2.

Before you start

  • Node.js 24.11.0 or newer on the server (.nvmrc names 26, which the Docker image uses), and pnpm through Corepack (Requirements).
  • PostgreSQL 16 or newer, with an empty database and a user that owns it (Database Setup).
  • The release unzipped into a new folder on the server, for example /opt/posify, owned by the account that will run it.
  • A filled-in .env in that folder (Environment Variables).
  • A domain pointed at the server, with ports 80 and 443 open for the reverse proxy (Domain & HTTPS).

Memory and CPU

SettingDefaultWhat it controls
BUILD_MAX_CPUSone worker per coreWorkers pnpm build starts. 2 on hosts with 8 GB or less, or when building beside the running app. The build is slower but stays within memory.
PAGE_CACHE_MEMORY_MB50Memory for pages and data the app keeps ready. They are kept in memory only, never written to disk. 0 keeps none. Read at start.
IMAGE_CACHE_DISK_MB1024Disk for optimized images in .next/cache/images. The least recently used go first.
DATABASE_POOL_MAX10Database connections per app instance. Raise it for many tills or heavy use; keep instances × pool size under PostgreSQL's max_connections (100 by default), with room for pnpm db:migrate and your own sessions.
RATE_LIMIT_STOREthe databaseWhere rate-limit counters live. Leave it unset when you run more than one instance, so every instance shares the same limits.

Set these in .env. BUILD_MAX_CPUS also works in front of the command: BUILD_MAX_CPUS=2 pnpm build.

  1. 1

    Install, migrate and build

    From the app's folder, enable Corepack, install the packages, create the tables in the database .env names, and build.

    1. 1corepack enable gives you the pnpm version package.json pins (10.24.0).
    2. 2On 8 GB of RAM or less, build with BUILD_MAX_CPUS=2 pnpm build, or put BUILD_MAX_CPUS=2 in .env.
    3. 3pnpm start runs the app in the foreground, on all addresses, port 3000. Press Ctrl+C to stop it: the service in the next step runs it for good, on 127.0.0.1 only.
    bash
    cd /opt/posify
    corepack enable
    pnpm install --frozen-lockfile
    pnpm db:migrate
    pnpm build
    pnpm start
    The build makes no database connection, so a wrong DATABASE_URL only shows once the app runs.

    Check: pnpm db:migrate names the database and server on its first line and ends with a Done: line. The build ends with check:chunks — … preloaded chunk references, all in .next.

  2. 2

    Keep it running with systemd

    systemd starts Posify when the server boots and restarts it if it stops. Create /etc/systemd/system/posify.service.

    1. 1WorkingDirectory is the app's folder. The app reads .env from there.
    2. 2ExecStart needs the full path to node: which node shows it (with nvm it is under your home folder).
    3. 3User is the account that owns /opt/posify.
    /etc/systemd/system/posify.service
    ini
    [Unit]
    Description=Posify
    After=network.target
    
    [Service]
    Type=simple
    User=posify
    WorkingDirectory=/opt/posify
    Environment=NODE_ENV=production
    ExecStart=/usr/bin/node node_modules/next/dist/bin/next start -H 127.0.0.1 -p 3000
    Restart=always
    RestartSec=5
    
    [Install]
    WantedBy=multi-user.target
    Then
    bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now posify
    journalctl -u posify -f        # the app's log
    The unit starts the app on 127.0.0.1 only, so nobody reaches it without the proxy.

    Check: systemctl status posify shows active (running), and curl -I http://127.0.0.1:3000 answers 307 with a location that ends in /install.

  3. 3

    Or keep it running with pm2

    Use pm2 instead of systemd if you prefer it. From the app's folder:

    bash
    pm2 start node_modules/next/dist/bin/next --name posify -- start -H 127.0.0.1 -p 3000
    pm2 save
    pm2 startup                    # prints the command that starts pm2 at boot
    pm2 startup only prints a command. Run that command too, or pm2 does not start after a reboot.

    Check: pm2 list shows posify as online.

  4. 4

    Put nginx or Caddy in front

    The proxy takes HTTPS from visitors and forwards to 127.0.0.1:3000. Use one of the two, with pos.example.com replaced by your domain, then reload the proxy.

    1. 1nginx: get the certificate with Certbot or your provider. On nginx older than 1.25.1, write listen 443 ssl http2; instead of the http2 on; line.
    2. 2nginx: client_max_body_size must be at least the largest file size set in Settings → Storage Settings, because uploads pass through the app.
    3. 3Caddy needs the domain to point at the server before it can get the certificate.
    nginx
    nginx
    server {
        listen 80;
        server_name pos.example.com;
        return 301 https://$host$request_uri;
    }
    
    server {
        listen 443 ssl;
        http2 on;
        server_name pos.example.com;
    
        ssl_certificate     /etc/letsencrypt/live/pos.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/pos.example.com/privkey.pem;
    
        # Uploads pass through the app: allow at least the largest file size
        # set in Settings → Storage.
        client_max_body_size 50m;
    
        location / {
            proxy_pass http://127.0.0.1:3000;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }
    Caddy (gets and renews the certificate itself)
    txt
    pos.example.com {
        reverse_proxy 127.0.0.1:3000
    }
    A proxy on the same machine needs no setting in Posify. Behind another CDN or a load balancer that forwards from a public address, set TRUSTED_PROXIES (Domain & HTTPS).

    Check: https://pos.example.com opens with a padlock and shows the install wizard.

  5. 5

    Install Chromium and fonts for PDF exports

    Posify prints PDFs with a headless Chrome or Chromium on the server: the PDF button of reports, statements, the tax report and the aging and statement screens, and the PDF copy attached to receipt emails. Without it, CSV exports still work, the PDF button says "PDF export needs Chrome or Chromium on the server. The CSV works without it.", and receipt emails go out without the PDF.

    1. 1A Linux server needs the Noto fonts too, or Bengali, Hindi, Arabic, Chinese and Japanese text prints as empty boxes.
    2. 2Posify looks at CHROME_PATH first. Otherwise, on Linux: /usr/bin/chromium, /usr/bin/chromium-browser, /usr/bin/google-chrome, /usr/bin/google-chrome-stable, /snap/bin/chromium and /usr/bin/microsoft-edge.
    3. 3macOS: Google Chrome, Chromium or Microsoft Edge in /Applications. Windows: Chrome or Chromium under Program Files or your local AppData, and Microsoft Edge under Program Files.
    4. 4Set CHROME_PATH in .env only when yours is somewhere else. At most two browsers print at once; each closes when its file is done.
    Debian / Ubuntu
    bash
    sudo apt-get install -y chromium fonts-noto-core fonts-noto-cjk
    Alpine
    bash
    apk add chromium font-noto font-noto-bengali font-noto-arabic font-noto-devanagari font-noto-cjk

    Check: Once the app runs and you are signed in: Statements → Profit and loss → PDF downloads a PDF.

  6. 6

    Run the install wizard

    Open your address and finish the wizard right away: it creates the owner account. First Run & Installer explains each screen.

    Check: The wizard says "Your business is ready", and you can sign in.

  7. 7

    Schedule the background jobs

    Add the crontab from Background Jobs to the server. It calls your public address with CRON_SECRET.

    Check: Settings → Maintenance Mode → Background jobs shows each job as Running after its first call.

  8. 8

    Update to a new release

    Follow Updates & Migrations: unzip the new release into a new folder, copy .env across, install, build, run the release's steps, and point the service at the new folder. Keep the old folder until the new one runs well.

    1. 1systemd: change WorkingDirectory in /etc/systemd/system/posify.service to the new folder, then run sudo systemctl daemon-reload and sudo systemctl restart posify.
    2. 2pm2: run pm2 delete posify, then the pm2 start command from the new folder, then pm2 save.

    Check: systemctl status posify (or pm2 list) shows the app running from the new folder.

Where to look when something goes wrong

journalctl -u posify -f follows the app's log under systemd; with pm2, pm2 logs posify. Known messages and their fixes: Troubleshooting.

More than one app instance

Many app instances, or a serverless platform, can need more connections than PostgreSQL allows. Put PgBouncer or your provider's pooler between them, and run pnpm db:migrate over a direct connection (Database Setup).

Chapter 13 · First Run & Installer

Run the install wizard (five screens)

Until the business is set up, every page sends you to the install wizard at /install. In five screens it checks the server, asks for your installation token, and takes the business details, the owner account and the storage bucket. Then it sets the business up and closes for good. It is the same on every path: the Docker image, a panel, a Node server or your own computer.

Runs only once

Run it yourself, right after the first start

Whoever finishes the wizard creates the owner account, which holds every permission. The wizard first asks for the INSTALL_TOKEN from the server's .env, so only someone who controls the server can finish it. Still, open it as soon as the app is online.

  • When it is done, /install answers "not found" for good. That is the lock, not a fault.
  • pnpm create-admin and pnpm db:seed also mark the business installed and close the wizard. Use the wizard or a command, not both.
  • Locked out later? Backups & Recovery shows how to get back in.

Before you start

  • The app is running, and pnpm db:migrate has run on its database: the wizard's database check reads Posify's tables.
  • In .env (or the panel's environment): DATABASE_URL, BETTER_AUTH_SECRET and INSTALL_TOKEN (each of the two at least 32 random characters), and NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL set to the address you will open (Environment Variables).
  • Optional: your storage bucket and its keys (Storage & Media). You can add storage after installing.

Where to fix a failed check

How you run PosifyWhere the value isAfter you change it
Node server, systemd.env in the app's folder.sudo systemctl restart posify. After a change to NEXT_PUBLIC_APP_URL, run pnpm build first.
Node server, pm2.env in the app's folder.pm2 restart posify. After a change to NEXT_PUBLIC_APP_URL, run pnpm build first.
Docker imageThe env file, for example /opt/posify/.env.docker rm -f posify, then the docker run command again. For NEXT_PUBLIC_APP_URL, change the GitHub variable, run the workflow and run the new image (Docker Image).
Deploy panelThe application's environment in the panel.Redeploy. For NEXT_PUBLIC_APP_URL, change the GitHub variable, run the workflow, then redeploy.
Your own computer.env in the app's folder.Stop the app with Ctrl+C and start it again. With pnpm start, run pnpm build first after a change to NEXT_PUBLIC_APP_URL (Running the App).

Then press Check again in the wizard (it shows while a check that blocks the install fails), or reload the page.

What Install creates

ItemWhat you get
The businessIts settings: the name, email, default language, currency, time zone and whether prices include tax, and the storage bucket if you entered one.
The owner accountYour account, on the Administrator role and marked as the owner: every permission, and nobody else can remove or suspend it.
RolesThe preset roles: Administrator, Manager, Cashier, Accountant, Stock Keeper, Purchaser, Supervisor, Read-only and External Accountant.
Main BranchOne branch, code MAIN, that sells at the counter, holds stock and accepts returns.
Counter 1One register at Main Branch, code R1.
UnitsPiece, Box, Pack, Dozen, Kilogram, Gram, Litre, Millilitre and Metre.
Chart of accountsThe system accounts the journals post to, and the first expense categories.
Sample dataOnly with Add sample data: a sample catalogue, suppliers and customers. No stock, no sales, no tax settings and no sign-ins.

You can rename and add branches and registers in Settings → Branches and Settings → Registers after you sign in.

  1. 1

    Open your address

    Open the address in NEXT_PUBLIC_APP_URL. Until the business is set up, every page sends you to /install.

    An error page instead of the wizard? Pages do not send you to the wizard while the database cannot be reached. Open /install yourself: its Database connection row names the cause.

    Check: The page is titled Set up your business, and shows System check after "Checking your environment…".

  2. 2

    Pass the system check

    The first screen checks five things. Node.js, Database connection, Authentication secret and Installation token must pass before you can go on. Application URL only warns, but sign-in fails until it passes. A green tick means the row passed; an amber triangle means it needs a fix.

    1. 1Node.js (the row shows your version): 24.11 or newer, or the row says "Node.js 24.11 or newer is required".
    2. 2Database connection: it must reach PostgreSQL and read Posify's tables. A row that fails names the cause: DATABASE_URL not set, a server that did not answer, a refused user or password, a database that does not exist, no tables yet (run pnpm db:migrate), or a user that may not read them.
    3. 3When the database cannot be reached at all, the other rows say "Not checked — the installer could not reach its database".
    4. 4Authentication secret: BETTER_AUTH_SECRET must be set, at least 32 characters long, and not an example value.
    5. 5Installation token: INSTALL_TOKEN must be set and at least 32 characters long, or the row says, for example, "INSTALL_TOKEN is 20 characters. Use at least 32, then restart the app."
    6. 6Application URL: NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL must both be the address in your browser. A warning names the variable and both addresses, for example "NEXT_PUBLIC_APP_URL is http://localhost:3000, but this installer is open on https://pos.example.com, so signing in here would fail. Make them match, then rebuild and restart."
    7. 7Fix a value as the table "Where to fix a failed check" shows, then press Check again.
    Make random values
    bash
    openssl rand -base64 48   # BETTER_AUTH_SECRET
    openssl rand -hex 32      # INSTALL_TOKEN, CRON_SECRET
    No openssl (for example on Windows)
    bash
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    The banner says "restart the app after editing .env". With the Docker image that means a new container (docker rm -f and docker run); in a panel, a redeploy.

    Check: All five rows show a green tick, and the Installation token box appears under them.

  3. 3

    Enter the installation token

    One box appears under the rows once nothing blocks the install. Continue stays greyed out until it is filled in.

    1. 1Press Continue. The wizard checks the token now, so a mistyped one is said at once, not after the last screen.
    Installation token
    The INSTALL_TOKEN value from the server's .env, exactly as it is there. It shows the business is being set up by whoever owns the server.
    "That installation token does not match INSTALL_TOKEN in the server's .env file." means the value differs from the one the app runs with: copy it again from the same place.

    Check: Continue opens About your business.

  4. 4

    About your business

    These settings shape receipts, reports and the till. You can change them later in Settings → General Settings, with two limits: the currency is fixed once the first sale is posted, and the time zone once a month's books are closed.

    Business name
    Required.
    Business email
    Printed on receipts and used as the sender of your emails. Leave it blank to use the owner's address.
    Default language
    The language Posify opens in, one of 18. Search by the language's own name or its English name.
    Currency
    USD until you pick another. Search the list, and choose with care: every price, sale and report is in this currency.
    Time zone
    Your browser's zone at first. Reports, receipts and the register's day roll over in this zone.
    Prices include tax
    Off by default. On: the price you type on a product is what the customer pays. Off: tax is added at the POS.
    A new business charges no tax until you add rates and groups under Settings → Tax (Tax), whichever way you set Prices include tax.

    Check: Continue becomes clickable once Business name is filled in (and Business email, if you typed one, looks like an email address).

  5. 5

    Create the owner account

    The owner holds every permission and cannot be removed or suspended by anyone else. Staff accounts are added later, under Staff (Staff & Roles).

    Your name
    Your full name.
    Email
    An address you read. Password resets go there once email is set up.
    Password
    At least 8 characters. Not a common password, not your name, email or the business name, and not a simple pattern like 12345678. The list under the box ticks each rule off.
    The published demo passwords are refused: "That is one of the published demo passwords. Choose your own."

    Check: Continue becomes clickable once every rule under Password is ticked.

  6. 6

    Connect your storage bucket, or skip it

    The screen Where media is stored connects the bucket for product images, your logo and documents. Storage & Media shows where to find each value.

    1. 1Under Storage provider, pick Cloudflare R2 (selected first), AWS S3, MinIO or DigitalOcean Spaces. The form shows that provider's fields.
    2. 2Fill them in and press Test connection. It uploads a small file and reads it back through the Public URL.
    3. 3No bucket yet? Tick Set storage up later. The install finishes, but uploads stay unavailable until you add the bucket under Settings → Storage Settings.
    4. 4Storage keys already in .env? The screen says "Storage credentials were found in your .env file" and ticks Set storage up later for you. Leave it, or fill the form in: values entered here are kept in the database and take priority.
    Account ID
    Cloudflare R2 only: your Cloudflare account ID.
    Region
    AWS S3, for example us-east-1. Optional for MinIO.
    Datacenter region
    DigitalOcean Spaces, for example nyc3.
    Endpoint URL
    MinIO only, for example https://minio.example.com.
    Bucket name
    Every provider.
    Access key ID
    Every provider.
    Secret access key
    Every provider.
    Public URL
    The address the files are served from, for example https://cdn.example.com. Optional here, but without it browsers cannot show the files.
    "API credentials are correct, but no Public URL is set" means the keys work but browsers cannot read the files. Make the bucket publicly readable, put its address in Public URL and test again.

    Check: Next to Test connection you see "Cloudflare R2 connected and public URL verified" (with your provider's name).

  7. 7

    Check the summary and install

    Ready to install shows the business name, the owner's email, the currency and the time zone. Press Back to change any of them.

    1. 1Add sample data is ticked by default: a sample catalogue, suppliers and customers to try the till with. It adds no stock, no sales, no tax settings and no sign-ins, and the sample customers have no phone numbers. Untick it to start empty.
    2. 2Press Install and wait. Do not close the page.
    A red message, such as "Installation failed — please try again", means the install did not finish and the wizard stays open. Press Back to the screen it points to, fix it, and press Install again.

    Check: "Your business is ready" appears, with Go to sign in.

  8. 8

    Read any warnings, then sign in

    Lines with an amber triangle under the result did not stop the install. Do what they say after you sign in.

    1. 1"The default branch, register and units could not be created — add them under Settings after signing in."
    2. 2"The sample data could not be created — you can add products from Products after signing in."
    3. 3"Your business is installed, but setup is not finished": sign in, open Settings → General Settings, check the business name, language and currency, then click Save.
    4. 4Press Go to sign in. The sign-in page opens in the language you chose; sign in with the owner's email and password.
    After your first dashboard visit, the bell shows "Background jobs have stopped". On a new business this is expected: nothing has called the jobs yet. Background Jobs sets them up.

    Check: You reach the dashboard, and /install now answers "not found".

  9. 9

    Set up the rest

    Nothing else is mandatory, but most businesses do these next.

    1. 1Background jobs: Background Jobs. Emails and texts that fail their first try are only retried by them.
    2. 2Email: Settings → Email, or the SMTP_* variables (Email / SMTP).
    3. 3Text messages (optional): Settings → SMS (Twilio). Texts go out only after SMS is switched on and one test message has been sent (Text Messages).
    4. 4Tax: rates and groups under Settings → Tax (Tax).
    5. 5Opening balances, if you move from another system (Accounting).
    6. 6Storage, if you skipped it: Settings → Storage Settings (Storage & Media).
    7. 7Scanners, printers and the cash drawer (Hardware).
    8. 8Then work through the Go-Live Checklist.
  10. 10

    Locked out, or /install answers not found

    /install answers "not found" once the business is installed: sign in at /login instead. Lost the owner's password? Use Forgot password? on the sign-in page (it needs email), or restore the account from the command line with pnpm create-admin, as Backups & Recovery shows.

    bash
    pnpm create-admin you@example.com "a-new-password"
    Only on a test database you can throw away: pnpm db:reset empties it, and after a restart the wizard opens again (Database Setup). Never on a live business.

    Check: The command prints ✓ Password set; every open session was ended., and you can sign in with the new password.

Chapter 14 · Go-Live Checklist

Before the first real sale

The wizard is done and you can sign in. Work through these lists once before the business starts trading on Posify. Each row says where to look and what you should see when it is done, and most rows link to the chapter with the details.

Before you start

  • The install wizard has finished and you signed in as the owner (First Run & Installer).
  • Your final https address, written here as https://pos.example.com.
  • Access to the server or the panel, for the rows about .env and the scheduler.

The server and its address

CheckWhereDone when
HTTPS addressDomain & HTTPShttps://pos.example.com opens with a padlock, and port 3000 is reachable only through the proxy.
App addressNEXT_PUBLIC_APP_URL and BETTER_AUTH_URL, rebuilt after the last changeBoth are the https address. Signing in at https://pos.example.com/login works, and Settings → Maintenance Mode → Background jobs shows lines with your address, not localhost.
SecretsBETTER_AUTH_SECRET and CRON_SECRETYour own random values: 32+ characters for the first, 16+ for the second. No placeholder left.
Owner fallback passwordADMIN_PASSWORD in .envChanged or deleted. .env.example ships change-me, which pnpm create-admin uses when you type no password.
Demo mode offDEMO_MODE and NEXT_PUBLIC_DEMO_MODEBoth unset (or false), rebuilt if NEXT_PUBLIC_DEMO_MODE was set. No Demo mode strip above the pages, and no Demo accounts box on the sign-in page (Security).
No demo sign-insThe databaseIt was set up by the wizard, not pnpm db:seed: signing in as owner@example.com with Owner@123 fails.
Maintenance mode offSettings → Maintenance ModeEnable Maintenance Mode is off, and saved.
ProxiesTRUSTED_PROXIESUnset, unless another CDN or a load balancer forwards from a public address (Domain & HTTPS).

Jobs, backups and the books

CheckWhereDone when
Background jobsThe server's crontab or your scheduler (Background Jobs)Settings → Maintenance Mode → Background jobs shows every job as Running; the daily ones after their first night.
BackupsA nightly pg_dump, copied off the server (Backups & Recovery)A backup restored into a test database opens with your data.
Books checkpnpm accounting:reconcile --dry-runIt exits with code 0.
PDF exportsChromium and the Noto fonts on the server (Node Server)Statements → Profit and loss → PDF downloads a PDF.

Messages and files

CheckWhereDone when
EmailSettings → Email (Email / SMTP)Send test email reaches your inbox. Password resets, receipts and notifications need it.
Text messagesSettings → SMS (Twilio), optional (Text Messages)SMS is switched on and one test text has been sent: texts go out only after that.
StorageSettings → Storage Settings (Storage & Media)Test connection reports "… connected and public URL verified", and a product image you upload shows.
Who hears of whatSettings → Notifications (Notifications)Daily digests from and Registers closed by match your trading hours.

The business

CheckWhereDone when
Business detailsSettings → General SettingsName, currency and time zone are right. The currency can no longer change once the first sale is posted, and reports, receipts and the register's day follow the time zone.
TaxSettings → Tax (Tax)Your rates and groups exist: a new business charges no tax until you add them.
Branches and registersSettings → Branches and Settings → RegistersMain Branch and Counter 1 carry your names, and each till device has its own register.
PaymentsSettings → PaymentsOnly the tenders you take are switched on.
ReceiptSettings → Receipt (Hardware)Paper width (58 mm or 80 mm), logo, header and footer are as you want them.
Opening figuresAccounting and Inventory → Opening stock (Inventory)If you move from another system: opening balances, customers' and suppliers' opening dues and the stock you hold are in.
Sample dataProducts, Customers and SuppliersIf you installed with Add sample data: the sample records you will not use are archived or deleted.
StaffStaff and Roles (Staff & Roles)Everyone has their own account and role. Nobody else uses the owner's sign-in.
Two-step sign-inYour profile, and Settings → Security & Access Control (Security)On for the owner at least.

The counter

CheckWhereDone when
ScannerHardwareA scan on the till screen adds the product: the scanner sends Enter after each code.
Receipt printerSettings → Receipt and Settings → RegistersReceipts print on the receipt printer, sized to the paper width.
Cash drawerSettings → Point of sale → Open the cash drawer, the register's Cash drawer switch, and QZ TrayTest in the till's Set up drawer printer opens the drawer.
Offline readinessEach till device (Offline Selling)The till was opened online once on that device, on the https address. Devices that scan with the camera opened the camera once while online.

Never seed or reset the live database

pnpm db:seed writes demo sign-ins whose passwords are published, and pnpm db:reset deletes every sale, product, customer and journal without asking. On a live business, run neither.

Prefer to have it done for you?

Paid installation help is available: book it here.

Chapter 15 · Background Jobs

Keep the eleven background jobs running

Posify does part of its work in eleven background jobs: it retries email and text messages, sends marketing campaigns, sends digests and reminders, expires store credit, records repeating expenses, cleans up, and checks the books every night. A job runs when a scheduler calls its URL with your CRON_SECRET, and nothing calls them until you set one up. If they stop, the till keeps selling, but this work waits until the scheduler calls again.

Before you start

  • The install wizard has finished (First Run & Installer).
  • Your CRON_SECRET value from .env: at least 16 random characters. openssl rand -hex 32 makes a good one.
  • Your public address, for example https://pos.example.com.

The eleven jobs

Job (/api/cron/…)ScheduleWhat it does
email-deliveries*/5 * * * *: every 5 minutesRetries queued email and text messages.
store-credit*/15 * * * *: every 15 minutesExpires store credit past its date and gives back abandoned till holds.
recurring-expenses10 * * * *: hourly, at :10Records the copies repeating expenses owe, each on the day it fell due.
notification-digests5 * * * *: hourly, at :05Sends the day's digests (low stock, late orders, bills due, customers' dues, expiring store credit).
register-watch20 * * * *: hourly, at :20Reports registers still open past Settings → Notifications "Registers closed by".
housekeeping40 3 * * *: daily, 03:40Deletes old delivery logs, spent request keys, expired rate-limit counters and old notifications. Never a business document.
accounting-reconcile15 2 * * *: daily, 02:15Posts any journal a document is missing, rebuilds the balance caches, and tells the accountants when the books need a look.
accounting-recoveries*/15 * * * *: every 15 minutesPosts the journals that failed to post as soon as each is due to be tried again (Books check → Postings waiting).
gift-card-expiry0 4 * * *: daily, 04:00Reminds holders of gift cards that expire soon, and, when Settings → Gift cards books breakage, takes what expired cards still hold into income.
staff-access25 * * * *: hourly, at :25Warns the people who manage a staff member a few days before their access end date, and logs the end and signs them out once it passes.
marketing-send* * * * *: every minuteStarts the campaigns whose time has come and sends the next batch of each (100 a channel), outside the quiet hours and within the daily SMS limit of Settings → Marketing. Sends nothing on a demo.

Each job is GET https://YOUR-DOMAIN/api/cron/<job> with the header Authorization: Bearer <CRON_SECRET>. Calling a job twice is harmless.

When a job counts as stopped

ScheduleJobsNot running after
Every minutemarketing-send30 minutes without a run
Every 5 minutesemail-deliveries30 minutes without a run
Every 15 minutesstore-credit, accounting-recoveries2 hours
Hourlynotification-digests, recurring-expenses, register-watch, staff-access6 hours
Dailyaccounting-reconcile, housekeeping, gift-card-expiry36 hours

A job that has never run counts as not running too. A job counts as failing after three failed runs in a row. A call refused with 401 is not a run.

  1. 1

    Set CRON_SECRET where the app runs

    The scheduler sends Authorization: Bearer <CRON_SECRET>, and the app refuses every call without the right value. Set it on the app first, then use the same value in the scheduler.

    1. 1Node server: put CRON_SECRET=… in .env, then restart the app.
    2. 2Docker image: put it in the env file, then run docker rm -f posify and the docker run command again.
    3. 3Deploy panel: add it to the application's environment and redeploy.
    bash
    openssl rand -hex 32
    No openssl (for example on Windows)
    bash
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    The app refuses a missing value, the .env.example placeholder replace-with-a-long-random-secret, and anything shorter than 16 characters. Every job then answers 401, and the log says why once, for example [cron] CRON_SECRET is still the placeholder from .env.example; scheduled jobs are refused until it is set to a long random value.
  2. 2

    On a Linux server: add the crontab

    Add the eleven lines to the crontab of the account that runs Posify. Any server that can reach your address works. With the Docker image, use the host's crontab, calling your public address.

    1. 1Run crontab -e.
    2. 2Paste the block. Put your value after CRON_SECRET= and your domain in place of YOUR-DOMAIN, then save.
    3. 3Or copy the lines from Settings → Maintenance Mode → Background jobs, under For your scheduler: they carry your address already, and Copy adds a CRON_SECRET= line for your value.
    4. 4Run crontab -l to see what was saved.
    crontab -e
    bash
    CRON_SECRET=paste-the-value-from-your-.env
    */5 * * * *   curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/email-deliveries > /dev/null
    */15 * * * *  curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/store-credit > /dev/null
    10 * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/recurring-expenses > /dev/null
    5 * * * *     curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/notification-digests > /dev/null
    20 * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/register-watch > /dev/null
    40 3 * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/housekeeping > /dev/null
    15 2 * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/accounting-reconcile > /dev/null
    */15 * * * *  curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/accounting-recoveries > /dev/null
    0 4 * * *     curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/gift-card-expiry > /dev/null
    25 * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/staff-access > /dev/null
    * * * * *     curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/marketing-send > /dev/null
    Crontab treats % as a special character. A hex secret (openssl rand -hex 32) has none.

    Check: crontab -l lists the CRON_SECRET= line and eleven job lines.

  3. 3

    In a deploy panel: add schedules

    Use the server's crontab as above, calling your public address, or your panel's schedules if it has them. A schedule that runs inside Posify's container cannot use curl: the image, built on node:24-bookworm-slim, has none. Use Node there instead, with one schedule per line below.

    1. 1For each schedule, use the cron expression in the comment and the node -e … line under it as the command. Copy only that one line.
    2. 2The command calls the app inside the container (http://127.0.0.1:3000) with the CRON_SECRET from the container's environment, prints each job with its status, and fails when a call does not succeed.
    One command per schedule
    bash
    # * * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" marketing-send
    
    # */5 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" email-deliveries
    
    # */15 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" store-credit accounting-recoveries
    
    # 5 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" notification-digests
    
    # 10 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" recurring-expenses
    
    # 20 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" register-watch
    
    # 25 * * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" staff-access
    
    # 15 2 * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" accounting-reconcile
    
    # 40 3 * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" housekeeping
    
    # 0 4 * * *
    node -e "Promise.all(process.argv.slice(1).map(j=>fetch('http://127.0.0.1:3000/api/cron/'+j,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(j,r.status);if(!r.ok)process.exitCode=1})))" gift-card-expiry

    Check: A schedule's run log shows each job with 200, for example store-credit 200.

  4. 4

    On Windows: Task Scheduler

    Create one Task Scheduler task per job that runs curl.exe with the same arguments as its crontab line. Windows 10 and 11 include curl.exe.

    Program/script
    curl.exe
    Add arguments
    -fsS -H "Authorization: Bearer YOUR-CRON-SECRET" https://YOUR-DOMAIN/api/cron/email-deliveries, with the job's own name at the end.
    Trigger
    The job's schedule. Every minute, 5 minutes or 15 minutes: daily, repeating the task every 1, 5 or 15 minutes for a duration of Indefinitely. Hourly at :05: daily at 00:05, repeating every 1 hour. Daily jobs: daily at the job's time.
    Security options
    Run whether user is logged on or not, so the task runs with nobody signed in.

    Check: Each task's Last Run Result reads The operation completed successfully. (0x0).

  5. 5

    Test one job by hand

    Call one job yourself to prove the secret and the address. housekeeping is safe at any time: it deletes only old logs, spent keys and old notifications, never a business document. Set CRON_SECRET in that terminal first, as the first line of each block does.

    macOS and Linux
    bash
    CRON_SECRET=paste-the-value-from-your-.env
    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/housekeeping
    Windows PowerShell
    powershell
    $env:CRON_SECRET = "paste-the-value-from-your-.env"
    Invoke-RestMethod -Uri https://YOUR-DOMAIN/api/cron/housekeeping -Headers @{ Authorization = "Bearer $env:CRON_SECRET" }
    A missing or wrong secret answers 401: curl says The requested URL returned error: 401, and PowerShell shows a red error. A refused call is not recorded, so the job keeps looking as if it never ran.

    Check: A right secret answers {"success":true,…}. PowerShell prints success as True.

  6. 6

    Read the jobs' health

    Settings → Maintenance Mode → Background jobs lists each job with what it does, its schedule and URL, when it last ran, and its state: Running, Not running or Failing. A failing job shows its last error under it. The refresh button reads them again.

    1. 1After you set the scheduler up, the frequent jobs turn Running within minutes, the hourly ones within the hour, and the daily ones after their first night.
    2. 2Opening the dashboard checks the jobs. When some have stopped, the bell tells everyone who may manage maintenance: "Background jobs have stopped", with the jobs by name. A new notice comes when that list changes.
    3. 3Accounting → Books check shows the same jobs in a box titled Background jobs need attention (Background jobs are not scheduled yet, when none has run).

    Check: Every job shows Running.

Campaigns need the every-minute job

marketing-send is called every minute so that Send now and a campaign's scheduled time are kept. A run with nothing to send reads a little and returns. Without it, a scheduled campaign never starts and a large one stops after its first batch; receipts, reminders and the automatic messages (birthday wishes and the rest) do not depend on it. A scheduler whose shortest interval is 5 or 15 minutes works too: campaigns then start that much later.

Times follow the server's clock

Crontab runs on the server's clock (timedatectl shows its time zone on Linux), so the daily jobs run at 02:15, 03:40 and 04:00 server time. The digests and reminders are called every hour on purpose: they go out once the business's own clock, the time zone in Settings → General Settings, reaches Settings → Notifications "Daily digests from", whatever zone the server keeps.

Maintenance mode does not stop the jobs

The job calls are read requests, which maintenance mode lets through. Queued email and the nightly books check carry on while you upgrade.

Keep CRON_SECRET private

Anyone who has it can start the jobs whenever they like. Keep it out of screenshots, tickets and repositories. To change it, set the new value on the app and in every scheduler at the same time.

Chapter 16 · Domain & HTTPS

Put Posify on your domain with HTTPS

Posify runs behind a reverse proxy that takes HTTPS from visitors and forwards to the app on port 3000. You point a domain at the server, let the proxy get a certificate, and set the app's two address variables to that domain. Do it before the install wizard: sign-in and the links in emails both follow this address.

Before you start

  1. 1

    Choose the final address

    Pick one address, such as pos.example.com, and use exactly that one everywhere: in NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL, in the GitHub variable if you run the image, and in your scheduler's lines.

    Choose it before you run the install wizard, so you install on the address you will keep.
  2. 2

    Point the domain at the server

    At your DNS provider, add an A record for the name (for example pos) with your server's IP address. Remove any other A, AAAA or CNAME record with the same name.

    Check: nslookup pos.example.com shows your server's IP address.

  3. 3

    Let the reverse proxy get the certificate

    Caddy gets and renews the certificate by itself once the domain points at the server. With nginx, get it with Certbot or your provider. In a deploy panel, add the domain to the application with HTTPS on (Dokploy & Panels).

    1. 1The full nginx configuration, and the Caddy one, are in Node Server, step "Put nginx or Caddy in front". They work the same in front of the Docker image's 127.0.0.1:3000.
    Caddyfile
    txt
    pos.example.com {
        reverse_proxy 127.0.0.1:3000
    }

    Check: https://pos.example.com opens with a padlock.

  4. 4

    Set the two address variables

    NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL must both be the https address, for example https://pos.example.com. Sign-in trusts these addresses, and links in emails are built from them. The install wizard warns when either differs from the address you opened it on.

    1. 1NEXT_PUBLIC_APP_URL is written into the app when it is built. Changing it in .env changes nothing until you build again.
    2. 2Node server: edit .env, run pnpm build, then restart.
    3. 3Prebuilt image: change the GitHub variable, run the workflow and deploy the new image. Keep the env file's value equal to it.
    4. 4BETTER_AUTH_URL is read when the app starts, so a restart is enough for it (with the image, a new container).

    Check: The wizard's Application URL row shows a green tick. Once installed, signing in at https://pos.example.com/login works.

  5. 5

    Open the tills on the https address

    Browsers allow the offline till only on an https:// address, or on localhost on the same machine. A till opened on a plain http:// network address, such as http://192.168.1.5:3000, cannot sell offline, and the camera scanner does not work there either.

    1. 1Signing in does work on a private network address the page is open on, which helps when you test from a second device. Still use the https address on every till.
    2. 2Open the till online once on each device, so it can work offline later (Offline Selling).

    Check: Every till device opens the POS from https://pos.example.com.

  6. 6

    Behind Cloudflare

    Cloudflare needs nothing in Posify: it reads the visitor's address from the header Cloudflare writes. Keep the DNS record on DNS only (grey cloud) until the server has its certificate. Then you may switch it to Proxied, with the SSL/TLS encryption mode Full (strict).

    Never use Flexible. Cloudflare would then call your server over plain http, the proxy redirects every http request to https, and the browser ends with too many redirects.
  7. 7

    Behind another CDN or a load balancer

    Posify finds each visitor's IP address from the proxy's X-Forwarded-For header. Rate limits, the sign-in lockout and the maintenance allow-list depend on it. A proxy on the same machine or a private network (nginx, Caddy, Traefik, Docker) is trusted already. Set TRUSTED_PROXIES only when another CDN or a load balancer forwards from a public address.

    1. 1Comma-separated IP addresses and CIDR ranges. The word cloudflare stands for Cloudflare's ranges.
    2. 2Without it, every visitor arrives as one of the CDN's addresses and shares its limits with everyone else there.
    .env
    bash
    TRUSTED_PROXIES=203.0.113.0/24
  8. 8

    Changing the domain later

    Do the steps above again for the new address, then update everything that still names the old one.

    1. 1The DNS record, and the proxy's site or the panel's domain.
    2. 2NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL, then rebuild (step 4).
    3. 3Every scheduler line (Background Jobs). Settings → Maintenance Mode → Background jobs shows the new lines once the app runs with the new address.

Keep port 3000 private

The app's own port must be reachable only through the proxy. The systemd unit and the pm2 command start it on 127.0.0.1, and the Docker command publishes it as 127.0.0.1:3000:3000. A visitor who reaches port 3000 directly can make up the address the rate limits see.

Still no certificate?

Check that the A record points at this server, that no old AAAA record points elsewhere, that port 80 is open (the certificate check uses it), and that the Cloudflare proxy is not on yet.

Chapter 17 · Settings Reference

Every settings page at a glance

Settings holds the choices that apply to the whole business. Open it with the gear in the header, or with Settings in the account menu at the foot of the sidebar. The sidebar then shows the settings menu in six groups, with Search settings and Back to Dashboard at the top. The tables below follow that menu: what each page holds, the permission that opens it, and the chapter that explains it.

Who can open Settings

Each page has its own permission

Settings opens for anyone whose role holds at least one permission of the Settings group in Administration → Roles. Each page then asks for its own permission, and the menu leaves out the pages a person cannot open. The owner opens every page, whatever their role.

  • Administrator: every page.
  • Manager: General Settings, Branding, Tax, Registers and Point of sale.
  • Accountant and External Accountant: Accounting.
  • Cashier, Supervisor, Stock Keeper, Purchaser and Read-only: no Settings at all.
  • An account limited to some branches can read the business's settings but not change them, because they apply at every branch: the page shows Settings for every branch, and the server refuses the save. Branches and Registers are the exception, since they belong to each branch. There such an account works on its own branches, while adding, deleting or re-defaulting a branch needs someone who works at every branch. The Media Library tab of Storage Settings also stays open.

Business

PageWhat it holdsPermissionExplained in
General SettingsStore Name and Store Email (both required), Phone Number, Store Description and Address; Default Language, Store Currency and Time zone; when the financial year starts; Prices include tax; Supported languages. The currency locks once the books hold journals in it, and the time zone once a month is closed.General and brandingBranding & Appearance, Languages & RTL, Tax
BrandingLight Theme Logo, Dark Theme Logo and Favicon; Primary, Secondary and Accent colours; Chart colours; the default light or dark mode.General and brandingBranding & Appearance
TaxYour tax registration; Tax defaults (Prices include tax, Rounding, Default tax group, exemption reasons, who may sell tax-free); Tax rates; Tax groups; Branch tax overrides.TaxTax
InventoryStock below zero in the back office (Allow or Refuse), Low stock at, and whether stock adjustments and stock counts wait for another person's approval.InventoryInventory
AccountingThe accounts that each branch's cash, the default bank, card payments, bank transfers and Other payments post to. Anything unset uses the system's cash and bank accounts.AccountingAccounting

Permission is the name in the Settings group of Administration → Roles. General and branding opens two pages, General Settings and Branding, and Receipt opens both Receipt and Invoice templates.

Branches & registers

PageWhat it holdsPermissionExplained in
BranchesThe shops, kiosks and warehouses: name, code, address and contacts; whether a branch sells at the counter, keeps stock and takes returns; its receipt header and footer, default tax group and tax registration number; which branch is the default.BranchesPoint of Sale
RegistersThe POS terminals of each branch: name, code, receipt prefix, receipt printer, cash drawer, and whether each one is active.RegistersPoint of Sale, Hardware

Selling

PageWhat it holdsPermissionExplained in
Point of saleHow every POS behaves: an open drawer to sell, printing a receipt and opening the drawer after a sale, the largest discount, selling past zero stock, the idle lock and the offline selling window, sending receipts by email or text, quick keys, sounds, notes and coins, blind close and floats, and the salesperson on each sale.Point of salePoint of Sale, Offline Selling
PaymentsThe ways a POS takes money (Cash, Card, Bank transfer, Other, Store credit, Loyalty points, Gift card, On account), cash rounding, deposits, and how long store credit from returns lasts.Payment methodsPoint of Sale
ReceiptWhat every POS prints and sends: paper width (58 or 80 mm), the logo, header and footer, the tax lines and tax numbers, and the loyalty balance.ReceiptPoint of Sale, Tax
Invoice templatesThe designs of the receipt and the A4 sale invoice.ReceiptInvoice Templates
LoyaltyHow customers earn points, what a point pays at the POS, and the tiers they climb.LoyaltyLoyalty & Gift Cards
Gift cardsWhether the POS sells and takes gift cards, what their codes look like, PINs, the smallest and largest amounts, expiry and reminders, and booking expired cards as income.Gift cardsLoyalty & Gift Cards
NumberingThe prefix and digits of each kind of document, from sales and returns to journals and gift cards, and whether numbers carry the branch's code. A new prefix counts on from the highest number already using it, and a register's own receipt prefix replaces the sale prefix there.Document numberingThis table; register prefixes in Point of Sale

Communication

PageWhat it holdsPermissionExplained in
EmailThe switch that turns email on, the mail server and its setup guide, the sender, Send test email, and the Delivery log (/settings/email/deliveries).EmailEmail / SMTP
SMS (Twilio)The SMS switch, Twilio or another provider over HTTP, the sender, the test text that SMS needs, numbers without a country code, codes by text per day, and the Delivery log (/settings/sms/deliveries).Text messagesText Messages
NotificationsWhich events reach the team in the bell, by email and by text; what customers are sent about their own account; when the daily digests and checks run.NotificationsNotifications
MarketingThe limits every offer obeys: quiet hours, how many offers one customer may get in how many days, offer texts a day, the line under an offer text, how long message history is kept, and the days after a message in which a sale counts as "came back". Also the switch that turns Coupons on (off for a new business).Marketing: manageText Messages, Background Jobs, User Manual

Security

PageWhat it holdsPermissionExplained in
Security & Access ControlSession length, the sign-in lockout and Unlock an account, rate limits, Offer two-factor sign-in, password rules, and password reset by text message.Security and sign-inSecurity

Advanced

PageWhat it holdsPermissionExplained in
Storage SettingsThe storage provider and its keys, the private bucket, Test Connection, the upload limits and the path prefix. Its Media Library tab lists, uploads and deletes stored files.StorageStorage & Media
Maintenance ModeThe maintenance switch, headline, message, background image, countdown and allowed IP addresses. Below them, Background jobs shows when each job last ran and the lines for your scheduler.Maintenance modeSecurity, Background Jobs

Each page saves on its own

The button at the foot of a page saves that page only: Save Changes, Save branding, Save tax settings, Save Storage Settings and so on. Tax rates, tax groups and branch tax overrides save from their own dialogs straight away.

Unsaved and Needs attention

The menu marks a page with edits not yet saved as Unsaved, and leaving it asks first (Stay or Discard). Needs attention marks Email or SMS (Twilio) switched on without a working login or sender, Storage Settings without a complete bucket, and Maintenance Mode while it is on.

Changed by someone else

If another person saved the same settings while you were editing them, your save stops at Settings changed elsewhere. Choose Reload to see their change, or Save anyway to overwrite it.

Search settings

The box at the top of the settings menu filters the pages by name.

Values from .env

An email, SMS or storage field filled from .env says Set via environment variable. A value saved here overrides it. A saved password, token or secret key never comes back to the browser: the field shows only a masked hint.

Demo mode

With DEMO_MODE on, every settings form is read-only under a Demo mode banner. The Media Library and the Invoice templates gallery still open. See Security.

Settings addresses (put the language code in front for a language that is not the default, e.g. /bn/settings/tax)
txt
/settings                      opens General Settings
/settings/general              General Settings
/settings/appearance           Branding
/settings/tax                  Tax
/settings/inventory            Inventory
/settings/accounting           Accounting
/settings/branches             Branches
/settings/registers            Registers
/settings/pos                  Point of sale
/settings/tenders              Payments
/settings/receipt              Receipt
/settings/invoices             Invoice templates
/settings/loyalty              Loyalty
/settings/gift-cards           Gift cards
/settings/numbering            Numbering
/settings/email                Email
/settings/email/deliveries     Email delivery log
/settings/sms                  SMS (Twilio)
/settings/sms/deliveries       SMS delivery log
/settings/notifications        Notifications
/settings/marketing            Marketing
/settings/security             Security & Access Control
/settings/storage              Storage Settings, with its Media Library tab
/settings/maintenance          Maintenance Mode, with Background jobs

Settings or .env

Almost everything is set here, after installing. .env keeps what Posify needs before it can read its settings: the database, BETTER_AUTH_SECRET, the app's address, INSTALL_TOKEN and CRON_SECRET. Email, SMS and storage can come from either place, and each of their chapters says which one wins.

Right after installing

Schedule the background jobs, connect storage if you skipped it in the wizard, set up email, add your tax rates (a new business charges none), check Point of sale and Payments, then add your staff.

Chapter 18 · Storage & Media

Connect a bucket for images and files

Posify keeps product images, logos, profile photos and documents in an S3-compatible bucket that you own: Cloudflare R2, AWS S3, DigitalOcean Spaces, or a MinIO server you run yourself. There is no local-disk option, so nothing can be uploaded until a bucket is connected. Connect it in the install wizard, in Settings → Storage Settings, or with the STORAGE_* variables.

Read this first

Settings win, field by field

Each provider keeps its own fields in Settings → Storage Settings, and any field left empty there takes the matching STORAGE_* variable. Two choices always come from the page: the provider, which is Cloudflare R2 until you select another, and AWS Region, which always holds a value for AWS S3, DigitalOcean Spaces and MinIO.

  • Keys for AWS S3, Spaces or MinIO only in .env? Open Settings → Storage Settings, select that provider, check AWS Region and press Save Storage Settings. Until you do, Posify looks for an R2 bucket.
  • STORAGE_REGION does not change the region of AWS S3, Spaces or MinIO: the page's AWS Region (us-east-1, or nyc3 for Spaces, until you change it) wins.
  • The wizard's step Where media is stored saves to the database, so its values win over .env. When .env already holds storage keys, the wizard says so and you can leave the step alone.
  • A field filled from .env says Set via environment variable. A value saved here overrides it.

The four providers

ProviderFields on the pageWhere Posify reaches itPublic URL / CDN
Cloudflare R2R2 Account ID (32 characters, from R2 → Overview), Bucket Name, Access Key ID, Secret Access Keyhttps://<ACCOUNT_ID>.r2.cloudflarestorage.com, built from the account ID. The region is always auto.Required: the bucket's r2.dev address or a custom domain you connected. Without it, image addresses point at the private R2 endpoint and fail to load.
AWS S3AWS Region, Bucket Name, Access Key ID, Secret Access KeyWorked out from the AWS Region you pick.Optional: CloudFront or your own domain. Left empty, files are served from https://<bucket>.s3.<region>.amazonaws.com, so the bucket must allow public reads.
DigitalOcean SpacesAWS Region (here the Space's datacenter: nyc3, sfo3, ams3, sgp1, fra1, syd1, blr1 or tor1), Bucket Name (the Space's name), Access Key ID, Secret Access Keyhttps://<region>.digitaloceanspaces.comOptional: left empty, files are served from the Space itself. Or paste the CDN endpoint (…cdn.digitaloceanspaces.com).
MinIOEndpoint URL, AWS Region (us-east-1 is fine, MinIO ignores it), Bucket Name, Access Key ID, Secret Access KeyThe Endpoint URL: the MinIO API (port 9000 by default, not the console), reachable from the Posify server.Optional: where browsers load the files, such as a CDN or reverse-proxy address. Left empty, files are served from <Endpoint URL>/<bucket>.

What Posify stores

FileUploaded fromWho can open it
Product, category and brand imagesThe product, category and brand formsAnyone who has the file's address
Logos and faviconSettings → Branding, and Receipt logo in Settings → ReceiptAnyone who has the address
Maintenance backgroundSettings → Maintenance ModeAnyone who has the address
Profile photosEach person's profileAnyone who has the address
Images in invoice templatesThe invoice template editorAnyone who has the address
Expense receiptsAn expense's receiptStaff, from Posify, when a private bucket is named
Journal attachmentsA journal's Attachments (PDF, PNG, JPG or WebP, up to 10 MB each)Staff, from Posify, when a private bucket is named

Posify opens expense receipts and journal attachments with links that last 5 minutes. They are private only in a private bucket: see Add a private bucket below.

  1. 1

    Create the bucket

    Make one bucket for Posify's files. Settings → Storage Settings repeats these steps in each provider's setup guide, under the fields they fill in.

    1. 1Cloudflare R2: in the Cloudflare dashboard, open R2 → Create bucket.
    2. 2AWS S3: create a bucket in the S3 console and note its region.
    3. 3DigitalOcean Spaces: Spaces Object Storage → Create a Space. Pick a datacenter near your branches: a Space cannot move to another datacenter later.
    4. 4MinIO: run it next to Posify with a volume mounted at /data, open its console (port 9001 by default) and create a bucket.
    MinIO without a volume at /data loses every uploaded file on the next redeploy. Serve it over HTTPS on its own subdomain too: browsers block mixed content, so an http:// endpoint breaks every image on an HTTPS install.
  2. 2

    Create access keys

    Give Posify keys that can read, write, list and delete in that bucket, and nothing more.

    1. 1Cloudflare R2: R2 → Manage R2 API Tokens → Create API token, permission Object Read & Write, scoped to the bucket. Copy both halves: the secret is shown once.
    2. 2AWS S3: in IAM, create a user with programmatic access and a policy granting s3:PutObject, s3:GetObject, s3:DeleteObject and s3:ListBucket on that bucket.
    3. 3DigitalOcean Spaces: API → Spaces Keys → Generate New Key.
    4. 4MinIO: Access Keys → Create access key, in the console.
  3. 3

    Let browsers read the files

    Browsers load images straight from the bucket, so it must be publicly readable, or sit behind a CDN that is.

    1. 1Cloudflare R2: bucket → Settings → Public access: enable the r2.dev subdomain or connect a custom domain. With a custom domain, Cloudflare's CDN answers cached requests without billing the bucket.
    2. 2AWS S3: allow public reads with a bucket policy, or put CloudFront in front of the bucket. New buckets have Block all public access switched on: leave it on only when you serve through CloudFront.
    3. 3DigitalOcean Spaces: Space → Settings → set File Listing to public, or enable the CDN.
    4. 4MinIO: run mc anonymous set download myminio/<bucket>, where myminio is your mc alias for the server.
  4. 4

    Fill in Settings → Storage Settings

    Open Settings → Storage Settings and select the provider's card. Switching from another provider asks Switch storage provider? first.

    1. 1Type the fields the table above lists for that provider.
    2. 2Public URL / CDN: the address from the previous step. R2 marks it Required.
    3. 3Or type the same fields in the install wizard's step Where media is stored, and press Test connection there.
    A field that .env already fills shows Set via environment variable under it, and you can leave it empty here.
  5. 5

    Add a private bucket

    Expense receipts and journal attachments are private documents. With a Private bucket named, Posify writes them there and opens them only through links that last 5 minutes. Without one, they go into the public bucket under private/, where anyone who has a file's address can open it.

    1. 1Create a second bucket in the same account, with public access off and no domain connected.
    2. 2Make sure the keys from Create access keys may use it too.
    3. 3Type its name in Private bucket, or set STORAGE_PRIVATE_BUCKET.
    Name it before the first expense receipt is uploaded. Files stored before stay in the public bucket and are still read from there.
  6. 6

    Test the connection and save

    Test Connection checks the bucket and the private bucket, uploads a one-byte probe file, fetches it back over its public address and deletes it. That catches the most common mistake: keys that work while browsers cannot load a single image.

    1. 1Press Test Connection and read the result under the fields.
    2. 2Press Save Storage Settings.
    3. 3Refresh, next to Test Connection, checks the saved setup again and updates the chip at the top of the page.
    Test Connection needs Bucket Name and both keys on the form, typed now or saved before. Keys that come only from .env cannot be tested with it: save the provider and read the Connected chip, which checks the bucket with what is saved and what .env supplies.

    Check: The result reads, for example, Cloudflare R2 connected and public URL verified, and the chip at the top of the page says Connected.

  7. 7

    Set the upload limits

    Under Upload Settings, set the largest file Posify accepts, then save. A larger file is refused with a message that names the limit.

    Max Image Size (MB)
    20 by default
    Max Video Size (MB)
    1024 by default
    Path Prefix
    uploads/ by default: the folder uploads go into
  8. 8

    Let large files go straight to the bucket (optional)

    When you upload, the browser first asks Posify for a short-lived upload address and sends the file straight to the bucket, so a large photo or video never passes through Posify's server. If the bucket refuses, the browser sends the file through Posify instead, which suits everyday images.

    1. 1In the bucket's CORS rules, allow PUT from your Posify address (for example https://pos.example.com) with the Content-Type header.
    2. 2An SVG always goes through Posify, which turns it into a regular image. A logo keeps its vector.
  9. 9

    Check with a real upload

    Upload an image from a product's form and open the product: the picture must show. Then open the Media Library tab of Settings → Storage Settings.

    1. 1Search files… and the All, Images, Videos and Documents filters find a file; Copy URL copies its address.
    2. 2Upload adds files straight to the library.
    3. 3Delete selected removes files from the bucket for good. Anywhere their address is still used (a product, a page, an email) then shows a broken file.
    4. 4Private files, such as expense receipts, are never listed here.

    Check: The image shows on the product, and the file is listed in the Media Library.

.env for Cloudflare R2 (keep Cloudflare R2 selected in Settings → Storage Settings)
bash
STORAGE_ACCOUNT_ID=your-r2-account-id
STORAGE_ACCESS_KEY_ID=your-access-key-id
STORAGE_SECRET_ACCESS_KEY=your-secret-access-key
STORAGE_BUCKET=posify-media
STORAGE_PRIVATE_BUCKET=posify-private
STORAGE_PUBLIC_URL=https://media.example.com
STORAGE_REGION=auto
KeyRequiredDescription
STORAGE_ACCESS_KEY_IDOptionalThe bucket's access key ID. Needed for uploads unless Settings holds it.
STORAGE_SECRET_ACCESS_KEYOptionalThe bucket's secret key.
STORAGE_ACCOUNT_IDOptionalCloudflare R2 only: your R2 account ID.
STORAGE_ENDPOINTOptionalMinIO only: your server's S3 API URL. The other providers ignore it.
STORAGE_REGIONOptionalShipped as auto in .env.example, for R2. AWS S3, Spaces and MinIO take their region from the page's AWS Region, which always holds a value, so set it there.
STORAGE_BUCKETOptionalThe public bucket's name.
STORAGE_PRIVATE_BUCKETOptionalThe private bucket for expense receipts and journal attachments. Not listed in .env.example.
STORAGE_PUBLIC_URLOptionalThe public base URL (or CDN) that files are served from. Set it before you build when files come from your own domain (see the note below).

Without storage, nothing uploads

Until a bucket is connected, every upload, the Media Library and expense receipts answer File storage is not set up yet. Selling and everything else keep working; products simply have no pictures. Set storage up later in the wizard leaves you here.

Switching provider moves nothing

Selecting another provider sends new uploads there. Files already uploaded stay in the old bucket, and the addresses saved on products and logos still point at it, so keep the old bucket readable until you have uploaded those files again.

Images served from your own domain

Posify optimizes images when they come from R2 (r2.dev), S3, CloudFront or Spaces addresses. For files served from your own domain (a CDN domain or a MinIO server), set STORAGE_PUBLIC_URL, or STORAGE_ENDPOINT for MinIO, in the environment when you build. Set only in Settings, those images are shown at full size. With the prebuilt image, add the variable to the workflow's build step: see Docker Image.

Chapter 19 · Email / SMTP

Send email through your own mail server

Posify sends password resets, staff invitations, receipts, statements and the notifications you choose through an SMTP account you own. Set it up in Settings → Email, or with the SMTP_* variables. Until one of them holds a username and a password, no email goes out, password resets included.

Mail server values for common providers

ProviderServer and PortUsernamePassword
Gmailsmtp.gmail.com, 587Your full Gmail addressAn app password (16 letters); the Google account needs 2-Step Verification on. A personal account sends up to 500 emails a day, Google Workspace up to 2,000.
Zoho Mailsmtppro.zoho.com for an address on your own domain, smtp.zoho.com for an @zoho.com one; 587Your full Zoho addressYour password, or an app password when two-factor sign-in is on. An account in another region uses that region's server, such as smtppro.zoho.eu.
Hosting (cPanel)The Outgoing Server and SMTP Port that cPanel shows under Email Accounts → Connect Devices, such as mail.yourdomain.com, 465The full email addressThat mailbox's password
Brevosmtp-relay.brevo.com, 587Your SMTP login, ending in @smtp-brevo.comAn SMTP key from SMTP & API → SMTP. Your Brevo password does not work.
SendGridsmtp.sendgrid.net, 587The word apikeyAn API key with Mail Send access
Amazon SESThe SMTP endpoint, email-smtp.<region>.amazonaws.com; 587The SMTP username from Create SMTP credentialsThe SMTP password from the same step. AWS access keys do not work.

The same values are in the setup guide on Settings → Email, which opens the right one when it recognises the Server you type.

What Posify sends by email

EmailWhen it goes outTo
InvitationAdministration → Staff → Add person with Email an invitation, or Send the invitation again on their page. The link works for 7 days.The new staff member
Password resetForgot password? on the sign-in page, or Send a password reset on a staff page. The link works for 1 hour.The account's address
Password changedAfter a password is changed, reset, or set by someone else. Not after the first password chosen from an invitation.The account's address
ReceiptThe cashier sends it from the POS while Settings → Point of sale → Sending receipts → By email is on, as it is by default. A PDF copy is attached when the server has Chromium.The customer
Gift cardA card sold with an email address on its line: its number, code, PIN, balance and expiry.That address
Gift card reminderBefore a card expires, when Settings → Gift cards → Remind the holder before expiry asks for it.The address its code went to, else its buyer
Statement and reminderSend statement (a PDF, which needs Chromium on the server) and Send reminder on a customer's Statement tab or in Receivables, and the Due reminder when it is switched on for customers.The customer
NotificationsThe events ticked Email under Settings → Notifications, and the Access ends soon notices.The staff each event concerns
Test emailSend test email on Settings → Email.The address you type
  1. 1

    Switch email on

    Open Settings → Email and turn on the switch beside the page title. Off, Posify sends no email at all, not even password resets, unless this server has SMTP_USER and SMTP_PASS in .env: those then send.

    Check: The Mail server and Sender cards appear.

  2. 2

    Fill in the mail server

    Under Mail server, type the values your provider gives you (see the table above).

    Server
    e.g. smtp.gmail.com
    Port
    587 (STARTTLS) or 465 (TLS)
    Username
    usually your full email address
    Password
    the password or app password; saved and hidden
    The port decides the encryption: 465 connects over TLS, 587 must upgrade with STARTTLS, and any other port is encrypted only if the server offers it. Avoid port 25, which many networks block.
  3. 3

    Set the sender

    Under Sender, choose what inboxes show; the card previews it as Inboxes show …. The sender comes from here or from SMTP_FROM; the Store Email in Settings → General Settings is printed on receipts and in emails, not used as the sender.

    From name
    blank uses your Store Name
    From email
    blank uses the Username
    Gmail sends from the account it signs in with, unless the From email is added to that account as a Send mail as address (Gmail → Settings → Accounts and Import).
  4. 4

    Save, then send a test email

    The test goes through the saved settings, so save first.

    1. 1Press Save Changes at the foot of the page.
    2. 2Press Send test email. Send a test to holds your own address; change it if you like.
    3. 3Press Send.
    The test is tried once and never retried. When it fails, the server's own error shows under Mail server and the guide opens If the test fails: a wrong username or password (Gmail, and Zoho with two-factor sign-in, need an app password), a From email the account may not send as, a certificate error (use the exact server name, not an IP address), or a timeout (check server and port; if 587 is blocked, try 465).

    Check: A message says Test email sent to … and Mail server shows Tested just now. The email arrives in that inbox.

  5. 5

    Schedule the retry job

    An email that fails its first try waits in the outbox. Only the background job /api/cron/email-deliveries, called every 5 minutes with your CRON_SECRET, tries it again: no sooner than 1, 5 and 30 minutes after each failure, four tries in all. An address the mail server refuses outright is not tried again. The same job retries text messages.

    bash
    curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/email-deliveries
    Without the job, Settings → Email warns Failed emails are not being retried, with Cancel them and Keep them. When the job starts, everything still waiting goes out at once. See Background Jobs.

    Check: Settings → Maintenance Mode → Background jobs shows the email-deliveries job as Running.

  6. 6

    Read the delivery log

    Delivery log, at the foot of Settings → Email, lists every email the business sent: who it went to, whether the mail server took it, and why one failed (/settings/email/deliveries).

    1. 1The All, Waiting, Sent and Failed tabs, a date filter and the search (address, subject or category) narrow the list.
    2. 2Each row shows its status (Queued, Sending, Sent, Retrying, Failed or Cancelled) and its tries, such as Try 2 of 4, with the error.
    3. 3Resend now sends a failed email again; Resend all queues every failed one for the next run of the retry job.
    A sent email keeps no copy of its content, so it cannot be resent. Sent emails stay in the log for 30 days and failed ones for 90; the daily housekeeping job deletes the rest.
  7. 7

    Choose which notifications go by email

    Staff get email only for the events ticked Email in Settings → Notifications, and customers only for the reminders switched on there. See Notifications.

KeyRequiredDescription
SMTP_HOSTOptionalYour SMTP server. Default smtp.gmail.com.
SMTP_PORTOptional587 uses STARTTLS, 465 uses TLS. Default 587.
SMTP_USEROptionalSMTP username. Together with SMTP_PASS it sends email even while the switch in Settings is off.
SMTP_PASSOptionalSMTP password.
SMTP_FROMOptionalThe sender, for example Your Business <no-reply@example.com> in quotes. A full name-and-address value is used as it is.

Settings or .env: which one sends

With the switch on, each field typed in Settings → Email wins, and an empty field takes its SMTP_* variable (the server defaults to smtp.gmail.com, the port to 587). With the switch off, the page's values are not used at all, and email goes out only if .env holds SMTP_USER and SMTP_PASS. Changing the server, port, login or sender clears Tested until you send a new test.

Without email

Forgot password? on the sign-in page tells people to ask the store owner or a manager, Add person can only give a first password, the POS cannot email receipts, and notifications ticked Email wait.

Authenticate your sending domain

Most sending services ask you to verify the From email or your whole domain, and give you SPF and DKIM records to add to the domain's DNS. Without them, mail may be refused or land in spam.

Chapter 20 · Text Messages

Send text messages through Twilio

Posify sends text messages through your own Twilio account, or through another SMS service that has an HTTP API. Texts carry receipts, the notifications you tick, customer reminders, marketing offers, and the codes that confirm a phone number or reset a password. Your provider bills every text, so nothing goes out until SMS is switched on in Settings → SMS (Twilio) and a test message has gone through.

Read this first

One accepted test text unlocks SMS

Switching SMS on is not enough. Only a test text that the provider accepts marks the sender as verified, and only for exactly those details. Until then, no receipt, notification or code goes out by text, and the SMS delivery log says Texts are not being sent.

  • Changing the Account SID, Auth Token or sender, in Settings or in the TWILIO_* variables behind them, needs a new test.
  • So does a new BETTER_AUTH_SECRET: the proof is signed with it.
  • .env alone never switches SMS on. The TWILIO_* variables only supply the details.

Before you start

  • A Twilio account with credit. Its Account SID and Auth Token are under Account Info in the Twilio Console.
  • A sender: a Messaging Service (recommended) or a Twilio number. Where the country allows it, a sender name of up to 11 letters and digits.
  • For delivery reports, Posify served at an https:// address (NEXT_PUBLIC_APP_URL).

What Posify sends by text

TextWhen it goes outTo
ReceiptThe cashier sends it from the POS while Settings → Point of sale → Sending receipts → By text message is on (off by default): the total, and a link to the receipt.The customer's number
NotificationsThe events ticked Text under Settings → Notifications → For the team.The number on each person's profile, under Text alerts
Customer remindersDue reminder and Store credit expiring when they are switched on for customers, and Send reminder on a customer's Statement tab or in Receivables.The customer's number
Number confirmation codeSomeone verifies their number on their profile, for password recovery.That number
Password reset codeForgot password? while Settings → Security & Access Control → Password reset by text message is on.The verified number
Test textSend a test text on Settings → SMS (Twilio).The number you type
  1. 1

    Switch SMS on

    Open Settings → SMS (Twilio) and turn on the switch at the top. Leave Send through on Twilio.

    Check: The Twilio account and Messages cards appear. If the server's .env already holds Twilio details, the fields show Set via environment variable, and the test is all that is left.

  2. 2

    Enter the Twilio account

    Copy both values from Account Info in the Twilio Console.

    Account SID
    AC followed by 32 letters and digits
    Auth Token
    never shown again once saved
    Disconnect removes the saved Account SID and Auth Token when you save; Discard brings them back.
  3. 3

    Choose who texts come from

    Send from offers one of two senders.

    1. 1Messaging Service: a Messaging Service SID (MG followed by 32 letters and digits). Recommended: Twilio picks the right number for each country and handles STOP replies.
    2. 2Number or name: a Twilio number with its country code, such as +15551234567, or a name of up to 11 letters and digits where the country allows one.
    People cannot reply to a name, so they cannot text STOP. A Messaging Service SID set in .env still sends in place of a number typed here.
  4. 4

    Save, then send the test text

    The test uses the saved details, so save first.

    1. 1Press Save Changes.
    2. 2Under Send a test text, type a mobile number with its country code.
    3. 3Press Send.
    Twilio bills the test like any other text. When Twilio refuses the text, its reason shows on the page.

    Check: The page says Twilio accepted the text to … Its delivery shows in the log below, and the text arrives.

  5. 5

    Set how texts read

    The Messages card holds three choices. Save after changing them.

    Numbers without a country code
    a two-letter country code, such as BD: customer and staff numbers saved without a code are read as this country
    Add a link to the receipt
    on by default: a texted receipt links to the sale's receipt page
    Codes by text, per day
    50 by default: the most codes texted in a day to confirm a number or reset a password; 0 turns codes by text off
  6. 6

    Read the delivery log

    Delivery log, at the foot of Settings → SMS (Twilio), lists every text: who it went to, what Twilio and the carrier said, and why one failed (/settings/sms/deliveries).

    1. 1Statuses: Queued, Sending, Sent, Delivered, Undelivered, Retrying and Failed.
    2. 2Billed as 2 texts, or more, marks a long message that was split into parts.
    3. 3Resend now and Resend all send failed texts again, and each one is billed again.
    4. 4A text that fails is retried by the same job as email, /api/cron/email-deliveries, up to four tries in all.
  7. 7

    Or use another SMS provider

    Set Send through to Another provider (HTTP) to send through any SMS service with an HTTP API, such as a local gateway. Copy the details from your provider's API page; each text is one request.

    Send address
    the provider's https:// address; it must be on the public internet
    Request
    POST or GET, with a JSON body or a Form body
    Key header
    the header your provider reads the key from, such as Authorization; empty if the key is in the address
    Key
    sent in that header, for example Bearer abc123; never shown again once saved
    Message
    the body your provider expects, with {{to}}, {{to_digits}}, {{from}} and {{body}}
    Sender
    the number or sender name your provider gave you
    Message ID in the answer
    optional, such as data.id, so the log shows it
    This provider has no .env fallback and sends no delivery reports, so its texts stay at Sent. It still needs a saved setup and an accepted test text.
KeyRequiredDescription
TWILIO_ACCOUNT_SIDOptionalYour Twilio account SID (AC…). Used while the Account SID field in Settings is empty.
TWILIO_AUTH_TOKENOptionalYour Twilio auth token.
TWILIO_MESSAGING_SERVICE_SIDOptionalA Twilio Messaging Service (MG…). Preferred: when it is set, it sends in place of any number.
TWILIO_FROM_NUMBEROptionalA Twilio number in international form (+15551234567) or a sender name. Needed only without a Messaging Service.

Twilio bills every text

The test, every resend and every part of a long message are billed. A text holds up to 160 basic Latin characters, or 153 a part once it is longer. One character outside that set, such as Bengali, Arabic, Hindi or Chinese script or an emoji, makes it 70, or 67 a part. Codes by text, per day caps the codes a flood of requests could run up; when the day's codes are used up, the owners get Codes by text paused for today in the bell.

Offer texts and STOP

Campaign and automation texts go only to customers who agreed to offers, and every one is billed like any other text. With Twilio, a customer who replies STOP is blocked by Twilio itself; the next text to them fails, and Posify then sets their SMS consent to Does not want offers and never tries the number again. With another provider, Posify cannot see replies: the line under each offer text (Settings → Marketing) must say how to stop them, for example "To stop offers, call 01…", and your staff record a refusal on the customer's page.

Delivery reports from Twilio

When NEXT_PUBLIC_APP_URL starts with https://, Posify hands Twilio the address https://<your-address>/api/webhooks/twilio with every text, so there is nothing to set up in Twilio. Twilio signs each report with your Auth Token, Posify checks the signature, and the log moves the text from Sent to Delivered or Undelivered. On http:// or localhost, texts stay at Sent.

Chapter 21 · Notifications

Decide who hears about what

Posify tells people about stock, orders, bills, dues, registers and background jobs in three places: the bell at the top of the page, email and text messages. Settings → Notifications decides, event by event, which of them each event uses, and what customers are sent about their own account. Browser push notifications are not included in 1.0.

Before you start

  • For email notifications, email set up: Email / SMTP.
  • For text notifications, SMS switched on and tested: Text Messages.
  • The background jobs scheduled: the digests and checks run only when your scheduler calls them. See Background Jobs.

Events for the team

EventWhat and whenWho hears it
Low stockA list per branch of the items at or below their reorder point. Once a day.See stock
Out of stockAn item that a sale or a movement took to nothing at a branch. When it happens; off until you switch it on.See stock
Purchase order lateA sent order whose expected date has passed with goods still to come. Once a day.Receive goods, or Approve purchase orders
Supplier bill dueA bill about to fall due, and again once it is past due. Once a day.Pay suppliers
Customers' old duesWho owes, and how much, past the days set under Timing. Once a day.Set credit limits, tax exemption and store credit, or See the books
Register left openA register still open after Registers closed by. Checked every hour.Registers (in the Settings group), and the cashier who opened it
Sold below zeroUnits sold that a branch did not have, at the POS or from an offline sale. When it happens.See stock
Offline sale needs reviewA sale taken offline that the server refused when it synced. When it happens.Edit sales
Store credit expiringHow much customers' store credit expires soon. Once a day.Set credit limits, tax exemption and store credit
Repeating expenses recordedThe copies of rent, salaries and other repeating expenses written on their days. When it happens.Record expenses
Batches expiringPer branch, batches with stock that expire within the days set under Timing, or have expired. Once a day.See stock

Who hears it: everyone whose role holds that permission, at the event's branch. People who work at every branch hear of every branch, and the owner hears of everything. In app starts ticked for every event but Out of stock; Email and Text start unticked.

Timing

SettingDefaultWhat it changes
Supplier bills due within3 days (0 to 60)How many days before its due date a bill is mentioned.
Remind about dues older than30 days (0 to 365)When a customer's due counts as old, counted from its oldest sale or opening due.
Remind again every7 days (1 to 90)How often a customer's reminder repeats while the due stays unpaid.
Store credit expiring within7 days (1 to 90)How far ahead expiring store credit is announced, once per credit.
Batches expiring within30 days (1 to 365)How far ahead the batches digest looks.
Registers closed by23:00A register still open after this time, on the business's clock, is reported.
Daily digests from08:00The hour from which the day's digests and reminders go out, in the business's time zone.

Notices that are always sent

NoticeGoes toWhere
Background jobs have stoppedMaintenance mode (in the Settings group)The bell and the dashboard
The books need a lookPost journal entriesThe bell
Stock adjustment waitingApprove adjustments and counts, at that branchThe bell
Stock requested by a branchTransfer stock, at the branch askedThe bell
Access ends soonSuspend and reactivate staff, for the people they manageThe bell and email
Codes by text paused for todayThe ownersThe bell

These are not on Settings → Notifications.

  1. 1

    Choose who hears what

    Open Settings → Notifications. Under For the team, tick In app, Email or Text for each event, then press Save Changes.

    Email goes out once Settings → Email is set up, and texts once SMS is switched on and a test message has been sent; the page says so while either is missing. A box ticked before then waits.
  2. 2

    Switch on customer notices

    Under For customers, tick Email or Text for Due reminder and Store credit expiring. They go to the customer's own email address or phone, in the business's language, and stay off until you switch them on.

  3. 3

    Set the timing

    The Timing card holds the numbers in the table above. Daily digests from and Registers closed by run on the business's clock (Settings → General Settings → Time zone), whatever time zone the server keeps.

  4. 4

    Check the jobs that send them

    Notifications that are not instant come from background jobs. Calling a job twice is harmless: each event reaches each person once.

    1. 1/api/cron/notification-digests, hourly at :05: low stock, late orders, bills due, customers' dues, expiring store credit and expiring batches, once the business's clock reaches Daily digests from.
    2. 2/api/cron/register-watch, hourly at :20: registers still open past Registers closed by.
    3. 3/api/cron/staff-access, hourly at :25: Access ends soon, 3 days before a staff member's access end date.
    4. 4/api/cron/email-deliveries, every 5 minutes: emails and texts that failed, tried again.

    Check: Settings → Maintenance Mode → Background jobs shows each one as Running.

  5. 5

    Read your notifications

    The bell at the top of every page opens your newest notifications, and a toast announces a new one. Notifications in the account menu opens the same list.

    1. 1All, Unread and Archived tabs, and Mark all as read.
    2. 2Open on a notification takes you to what it is about.
    3. 3See all opens the Notifications page (/notifications), with every notification and a Kind filter.
    4. 4Archive or Delete tidies the list. The daily housekeeping job deletes notifications older than 90 days.

No browser push in 1.0

Notifications reach people in the bell, by email and by text. Installing Posify as an app does not add push notifications.

Ticked, but nothing arrives?

Check that the person's role holds the event's permission and that they work at its branch; that Settings → Email works (send a test); that SMS passed its test and the person has a number under Text alerts on their profile; and that the job shows Running in Settings → Maintenance Mode → Background jobs.

Chapter 22 · Tax

Set up tax rates and tax groups

A new business charges no tax until you add tax rates and put them into tax groups under Settings → Tax. Each product is taxed at one group, taken from the product, its category, its branch or the business default. One switch decides whether the prices you type include tax.

Decide this first

Prices include tax, or tax on top

Prices include tax is one switch for the whole business. The installer asks for it, and it lives in Settings → General Settings → Financial year and tax. Settings → Tax shows it too, but only someone with the General and branding permission can change it.

  • On: a product priced 115 with 15% tax charges 115, with the tax inside the price.
  • Off: the same product charges 132.25, because the tax is added at the POS.
  • A change applies from the next sale at every POS. Sales already made stay as they were charged.
  • With prices including tax, sales always round tax per document, so their totals add up.

Which tax group a product is taxed at

OrderWhere it is set
1The product's Charge tax on this product switch. Off, the product is sold tax-free (0%), whatever its category says. A gift card is never taxed when it is sold; tax is charged on what it buys.
2The product's Tax class.
3Its category's Tax group, then the nearest parent category that names one.
4The branch's Default tax group, in Settings → Branches.
5The Default tax group in Settings → Tax → Tax defaults.
6None of these: the product is sold tax-free.

Then a branch's tax override may swap the group it landed on for another group, or for tax-free. A tax-exempt customer, or a cashier selling tax-free with a reason, takes the tax off the whole sale.

Kinds of tax rate

KindWhat it chargesFor
Percentage of the priceA share of the price, from 0 to 1000%, with up to 4 decimals. Some duties are above 100%.VAT, GST, sales tax
Fixed amount per unitThe same amount, in the business currency, on each unit sold (each piece, or each kg of an item sold by weight), whatever the price. A discount does not lower it.A bag levy, a sugar tax per litre, a duty per pack
Withholding taxA share held back from a supplier's payment and paid to the tax office instead. Offered when paying a supplier; never in a tax group and never charged on a sale.Withholding on supplier payments

Where tax shows

PlaceWhat you see
ReceiptsSettings → Receipt holds Show the tax breakdown (on: one line per tax rate under the totals), One line per tax rate (off: each tax on its own line, such as VAT 15% and SD 10%, in place of one Tax line) and Show tax numbers (off: the business's tax registration and the customer's Tax ID). A tax-exempt sale prints Tax exempt with its reason.
Invoice templatesA template prints the tax registration where it shows it. See Invoice Templates.
The booksTax on sales posts to Output tax payable (2200), and tax on supplier bills to Input tax receivable (1400). Sales revenue is net of tax. See Accounting.
Tax reportFinance → Statements → Tax report: output and input tax by month and by rate, the net to pay or reclaim, tax-exempt sales, sales by tax treatment, and withholding tax held back from suppliers.
  1. 1

    Enter your tax registration

    Optional. Under Your tax registration, type the number the tax office gave the business (a VAT, GST, BIN, ABN or TRN number) and what it is called, then press Save tax settings.

    What it is called
    e.g. VAT No. or GSTIN
    Tax registration number
    your number
    Receipts print it while Settings → Receipt → Show tax numbers is on. A branch registered on its own types its own number in Settings → Branches, and its receipts print that one instead.
  2. 2

    Add a tax rate

    Under Tax rates, press Add rate. A rate is one tax, like VAT or a city levy, and it charges nothing until it is in a tax group.

    Name
    e.g. VAT
    Code
    optional
    Kind
    Percentage of the price, Fixed amount per unit, or Withholding tax
    Rate
    e.g. 15; a fixed rate asks for an Amount per unit instead
    Description
    optional
    Active
    on; an inactive rate is not offered for new groups

    Check: The rate is listed under Tax rates. Rates and groups save from their dialog at once, without the page's save button.

  3. 3

    Put rates into a tax group

    Under Tax groups, press Add group. A product or category is taxed at a group: its rates, charged together in order.

    Name
    e.g. Standard rate
    Code
    optional; a product import can name the group by its code
    Rates, in the order they are charged
    up to 5; Add a rate adds one
    Compound
    on a rate after the first: charged on the price plus the taxes above it
    Reported as
    Standard-rated, Zero-rated, Exempt or Out of scope
    Active
    on; an inactive group is not offered for products and categories
    10% then 5% compound comes to 15.5%, not 15%. A group with no rates sells tax-free. Reported as is only a label for the tax report's Sales by tax treatment: what a group charges is its rates.

    Check: The dialog shows the group's total, such as Total rate: 15%.

  4. 4

    Choose the defaults

    Under Tax defaults, choose how tax is rounded and what a product without a group of its own is taxed at, then press Save tax settings.

    Rounding
    Per document (recommended): each line's tax is worked out exactly and the sale's total tax is rounded once. Per line: each line's tax is rounded on its own, as some tax authorities require.
    Default tax group
    a group, or None — tax-free unless a product or category sets a group
    Changing the default asks first and says how many products take their tax from it. From the next sale they are taxed at the new default; branches with a default of their own keep it.
  5. 5

    Give products and categories their group

    Most businesses set the default group and give a different group only where it differs.

    1. 1A product: Charge tax on this product, and its Tax class. An empty Tax class takes the category's group, then the branch's, then the business default.
    2. 2A category: its Tax group, or Inherit from parent / business default.
    3. 3A branch: Default tax group in Settings → Branches, for its sales when neither the product nor its category names a group.
    4. 4A product import: the chargeTax column (false sells tax-free) and taxGroup (a group's code or name; empty inherits).
  6. 6

    Set up tax exemptions

    A sale can be tax-free in two ways: an exempt customer, or a cashier selling tax-free with a reason.

    1. 1Exempt customer: on the customer, turn on Tax exempt, with an Exemption certificate number (optional) and Valid until (optional). Their sales carry no tax and the POS asks no reason; after the last day, their sales carry tax again. This needs Set credit limits, tax exemption and store credit.
    2. 2At the POS: Tax exempt opens Tax-exempt sale. Type a Reason (required) and, if there is one, an Exemption certificate number (optional), then press Sell tax-free. The reason is kept on the sale and printed on the receipt.
    3. 3Settings → Tax: Tax exemption reasons (up to 20, each up to 100 characters) are the reasons a cashier picks from, and Only the listed reasons stops them typing their own.
    4. 4Who may sell tax-free: Whoever may give discounts (the default), or Only those allowed to sell tax-free, which is the Sell tax-free permission in Administration → Roles.
  7. 7

    Change a rate on a date

    Edit the rate and use Change the rate on a date, for example for a budget's new VAT rate. Type the New rate and pick the day it Starts on. For a tax holiday, tick Only for a while and pick the Last day.

    Check: Until that day, sales charge the old rate; from the start of it, in the business's time zone, they charge the new one. Every POS switches on its own, offline too.

  8. 8

    Tax a branch differently

    Under Branch tax overrides, pick a Branch. For a Group, choose what it is Charged here as: another group, or Tax-free at this branch. Then press Save overrides for that branch. Use it for a branch in another state or province, or in a free zone.

  9. 9

    Read the tax report

    Finance → Statements → Tax report (/accounting/statements/tax) shows the tax charged on sales and paid on purchases, by month and by rate, and the net to pay or reclaim. It needs See the books or Tax reports.

    1. 1Not by rate (rounding, entries by hand) holds the tax no rate can claim, so the rates and that line always add up to the tax accounts.
    2. 2Tax-exempt sales lists each sale made without tax, with its reason and whether it came from an exempt customer or the POS.
    3. 3Sales by tax treatment splits net sales by each group's Reported as.
    4. 4Settle tax records what you paid the tax office for a period, or got back, so the tax accounts read zero for it. It needs Post journal entries.
    5. 5CSV and PDF export the report.
    The tax report is not a tax return. It gives the totals to hand your accountant or tax adviser. See Accounting.

Changes apply to new sales only

A changed rate, group, default or branch override charges from the next sale. Sales already made keep the tax they were charged.

Who may change tax

Changing Settings → Tax needs the Tax permission, which Administrator and Manager have. Tax rates, groups and defaults apply at every branch, so an account limited to some branches can read them but not change them.

Chapter 23 · Branding & Appearance

Your name, logo and colours

Posify shows your business's name, logo and colours, never its own. Set the name in Settings → General Settings, and the logos, favicon, colours and default theme in Settings → Branding. The brand is the same for everyone: the dashboard, receipts and emails all use it.

  1. 1

    Name the business

    Open Settings → General Settings. Under Store Information, the name and contact details print on receipts and in emails. Store Name also names the installed app and heads the maintenance page.

    Store Name
    required
    Store Email
    required; printed on receipts and in emails, but not the sender, which is set in Settings → Email
    Phone Number
    pick the country, or type the number with its country code
    Store Description
    optional; also the installed app's description
    Address
    printed on receipts, unless a branch has its own

    Check: Press Save Changes; the toast says Settings saved.

  2. 2

    Upload the logos and favicon

    Open Settings → Branding. Under Brand assets, drop a file onto each card or click it to choose one. Uploads need storage connected: see Storage & Media.

    Light Theme Logo
    PNG, JPG, SVG or WebP, up to 5 MB; 400×120 px recommended
    Dark Theme Logo
    the same, for the dark theme
    Favicon
    PNG, ICO, SVG, JPG or WebP, up to 1 MB; 32×32 px recommended
    A logo keeps its SVG vector. Receipts can print a separate image: Settings → Receipt → Receipt logo, where a black-and-white logo prints best.
  3. 3

    Pick the brand colours

    Under Brand colours, set each colour with the colour picker, a hex value or rgb(). Buttons, links and highlights in the dashboard, on receipts and in emails use them, and Preview shows how they apply.

    Primary colour
    #2065D1 until you change it
    Secondary colour
    #8b5cf6
    Accent colour
    #f59e0b
  4. 4

    Check the chart colours

    Charts that compare several things, like payment methods and sales by category, use your three brand colours first, then Colour 4, Colour 5 and Colour 6. Anything past six is grey, as Other. Sales trends and age bands keep their own quiet colours.

    1. 1Leave a colour empty for its default: #10b981, #f43f5e and #0ea5e9.
    2. 2The preview warns when two colours look almost the same, or when one almost disappears on the light or dark background.
    3. 3Reset chart colours empties all three.
  5. 5

    Choose the default appearance

    Under Default appearance, set Mode to Light or Dark: how the app opens before a person picks for themselves. Light is the default, and Posify never follows the device's own setting. Then press Save branding.

  6. 6

    Let each person set their own look

    Each person changes their own view from the account menu at the foot of the sidebar: the sun or moon button switches between light and dark, and Preferences opens the rest. These stay in that browser and change nothing for anyone else.

    1. 1Dark mode and Contrast.
    2. 2Right to left, and Collapsed sidebar.
    3. 3Sidebar → Color: Integrate or Apparent.
    4. 4Language, and the fullscreen button.
    5. 5Reset to defaults goes back to the business's default look.
  7. 7

    Install Posify as an app

    Chrome and Edge show Install app in the header once the browser offers to install Posify, which needs a favicon or logo. Not now hides it for 30 days. Safari installs from its Share menu.

    1. 1The installed app carries your Store Name and an icon made from the favicon, or from the logo when there is no favicon.
    2. 2It opens in its own window, with shortcuts to POS, Sales and Dashboard.
    3. 3Installing changes nothing about notifications: there is no push in 1.0.
    Browsers allow the offline till only over HTTPS (or on localhost), and only from a production build. See Offline Selling.
  8. 8

    Change the built-in defaults

    For people who change the code only. config/branding.config.ts holds what a business shows before it sets its own name, currency, language and colours; nothing else in the app names the product.

    config/branding.config.ts
    ts
    export const DEFAULT_STORE_NAME = "Posify";
    export const DEFAULT_CURRENCY = "USD";
    export const DEFAULT_LANGUAGE = "en";
    
    export const DEFAULT_PRIMARY_COLOR = "#2065D1";
    export const DEFAULT_SECONDARY_COLOR = "#8b5cf6";
    export const DEFAULT_ACCENT_COLOR = "#f59e0b";

No logo, no stand-in

Posify never shows a placeholder brand of its own. Until you upload a favicon or logo, the browser tab and the installed app show the browser's own placeholder icon.

A square favicon makes the best app icon

Posify renders the app icon at 192 and 512 px from the favicon, or the logo, and pads the maskable icon onto white so that a round mask never clips it. A square image fills it best.

Chapter 24 · Languages & RTL

18 languages, right to left included

Posify ships 18 languages, and Arabic runs right to left. You choose which of them your team may use and which one is the default; each person then picks their own from the header. The default language has no prefix in the address, and every other one has its code in front.

The 18 languages

LanguageCodeIn the pickerDirection
EnglishenEnglishLeft to right
BengalibnবাংলাLeft to right
ArabicarالعربيةRight to left
SpanishesEspañolLeft to right
FrenchfrFrançaisLeft to right
GermandeDeutschLeft to right
TurkishtrTürkçeLeft to right
Hindihiहिन्दीLeft to right
DutchnlNederlandsLeft to right
Chinese (Simplified)zh中文Left to right
Japaneseja日本語Left to right
ZuluzuisiZuluLeft to right
XhosaxhisiXhosaLeft to right
AfrikaansafAfrikaansLeft to right
SwahiliswKiswahiliLeft to right
HausahaHausaLeft to right
YorubayoYorubaLeft to right
IgboigIgboLeft to right

Which language each message uses

MessageLanguage
ScreensThe language the person picked in this browser, else the business's default.
NotificationsThe business's default language, in the bell, by email and by text.
Customer messagesReceipts sent by email or text, statements, reminders and gift card emails: the business's default language.
Invitation emailThe language of the page the person adding the staff member had open, when that language is switched on; else the default.
Password reset emailThe language of the page Forgot password? was used on, when it is switched on; else the default.
Printed receipts and invoicesTheir template's own language. See Invoice Templates.
Maintenance pageEnglish, apart from the headline and message you type in Settings → Maintenance Mode.
  1. 1

    Choose the default language

    Open Settings → General Settings. Under Language and currency, pick the Default Language, or press the star beside a language under Supported languages. Then press Save Changes.

    The installer set the default language you picked there, and switched on English as well.

    Check: The page moves to the address of the new default, which has no language prefix.

  2. 2

    Switch languages on and off

    Under Supported languages, tick each language your team may use, then press Save Changes. Only ticked languages are offered in the picker.

    1. 1At least one language stays ticked.
    2. 2Unticking the default makes the first ticked language the new default.
    3. 3A link with the prefix of a language you switched off redirects to the same page without the prefix.
  3. 3

    Know how the addresses work

    The default language owns the addresses without a prefix (/sales), and every other switched-on language keeps its code in front (/bn/sales). A business with one language has no prefixes at all.

    Default English, Bengali also switched on
    txt
    https://pos.example.com/sales       English
    https://pos.example.com/bn/sales    Bengali
    https://pos.example.com/en/sales    redirects to /sales (308)
    Change the default later and nothing breaks: an old link with the default's prefix, or with a switched-off language's prefix, redirects permanently to the address without one.
  4. 4

    Let each person pick their own

    Each person chooses from the flag button in the header (Select Language), or from Preferences → Language in the account menu. The choice is remembered in that browser.

    1. 1On a first visit, a business whose default is not English opens in its default language.
    2. 2A business whose default is English follows the browser's language, when that language is switched on.
  5. 5

    Check right to left

    Arabic switches every screen to right to left. Anyone can do the same in another language with Preferences → Right to left, in their own browser. Check the POS, receipts and reports in Arabic before you rely on it.

Changing the words

The words live in locales/<code>.json, one file per language, with en.json as the reference; a key a language lacks shows in English. After editing a file, keep every {placeholder} and tag of the English, run pnpm check:i18n, then rebuild with pnpm build, because the words are built into the app.

Chapter 25 · Staff & Roles

Add your staff and decide what they may do

Each person gets their own account, with a role that decides what they may do and branches that decide where they may do it. Posify creates nine built-in roles at install; you can change them and add your own. The owner account the installer created holds every permission, and nobody else can change it.

Before you start

  • Email set up, to send invitations: Email / SMTP. Without it, give each person a first password instead.
  • Your branches and registers in place: Settings → Branches and Settings → Registers (Point of Sale).
  • A role with Add staff to add people, and Manage roles to change roles. Administrator has both; Manager has Add staff.

The nine built-in roles

RoleWhat it is forSettings pagesLeft out
AdministratorEverything in the business: sales, stock, money, staff, roles and settings. The only built-in role that manages roles and sees the activity log.AllNothing
ManagerRuns the shop day to day: every POS permission, sales, products, stock, buying, customers, suppliers, loyalty, gift cards, every report, and staff (add, edit, suspend, remove, set PINs).General Settings, Branding, Tax, Registers, Point of saleManaging roles, the activity log, posting journals, the chart of accounts, closing months, reversals, write-offs, gift card codes and PINs, issuing or importing gift cards, the other settings pages
SupervisorLeads a shift: every POS permission but selling from an expired batch, plus Sales reports, Their own sales history and Staff reports.NoneSettings and staff
CashierSells at the POS: opens and closes a register, puts cash in and takes it out, gives discounts, takes returns and payments against dues, sells and takes gift cards, adds and edits customers.NoneVoids, price changes, selling on account, selling tax-free, reports
AccountantKeeps the books: every accounting permission, supplier bills and payments, payments against dues, and the sales, purchasing, financial and tax reports.AccountingThe POS, stock changes, staff
External AccountantAn outside accountant: every accounting permission and the financial and tax reports, with read access to sales, purchases, customers and suppliers.AccountingTaking payments against dues, paying suppliers, the POS, staff
Stock KeeperReceives goods, adjusts, transfers and counts stock, and sees costs.NoneApproving adjustments and counts
PurchaserSuppliers, purchase orders, receiving goods and returning them; adds and edits products.NoneApproving purchase orders, supplier bills, supplier payments
Read-onlySees sales, products and their costs, stock, purchases, customers, suppliers, the books and every report, and changes nothing.NoneThe POS, staff, the activity log, settings

As shipped. Each can be renamed and given or denied permissions, but not deleted, and Reset to default brings its shipped permissions back. Every one includes See the dashboard.

  1. 1

    Add a person

    Open Administration → Staff and press Add person. Fill in the form, then press Create account. Only roles whose permissions you hold yourself are offered.

    Name
    their full name
    Email
    the address they sign in with
    Job title
    optional, e.g. Shift lead
    Mobile number
    optional; where their text notifications go
    Role
    e.g. Cashier
    Extra roles (optional)
    up to 5 more roles; they get everything those roles allow as well
    Access ends (optional)
    a date and time, for temporary access such as an outside auditor
    Where they work
    the branches they work at, and Every register or particular POS terminals. Every branch includes branches added later; only someone who works at every branch can give it.
    Signing in
    Email an invitation (a link to set their own password, valid for 7 days), or Give a first password that meets your password rules and hand it over
    Their branches and registers limit what they see and sell, whatever their role allows. With extra roles, the main role decides their home page and dashboard, and sign-in hours and two-step verification follow the strictest of their roles.

    Check: A message says the person was added and invited by email, or can sign in now, and their staff page opens.

  2. 2

    Give them a register PIN

    On their staff page, the Register PIN card lets a colleague switch to them at the POS without signing anyone out. Type a New PIN and PIN again, then press Save PIN.

    1. 14 to 8 digits, not one digit repeated and not a run like 1234.
    2. 2They can set or change their own from their profile.
    3. 3Five wrong tries lock the PIN for five minutes. Clear PIN removes it.
    4. 4Setting someone else's PIN takes Set staff register PINs and every permission they hold. Nobody sets the owner's.
    Someone whose role does not work the POS needs no PIN. Switching at the till is in Point of Sale.
  3. 3

    Give a different till role at one branch

    Till role by branch, on their staff page: at a branch with its own till role, what they may do at the POS (discounts, voids, returns, the drawer) comes from that role. Everything else stays their main role's.

  4. 4

    Suspend, reactivate or remove someone

    The Signing in card on their staff page holds what you need when someone leaves or forgets a password.

    1. 1Suspend ends every session at once; they cannot sign in until you press Reactivate.
    2. 2Remove deletes an account only if it has recorded nothing. For someone with sales, drawers or other records in their name, suspend instead, so those records keep their name.
    3. 3Send a password reset emails them a reset link; Send the invitation again does the same while they have not set a password.
    4. 4Set a new password is for someone who cannot get an email: tell them the new password in person. It signs out every device of theirs, and Also turn off two-step verification helps when they lost their phone and backup codes.
  5. 5

    End access on a date, or let someone in after hours

    Access end date, on their staff page, ends someone's access by itself: pick Ends on and At (or press +7 days or +30 days), then Save. After it they cannot sign in, and their sessions end.

    1. 1The people who manage them hear 3 days before, in the bell and by email.
    2. 2Remove end date makes their access last until it is changed.
    3. 3When their role limits sign-in hours, Sign-in hours lets them in for a one-off late shift: pick For (30 minutes to 12 hours) and press Allow sign-in now. End now stops it early.
    The end date runs on their branch's clock, or the business's. The warning comes from the background job /api/cron/staff-access: see Background Jobs.
  6. 6

    Make your own role

    Open Administration → Roles and press New role. Give it a Name, and start from Copy permissions from (another role, or Nothing: start empty), or from a starter role for a Retail shop, a Grocery or supermarket or a Pharmacy. Press Add role.

    1. 1Tick the permissions it grants. Search permissions and Show only ticked help in the long list; Risky marks the sensitive ones, and a permission that another one needs is ticked with it.
    2. 2Opens on sign-in: Dashboard or POS (the till).
    3. 3Dashboard: the job its dashboard is laid out for (Automatic, Overview, Till, Stock, Buying or Money).
    4. 4Preview this role shows the menu, dashboard and POS actions it would give, before you save.
    5. 5Save, check the lists of permissions Added and Taken away, and confirm with Change access.
    You cannot tick a permission you do not hold, or edit a role you carry yourself. Roles apply at every branch, so an account limited to some branches can only read them.

    Check: The role is listed on the Roles page, and the people who hold it get its access on their next click; no sign-out needed.

  7. 7

    Add sign-in rules and till limits to a role

    Two cards on each role add limits on top of its permissions.

    1. 1Sign-in security: Require two-step verification (holders who have not set it up are sent to do so, and can do nothing else first), and Limit sign-in hours with a From and To time for each day, on the clock of each person's branch. The owner is never limited. Press Save.
    2. 2Till limits: Most discount per sale, Most price change, Most refund per return and Most cash out at once. An empty box means the business default for the discount, and no limit for the rest. Past a limit, a colleague whose own limit covers it approves with their PIN. Press Save limits.
  8. 8

    Compare roles and export them

    Press Compare and export on the Roles page to see every role side by side: what it grants, its till limits and its sign-in rules.

    1. 1Roles to compare picks the columns, and Differences only hides the rows where they agree.
    2. 2Print, Download CSV or Download PDF for an audit. A PDF needs Chromium on the server.

The owner

The installer's account is the business's owner. It holds every permission at every branch, whatever role it carries. Nobody can change its role, suspend or remove it, set its register PIN or give it an access end date, and sign-in hours and a role's two-step rule never apply to it. Ownership cannot be handed over in the app. A lost owner password is restored on the server with pnpm create-admin: see Backups & Recovery.

Nobody raises their own access

You cannot change your own role or status, give a role that holds permissions you lack, or give someone branches you do not work at. A manager limited to some branches sees and manages only the staff of those branches.

The activity log

Administration → Activity log (/staff/activity) records who did what, to which record, when and from which IP address: sign-ins and failed sign-ins, settings, roles, sales, stock, money and more. Filter by Person, Action, Record type, Outcome and Date, and open an entry to see its changes before and after. Only Administrator sees it by default (See the activity log). Entries cannot be edited or deleted, and are kept for two years.

New permissions after an update

When an update adds permissions, the Roles page shows New permissions to review. Roles never change by themselves: add the new permissions to a role, or dismiss the notice.

Pay, targets and notes

A staff page also holds Commission % (of net sales on the sales they are named salesperson on), Sales targets (daily, weekly and monthly, shown on their dashboard), and Notes, which are dated, signed and never edited.

One account for each person

The activity log, every sale and every drawer count carry the name of the person who did them. A shared login makes them meaningless, so give everyone their own account and their own PIN.

Chapter 26 · Security

Lock down sign-in before real staff use it

Settings → Security & Access Control holds the sign-in rules for everyone: session length, lockout, rate limits, two-step sign-in and password rules. Roles can ask for more, and a few server values protect the whole install. Go through this chapter before the first real staff member signs in.

Before go-live

Five checks

Each is set once, and the rest of this chapter relies on them.

  • BETTER_AUTH_SECRET, INSTALL_TOKEN and CRON_SECRET are long random values of your own, not the examples.
  • Neither DEMO_MODE nor NEXT_PUBLIC_DEMO_MODE is set.
  • Two-step sign-in is on for the owner, and required for the roles that handle money and staff.
  • Posify's own port (3000 by default) is reachable only through your reverse proxy.
  • Behind a CDN other than Cloudflare, or a load balancer, TRUSTED_PROXIES names it.

Settings → Security & Access Control

SettingDefaultWhat it does
Session Duration (days)7 (1 to 365)How many days a sign-in lasts. A session in use is renewed once a day.
Max Login Attempts10 (0 to 100)Failed sign-ins for one email from one address before it locks; 0 switches the lockout off. Counting by address as well means nobody can lock the owner out from somewhere else.
Lockout Duration (min)15 (1 to 1440)How long the lock lasts.
Unlock an account—Type the email and press Unlock to clear its failed sign-ins on every device it was locked from.
Enable Rate LimitingOnLimits how many requests one account or one address may send. Sign-in keeps its own limit of 8 tries a minute from one address, whatever this switch says.
Rate limit presetsDefaultSigned-in accounts, Sign-in and Signed-out (by address) each take Default, which keeps each action's own limit, or Lenient (100/15m), Moderate (20/15m) or Strict (5/15m).
Offer two-factor sign-inOffShows the Two-Factor Authentication card on everyone's profile. Switching it off hides the card but un-enrols nobody.
Minimum Password Length8 (8 to 128)Applies to every new password.
Require switchesOffRequire Uppercase, Require Lowercase, Require Numbers and Require Special Characters. Letters from scripts without case, such as Arabic, Chinese or Hindi, count for both case rules. Always refused, whatever the switches: common passwords, the person's own name or email, the store name, and patterns like 12345678.
Password reset by text messageOffForgot password? also offers a code by text, sent to a number the person verified on their profile. It needs SMS set up and tested, and the owner can use it only with two-step verification on. Countries codes may be texted to takes two-letter codes; empty means your business's own country.

Press Save Security Settings after a change. Unlock an account works at once, without saving.

Secrets on the server

ValueWhat it protectsKeep in mind
BETTER_AUTH_SECRETSigns every session. It also keys the codes sent by text, the PIN switch at the POS, and the proof that SMS passed its test.32+ random characters. In production, sign-in refuses to work while it is empty, a known placeholder or too short. Changing it signs everyone out, and texts stop until you send a new test text.
INSTALL_TOKENThe install wizard, which creates the owner account.32+ random characters. Unused once the business is installed: the wizard's address then answers not found.
CRON_SECRETThe background job addresses.16+ random characters (openssl rand -hex 32 is better). The .env.example placeholder or a shorter value is refused, and every job answers 401. Change it in .env and in every scheduler line together.
QZ_TRAY_PRIVATE_KEYSigns every print job sent to the tills' QZ Tray.Whoever has it can send jobs to every till that trusts your certificate. Only people who may use the POS can have a job signed. See Hardware.
Saved credentialsThe SMTP password, the Twilio Account SID and Auth Token, the SMS provider's key and the storage keys typed in Settings.Never sent back to the browser: the page shows only a masked hint, and in demo mode not even that.
  1. 1

    Turn on two-step sign-in

    Switch on Offer two-factor sign-in and press Save Security Settings. Then each person, starting with you as the owner, sets it up from their own profile.

    1. 1Open the account menu → Profile, and under Two-Factor Authentication press Set Up Two-Factor Authentication.
    2. 2Step 1: scan the QR code with an authenticator app (or type the code shown under Can't scan?).
    3. 3Step 2: type the 6-digit code from the app.
    4. 4Keep the Backup Codes somewhere safe: they sign you in if the phone is lost.

    Check: On the person's staff page, Signing in says Two-factor sign-in is on.

  2. 2

    Require two-step verification for a role

    Open Administration → Roles, pick the role, and in Sign-in security switch on Require two-step verification, then press Save. The card counts the holders who have not set it up yet.

    Holders who have not set it up are sent to set it up and can do nothing else until they do, and they cannot turn it off. The owner is never forced.

    Check: The staff page of each holder without it shows 2-step needed until they set it up.

  3. 3

    Help someone who lost their phone

    On their staff page, under Set a new password, type a new password, tick Also turn off two-step verification, and press Set password. Tell them the password in person: every device of theirs is signed out.

    The owner's own account, run where Posify runs
    bash
    pnpm create-admin you@example.com "a-new-password" --reset-2fa
    The owner cannot be reset from a staff page. For the owner, pnpm create-admin with --reset-2fa sets a new password and turns two-step verification off: see Backups & Recovery.
  4. 4

    Put Posify into maintenance mode

    Use it while you update or repair Posify. Open Settings → Maintenance Mode.

    1. 1Turn on Enable Maintenance Mode.
    2. 2Write a Headline and a Maintenance Message, or leave them empty for Posify's own: your Store Name is temporarily offline, and a short message.
    3. 3Optional: a Background image, and Show countdown with Expected back online.
    4. 4Under Allowlisted IP addresses, add your own address, one per line, to keep using everything.
    5. 5Press Save Maintenance Settings. Live Preview shows the page visitors get.
    The list matches exact addresses, not ranges. Posify reads the visitor's address through your proxy, so behind a CDN other than Cloudflare, or a load balancer, set TRUSTED_PROXIES, or the list sees the proxy's address instead of yours. Sign-in and Settings stay reachable from any address, so whoever may change Maintenance Mode can always switch it off.

    Check: From another address, every page but sign-in, password reset and Settings shows the maintenance page with HTTP status 503, and changes sent to the server are refused. From an allowed address, Posify works as usual.

  5. 5

    Unlock someone who is locked out

    After too many failed sign-ins, a person waits out the Lockout Duration. To let them in now, type their email under Unlock an account and press Unlock.

    Check: The page says Account unlocked. They can sign in again now.

Visitors' real addresses

Rate limits, the sign-in lockout and the maintenance allow-list key on the visitor's IP address. A reverse proxy on the same machine or private network (nginx, Caddy, Traefik, Docker) is trusted already, and Cloudflare needs nothing. Behind another CDN or a load balancer that forwards from a public address, list it in TRUSTED_PROXIES (IPs and CIDR ranges, comma-separated; cloudflare stands for Cloudflare's ranges), or every visitor shares its address and its limits.

Keep Posify's own port private

A request that reaches Posify's port directly, not through your proxy, can claim any address, which defeats the lockout and the rate limits. Let the internet reach only the reverse proxy, with HTTPS: see Domain & HTTPS.

Rate limits across servers

Rate-limit counters live in the database by default, shared by every instance of Posify. RATE_LIMIT_STORE=memory keeps them in each instance's memory: only for exactly one instance.

The installer closes for good

Once the business is installed, the install wizard's address answers not found, and INSTALL_TOKEN is no longer used.

Every sign-in is logged

Sign-ins, failed sign-ins, password changes and two-step changes are in the Activity log, with the IP address. See Staff & Roles.

Access by the clock

A role can limit sign-in hours, and a staff member can have an access end date. Both are in Staff & Roles.

Never turn on demo mode for a real business

DEMO_MODE or NEXT_PUBLIC_DEMO_MODE set to true, 1, yes or on turns the site into a public demo: deletes, settings saves, profile changes and actions that reach outside services are refused, and the sign-in page shows the demo accounts.

Locked out of the owner account

If the owner's password is lost and email cannot reset it, pnpm create-admin restores the account from the server: see Backups & Recovery.

Chapter 27 · Point of Sale

Set up branches, registers and the till

The till, POS in the sidebar, runs in the browser on any computer, tablet or phone. Before anyone sells, the business needs a branch that sells over a counter, a register at it, the ways to pay it takes and a receipt layout. A new install already has a Main Branch with one register, Counter 1. This chapter sets those up and walks through one register's day; the user manual covers day-to-day selling.

Read this first

Settings apply everywhere; branches and registers hold the local detail

Settings → Point of sale, Payments, Receipt and Numbering apply at every branch and register. An account limited to some branches can read them but not change them. The local detail sits one level down: a branch has its own address, receipt lines and tax registration number, and a register has its own receipt prefix, printer and cash drawer.

  • Who may sell, discount, void or take returns is a permission of each role, not a setting. See Staff & Roles.
  • Each device picks the register it stands at. Its sales, its drawer and its held sales follow that choice.
  • The till keeps selling without the internet once each device is prepared for it: see Offline Selling.

Before you start

  • An account with the Settings permissions Branches, Registers, Point of sale, Payment methods, Receipt and Document numbering. The Administrator role holds them all.
  • Tax rates and groups, if you charge tax: a new business charges none until you add them (Tax).
  • Products to sell. The install wizard's sample data is enough to try the till.

Settings → Point of sale

SettingWhat it doesNew business
Require an open drawer to sellEach register must open its drawer with a float before it takes a sale, so every sale lands in a session that is counted at closing. Off, the till also offers Sell without a shift.Off
Print a receipt after every salePrints as soon as a sale is paid, to the register's printer or the browser's print dialog. Off, the cashier prints from the Sale complete screen, or later from the till's Sales list.Off
Open the cash drawerOpens the drawer when cash changes hands, on registers whose Cash drawer switch is on. Needs QZ Tray and a receipt printer with a drawer port (Hardware).Off
Largest discountThe most a cashier may take off a line or a sale, for roles that may discount at all: 0 to 100%. 100% sets no cap. A role can carry its own limit instead.100%
Selling past zero stockOnly products that allow it (the product's Sell below zero at the POS switch), or Every product. Every oversell is reported. The back office never sells past zero.Only products that allow it
Salesperson on each saleDon't ask, Optional or Required: who made the sale on the floor, which is not always the cashier, at the till and on back-office sales. The staff reports work out commission from it.Don't ask
Notes and coinsWhat a cashier counts the drawer in when a shift opens and closes, separated by commas. Empty uses the usual notes and coins of your currency.Empty
Blind closeCashiers count the drawer without seeing what it should hold; the difference shows once it is closed. Roles with See the expected cash when closing a drawer still see it.Off
Count difference needing approvalA close whose count is off by more than this needs a note and the PIN of someone who may approve it. 0 asks no one.0
Default floatWhat a new shift's float starts at when the last shift left nothing to go by. 0 starts it empty.0
Largest floatA drawer opened with more than this needs a note saying why. 0 sets no limit.0
Lock the POS when idleMinutes without a touch, 0 to 240, before the till locks until a cashier types their PIN. 0 never locks it. Locking needs a connection: offline, the till stays with its last cashier.0 (never)
Offline selling windowHours, 1 to 72, a register keeps selling with no connection after it last reached the server. See Offline Selling.12 hours
Sending receipts: By emailThe till offers to email the receipt to the address typed or the one on file. Needs Settings → Email set up (Email / SMTP).On
Sending receipts: By text messageThe till offers to text a short message with the total and a link to the receipt. Needs Settings → SMS (Twilio) set up (Text Messages).Off
Quick keysUp to 60 products every till shows first, in its Favourites tab. They are starred at the till by anyone whose role may change the Point of sale settings. Clear the quick keys empties the list.None
SoundsOn or off, a volume, and four sounds: Item added, Payment accepted, Sale complete, and Error or stock warning.On, volume 50%

Every option on the page, with what a new business starts with. Who may sell is not here: it is the Use the POS permission of each role.

Settings → Payments

SettingWhat it doesNew business
Ways to payCash, Card, Bank transfer, Other, Store credit, Loyalty points, Gift card and On account. A sale may be split across several of them. One has to stay on.Cash and Card
Cash roundingRound to: No rounding, or a step from 0.01 to 100. Direction: To the nearest step, Always up or Always down. Only cash is rounded; the difference prints on the receipt and posts to Rounding differences. The page shows an example.No rounding
Allow depositsThe till may take part of a sale now and the rest later, for a sale with a customer attached. The goods are set aside, and the sale is complete once it is paid off.Off
Store credit from returns expires afterDays that credit refunded on a return stays good, to the end of the last day in the business's time zone. 0 keeps it forever; at most 3650.0 (never)

Loyalty points and Gift card also need their own programme switched on, and Store credit is offered when the customer on the sale holds some: see Loyalty & Gift Cards. The permission behind this page is called Payment methods.

Settings → Receipt

SettingWhat it doesNew business
Paper width58 mm or 80 mm. A browser print is sized to it, with no margins.80 mm
Print the logoThe business logo (Settings → Branding), or a Receipt logo chosen here. A black-and-white logo prints best.On
Header, FooterLines above and below the receipt, up to 500 characters each, such as a VAT number or an exchange policy.Empty
Show the tax breakdownTax lines under the totals. A tax-exempt sale always prints its tax line.On
One line per tax rateEach tax on its own line (VAT 15%, SD 10%) in place of one Tax line.Off
Show tax numbersThe business's tax number (Settings → Tax) under its details, and the customer's tax ID under their name, when they have them.Off
Show the loyalty balanceThe customer's points after the sale, when loyalty is on.On

A branch's own address, phone, email, receipt header and footer (Settings → Branches) replace these on its receipts, and its Tax registration number replaces the business's. For a different layout altogether, see Invoice Templates.

What the till asks of a role

To…Permission
Open the till and sellUse the POS
Open or close a drawerOpen a register, Close a register
Cash in, Cash out, No salePut cash in or take it out
Discount a line or the saleGive discounts, up to Largest discount or the role's own limit
Type another priceChange a price at the POS
Sell without tax on requestGive discounts, or Sell tax-free when Settings → Tax → Who may sell tax-free asks for it
Void a saleVoid a sale
Take a returnTake returns, at a branch with Take returns here on
Leave the rest on the customer's accountSell on account
See the expected cash on a blind closeSee the expected cash when closing a drawer
Approve a drawer count that is offApprove a drawer count that is off
Sell from a batch past its expirySell from an expired batch

The Cashier role starts with Use the POS, Open a register, Close a register, Put cash in or take it out, Give discounts and Take returns. When a cashier lacks a permission or goes past a limit, Ask a manager lets a colleague who holds it approve that one action with their register PIN. Roles, their till limits and who works where: Staff & Roles.

  1. 1

    Set up each branch

    Settings → Branches → Add branch, or edit Main Branch. A branch is a shop, a kiosk or a warehouse. Only the name is required.

    Name
    Up to 100 characters, for example Main shop.
    Code
    Up to 10 capital letters, digits and dashes, for example HQ. It goes into document numbers when Branch code in numbers is on (step 6).
    Address, Phone, Email
    Printed on this branch's receipts. Left empty, they print the business's.
    Sell over a counter here
    On for a shop: registers may stand here. Off for a warehouse.
    Hold stock here
    Off for a kiosk that sells from another branch's shelves; then choose that branch in Sells stock from (Inventory).
    Take returns here
    A till here may take goods back and refund them.
    Receipt header, Receipt footer
    Replace the lines of Settings → Receipt for sales at this branch. Empty uses those.
    Default tax group
    Charged here when neither the product nor its category names a tax group. Shown once tax groups exist.
    Tax registration number
    For a branch registered on its own (a GSTIN per state): its receipts print this number instead of the one in Settings → Tax.
    Time zone
    The clock for the sign-in hours and access end dates of the people who work here. Reports and the books keep the business's time zone.
    Default branch
    New records fall back to it. There is always exactly one, and only someone who works at every branch can move it.
    Only a branch nothing refers to can be deleted. Switch it off instead (Active): it keeps its history but takes no new sales, stock or staff. The default branch stays active.

    Check: The branch is listed with its registers, and with No POS, No stock or No returns where a switch is off.

  2. 2

    Add a register for each counter

    Settings → Registers → Add register. A register is one till at a branch; each device then picks the register it stands at. An account limited to some branches sees the registers of its own branches.

    Branch
    An active branch that sells over a counter. A register stays at its branch.
    Name
    For example Front POS.
    Code
    Required. Up to 10 capital letters, digits and dashes, for example R2.
    Receipt prefix
    Numbers this register's sales: FR- gives FR-000001. Empty uses the Sale prefix of Settings → Numbering.
    Receipt printer
    The printer's name in QZ Tray, such as EPSON TM-T20III. Empty prints through the browser's print dialog (Hardware).
    Cash drawer
    On when a drawer is wired to this register's printer. It opens on cash when Settings → Point of sale says so.
    Active
    A switched-off register keeps its sessions and sales, and no device can pick it.
    Give each device its own register, and keep each register on one device. Held sales and the offline queue are kept in that device's browser, per register.

    Check: The register is listed under its branch in Settings → Registers.

  3. 3

    Decide how every till behaves

    Settings → Point of sale holds the options in the first table above, in five cards: At the POS, Locking and offline selling, Sending receipts, Quick keys and Sounds. They apply to every register. Press Save changes at the foot of the page.

    With Require an open drawer to sell off, a cashier may choose Sell without a shift. Cash taken that way goes into no drawer, so no count checks it, and Sales History reports those sales as cash taken with no drawer open.
  4. 4

    Choose the ways to pay

    Settings → Payments, the second table above. Switch on each way your counters take money, set cash rounding if your smallest coin is larger than the currency's smallest unit, and decide whether the till may take deposits.

    1. 1Card and Bank transfer are recorded with an optional reference. Posify 1.0 does not connect to card terminals.
    2. 2On account leaves what is unpaid as the customer's due, within their credit limit, for a cashier allowed to sell on account.
    3. 3At closing, a drawer is counted in cash and in every other way to pay that is switched on, except On account.

    Check: The till's payment dialog lists the ways you switched on.

  5. 5

    Lay out the receipt

    Settings → Receipt, the third table above. The Preview beside the form draws a sample sale with your logo, header and footer, at the paper width you chose.

    For another layout altogether (a QR code, other fields, a design of your own), make a receipt template and set it as the default: Invoice Templates.
  6. 6

    Check the sale numbers

    Settings → Numbering lists every numbered document with its Prefix, its Digits (3 to 10, 6 by default) and an Example. A new prefix counts on from the highest number already using it; documents already numbered keep their numbers.

    Sale
    SAL- by default, so SAL-000001. A register's own Receipt prefix replaces it there.
    Return
    RET-.
    Customer receipt
    RCT-: money taken against a customer's dues, not the till's slip.
    Gift card
    GC-, so card numbers read GC-000012.
    Branch code in numbers
    Off by default. On, sales, returns, purchases, stock and money documents carry their branch's code after the prefix, and each branch counts on its own: SAL-MALL-000001. A branch without a code keeps the plain number; journals and opening balances never carry one.
    A sale taken offline prints a provisional number first. Its final number follows once the register reconnects (Offline Selling).
  7. 7

    Give staff their registers and PINs

    On each person's staff page, tick the branches they work at, and narrow Every register to tie them to particular tills. Each person then sets a register PIN of 4 to 8 digits in their profile, or a manager sets it on their staff page; colleagues use theirs to take over the till, unlock it and approve. The fourth table above lists what the till asks of a role. Details: Staff & Roles.

    Check: A cashier tied to some registers is offered only those when the till asks which register they are at.

  8. 8

    Open the till on each device

    Open POS in the sidebar. The first time on a device, the till asks "Which register are you at?". Pick the register (Recent on this device lists the last ones used there), then press Start selling.

    Switch register changes it later. Finish the payment in progress first.

    Check: A message says Now selling at, followed by the register and its branch: Counter 1 · Main Branch on a new install.

  9. 9

    A register's day: open the shift

    With no drawer open, the till shows Open your shift. Count the cash in the drawer and type it as Counted opening cash, or use Count by notes and coins, then press Start shift. Opening a drawer posts no journal: the float only moves cash inside the branch's cash.

    1. 1The till says what the last shift left in the drawer. A float that differs from it, or one above Largest float, needs a note saying why.
    2. 2Print opening slip prints the opening count.
    3. 3A drawer still open from an earlier day, or opened by another cashier, offers Carry on in it or Count and close.
    4. 4Without Require an open drawer to sell, Sell without a shift is offered too.

    Check: Shift started, and the drawer chip reads Drawer open.

  10. 10

    During the day: cash in, cash out and no sale

    The till's Cash drawer dialog moves cash that is not a sale. Each move needs a reason, which is kept with the drawer's report, and each opens the drawer when the cash drawer is set up.

    1. 1Cash in: cash put into the drawer that is not a sale, such as change from the safe.
    2. 2Cash out: cash taken out that is not a refund, such as a drop to the safe or a paid-out expense. Past the role's cash-out limit, a manager approves it with their PIN.
    3. 3No sale: opens the drawer for change or a check, with no money moving.
    Cash in and Cash out post to Cash in transit until you say where the money went: banked, spent or put back, from Money in and out (Accounting).
  11. 11

    Mid-shift: print an X report

    Cash drawer → Print X report prints a reading of the open drawer at the receipt's paper width: when it opened, the float, the number of sales, the sales total, each other way to pay, cash sales, cash in, cash out, cash refunds and the cash expected in the drawer. It changes nothing, so print one whenever you need it.

    Check: A slip titled X report prints. If no window opens, allow pop-ups for this site.

  12. 12

    Voids and returns at the till

    The till's Sales list finds a sale by receipt number or phone number. Both actions below need a connection.

    1. 1Void reverses the whole sale: its stock goes back and its money is reversed. It asks why and cannot be undone. It needs Void a sale.
    2. 2Return items takes some or all goods back, each Back on the shelf or Damaged, with a reason. It needs Take returns, at a branch with Take returns here on.
    3. 3Refund to: Cash from the drawer, Card by hand, Bank transfer, Store credit (for a customer who is not archived), Exchange (the refund pays toward the next sale rung up) or Other.
    4. 4Anything the customer still owes on the sale comes off first. Points, store credit and gift card money go back where they came from (Loyalty & Gift Cards).
    Void a cash sale at the till while its drawer is still open: the back office (Sales → All sales) refuses it then. Once that drawer is closed, the back office asks for an open drawer at the sale's branch to pay the cash back from.
  13. 13

    Close the drawer and print the Z report

    Cash drawer → Close drawer. Type the Counted cash, or count by notes and coins, then each other way to pay the till took. Split the cash between Leave in the drawer (the next shift's float) and To the safe or bank, add a Closing note, and close.

    1. 1With Blind close on, the cashier counts without seeing what the drawer should hold; the difference shows once it is closed.
    2. 2A count off by more than Count difference needing approval needs a note and the PIN of someone who may approve it.
    3. 3Sales still waiting to sync must sync first: "Close the drawer once they have."
    4. 4Then Print Z report: the X report's figures, plus the counted cash, what was left and taken to the safe, and the variance for each way to pay.
    Whatever a count finds over or short posts to Cash over and short (6300). Settings → Notifications → Registers closed by reports registers still open after that hour, through the register-watch job (Background Jobs).

    Check: Drawer closed. The session is listed under Sales → Register sessions, with its Z report.

Held sales stay on the device

Hold (F4) parks a sale on its register, with an optional label, so the cashier can serve the next customer. Each register keeps up to 50 held sales in that browser. Resuming one re-checks prices and stock and says what changed.

Keyboard shortcuts

F2 customer, F3 discount, F4 hold or resume, F9 take payment, / search, F8 the scan field, Alt + C calculator, Esc closes a dialog, and ? shows the list on the till. A barcode scanner needs no shortcut: it works from anywhere on the till (Hardware).

Deposits and sales on account

With Allow deposits on and a customer on the sale, the payment dialog takes part now and leaves the rest due; the goods are set aside, and Collect balance in the till's Sales list takes the rest. On account leaves the rest as the customer's due, paid later with Receive due at the till or Money in and out → Customer receipts.

Ask another branch

When an item is out at this branch, Ask another branch on the till requests it from a branch that holds it. That branch approves the request and ships it as a transfer (Inventory).

Sales History and Register sessions

Sales → Sales History shows sales by cashier and counter, money taken by tender, and how each drawer's count came out. Sales → Register sessions lists every drawer with its X report (so far) or Z report, its cash events and what it was over or short.

Card payments are recorded, not charged

Posify 1.0 does not connect to card terminals. The cashier takes the card on your own reader and records Card, with an optional reference such as the authorisation code. Bank transfer works the same way.

Rehearse a register's day before going live

On a test register, open a shift, ring up a cash sale and a card sale, do a Cash out, print an X report, return one item, then close the drawer and print the Z report. Check the session under Sales → Register sessions and its journals under Accounting → Journals.

Chapter 28 · Offline Selling

Keep selling when the internet drops

When the shop's connection drops, the till keeps selling. It saves each sale on the device, prints a receipt with a provisional number, and sends the sales to the server by itself when the connection comes back. Offline selling needs a production build served over HTTPS or on localhost, and each device must have opened the till online first.

Before you rely on it

Three things every till device needs

Offline selling is prepared device by device. A device that lacks any of these cannot sell offline, however long it was used online.

  • A production build: pnpm build, then pnpm start, or the prebuilt Docker image. pnpm dev has no offline till (Running the App).
  • A secure address: https:// (Domain & HTTPS), or localhost on the same machine. A till opened on a plain http:// network address cannot work offline.
  • The till opened online once on that device, signed in, until it has loaded its products. Otherwise it says "This register has not reached the server on this device yet, so it cannot be used offline."

What works offline

AreaWorks offlineNeeds a connection
SellingScanning, the product grid, quantities, line notes, discounts, tax exemption, holding and resuming salesReturns, voids, and finding an earlier sale in the till's Sales list
PaymentsCash, Card, Bank transfer and OtherLoyalty points, Store credit, Gift card, and Receive due (a payment against a customer's dues)
The drawerOpening it, Cash in, Cash out, No sale, closing itThe expected cash and the Z report, which are worked out when the register reconnects
CustomersFinding one of the 500 most recently changed active customers; adding a new one with a name and a phone or an emailAny other customer
Gift cards—Selling or reloading a card, and checking a balance
ReceiptsPrinting, with a provisional numberSending by email or text, once the sale has synced
CashiersThe last cashier stays on the tillLocking the till when idle, and switching cashier with a PIN
Back office—Every page outside the till

Offline, the payment dialog simply leaves out what needs a connection. Trying one anyway says "… cannot be taken while the register is offline".

What the server does with a queued sale

Part of the saleWhen it arrives
Whether it counts as offlineWhile online, the till is handed a pass signed by the server: with its offline data (every 15 minutes and on every reconnect) and whenever the person at the till changes. Each queued sale carries the newest pass. The server treats a sale as offline only when the pass is its own, for that register, no newer pass had been issued to that register before the sale's time, and the sale is dated inside the offline window (Settings → Point of sale → Offline selling window, plus an hour). Any other sale gets every check of a sale rung up online.
Prices and taxWorked out again from the catalogue and tax tables as they are on arrival, as for any sale. If a price or a tax changed and the payments no longer match, the sale goes to review.
The timeKept: the sale is dated when it was taken, inside the offline window, so reports and the books put it on the right day.
The cashierThe person the pass names, as long as they still work at that branch and register; otherwise the person signed in when it is sent.
Stock and other rulesThe same rules as a sale rung up online: role limits and approvals, the till's selling-below-zero setting (the product's Sell below zero at the POS switch, or Settings → Point of sale for every product), "open the drawer first", and the branch's product list. A queued sale that breaks one of them, for example stock another till sold meanwhile, is refused and goes to the till's review list: a manager fixes the cause, such as adding the stock, and presses Send again (Know why a queued sale is refused). A sale that did sell below zero is marked oversold; people who see inventory get Sold below zero in the bell, and Inventory → Movements → Only sold below zero lists them.
Loyalty pointsA sale for a named customer earns its points now, dated at the time it was rung up.
The booksThe sale posts its journal like any other (Accounting).

Limits

WhatLimit
Offline selling window1 to 72 hours since the register last reached the server; 12 by default
Unsynced sales per register500. Then the till says "This register has too many unsynced sales. Reconnect to sync before taking more."
Products in the snapshot20,000, with their variants, prices and the branch's stock
Customers in the snapshotThe 500 most recently changed active customers
Product picturesUp to 400 per download, and the browser keeps up to 600; none on a data-saver connection
Snapshot refreshEvery 15 minutes while the till is open and online, and each time the connection comes back
Retries while offlineEvery 30 seconds
  1. 1

    Prepare each device

    On every device that will sell offline, sign in, open POS, pick its register and wait until the products have loaded. From then on the browser keeps a copy of the till and of the register's snapshot.

    1. 1Open the camera scanner once while online, if the device scans with its camera: it is downloaded the first time it opens. A hardware scanner and typing the barcode always work.
    2. 2Installing Posify as an app is optional: Chrome and Edge offer Install app once the business has a logo or favicon. The browser tab works offline just the same.
    3. 3Use one register per device. The drawer, the held sales and the queue follow the register the device picked.

    Check: With the network unplugged, the till still opens, and its banner reads Offline — sales are being queued.

  2. 2

    Set the offline selling window

    Settings → Point of sale → Locking and offline selling → Offline selling window: how long a register keeps selling with no connection, counted from the last time it reached the server. 1 to 72 hours, 12 by default.

    1. 1After the window, the till locks with "Reconnect to keep selling" until it reaches the server again and someone is signed in.
    2. 2Nothing taken before is lost: the lock screen counts the sales still saved on the device.
    3. 3The window protects a device that leaves the shop. The real protection is on the server: a queued sale is treated as offline only with a pass the server signed for that register, dated inside the window.
    Signing out clears the till's offline copy and its window on that device, though never the queue: queued sales are sent at the next signed-in session. Do not sign out of a till you may need offline; switch cashiers with their PIN instead, and open the till online once after any sign-out.
  3. 3

    Sell while offline

    The banner shows how old the stock figures are ("Stock shown is from …"). Each sale is saved on the device with "Saved offline — receipt …", and its receipt prints a provisional number, the device's code and a running number, under the line "Provisional receipt number — the final number follows once the register reconnects."

    1. 1Pay with Cash, Card, Bank transfer or Other.
    2. 2A customer added at the counter is saved on the device and sent with the sale. The server finds them by phone or email if they already exist, so nobody is added twice. Adding one needs the Add customers permission, online or offline.
    3. 3Later, the sale can be found by its provisional number in Sales and in the till's Sales list, for a return for example.
  4. 4

    Let the queue sync

    As soon as a request reaches the server, the till sends its queue by itself. The banner shows "… sales waiting to sync" and offers Sync now.

    1. 1Items go one at a time, register by register, in the order they were taken. Items of the same moment go drawer opening first, then new customers, sales, cash in and out, and the drawer closing last.
    2. 2A drawer opening or closing that has not gone through holds everything queued after it on that register. Other registers are not held.
    3. 3Each queued item carries its own key, so an item the server already saved is never taken twice.

    Check: The banner says Back online, and nothing is left waiting to sync.

  5. 5

    Close the drawer, online or offline

    A drawer can be closed offline, after offline sales too. The close is queued behind them with the counted cash; the expected cash and the Z report are worked out when the register reconnects. Drawers opened, closed or cash moved offline follow the same pass rule as sales: a drawer opened offline without a valid pass is checked like one opened online.

    1. 1The close is sent only once every sale before it is in. A sale the server refuses holds the close back until it is sent again or discarded, so the Z never misses it.
    2. 2Until the server has the close, the till keeps that drawer closed and opens no new drawer online on top of it.
    3. 3Online, sales still waiting must sync first: "Close the drawer once they have."
  6. 6

    Know why a queued sale is refused

    A queued sale the server refuses on its merits is neither dropped nor retried for ever: it moves to the review list of the device that took it. Everyone with the Edit sales permission at that branch, and the owner, gets "An offline sale needs review" in the bell, once per sale, with the receipt, the register and the reason. Settings → Notifications → Offline sale needs review can add email or text messages.

    1. 1A product was archived ("… is no longer sold").
    2. 2A price or a tax changed, so the payments no longer cover the sale, or come to more than it.
    3. 3The customer was archived, or a sale on account would pass their credit limit.
    4. 4A permission the sale needs is missing: to sell, discount, change a price, sell on account or add customers. The queue is sent with the permissions of whoever is signed in on the till at that moment; adding a customer is checked against the cashier who took the sale.
    5. 5A way to pay, or deposits, was switched off in Settings → Payments.
    A refusal because the person was signed out, or because the server asked the till to wait, is retried by itself instead.
  7. 7

    Fix a refused sale on the device that took it

    The review list lives in that device's browser. Open the till on it and press Review on the banner: each sale shows its provisional receipt number, when it was taken, how many attempts were made, and "Server said: …".

    1. 1Read the reason.
    2. 2Fix the cause in the back office: reactivate the product, put the price back, raise the credit limit, give the permission back, or switch the way to pay on again.
    3. 3Press Send again.
    4. 4If the sale cannot be sent as it is, record it another way, such as a back-office sale, then press Discard.
    Discard deletes the sale from the queue for good, and the customer holds its receipt: discard only once the sale is recorded. Discarding a refused drawer opening sends that drawer's sales without a drawer, so record its float and takings another way first. A drawer opened offline is refused while another drawer is open on that register on the server: close that one, then press Send again.

The browser keeps the till

Once a device has opened the till while online, the browser keeps a copy of it. With the connection down, the till opens from that copy.

Each register downloads a snapshot

While online, each device downloads for its register the catalogue with prices and the branch's stock, the tax tables, the selling settings, the receipt layout (with the receipt template, when one is the default), the quick keys, recent customers and product pictures.

Everything offline goes into a queue

Sales, drawer openings, cash in and out, drawer closings and new customers wait in the browser's own storage on that device, kept per register, until they sync.

Offline is judged by evidence

The till does not trust the computer's connected flag, which can be wrong when the shop's router is up but its line to the internet is down. It is offline when a request fails to reach the server, and it tries again every 30 seconds.

Keep the browser's storage

Queued sales exist only on that device until they sync. Do not clear the site's data, browse in a private window, or use a clean-on-exit browser setting on a till. If the browser cannot store anything, the till refuses an offline sale rather than take money for a sale that would exist nowhere: "This browser cannot store offline sales, so the sale was not taken."

Good habits

Open the till online at least once a day on every device. Avoid changing prices, taxes or products while a till is offline. Sync before closing the drawer, and deal with any review the same day. Watch the banner: Offline — sales are being queued, … waiting to sync, … need review, and Signed out — sign in again to sync.

Points, store credit and gift cards need the server

An offline till offers none of Loyalty points, Store credit or Gift card, and cannot sell a gift card. A sale taken offline for a named customer still earns its points once it reaches the server (Loyalty & Gift Cards).

Chapter 29 · Hardware

Scanners, printers and the cash drawer

Posify runs in the browser, so the till works on any computer, tablet or phone with a modern browser. This chapter sets up the devices around it: barcode scanners and the camera, barcodes in the catalogue, receipt printers, QZ Tray for printing without a dialog, the cash drawer and label printers.

Plan this first

Most devices need no software; three things need QZ Tray

A keyboard-mode scanner, the camera and any printer the computer can print to work straight from the browser. QZ Tray, a small program on the till's computer, is needed only to print receipts without the print dialog, to open the cash drawer, and to send labels straight to a thermal printer.

  • Without QZ Tray, receipts print through the browser's dialog and the drawer stays shut. A sale is never held up by a printer.
  • QZ Tray only takes jobs from a site it can verify: Posify signs each job on the server with your key, set in QZ_TRAY_CERTIFICATE and QZ_TRAY_PRIVATE_KEY.
Download QZ Tray

Barcode formats

FormatDigitsHow Posify checks it
EAN-1313Check digit verified
UPC-A12Check digit verified
GTIN-1414Check digit verified
Code 128Anything else: 1 to 80 printable charactersLetters, digits and common symbols

A product's or variant's Barcode standard is detected (Auto-detect) or chosen. Its Barcode source says where the code came from: Printed by the manufacturer, Issued to us by GS1, Internal (this business only) or Not specified.

What QZ Tray is used for

UseSet up in
Receipts with no print dialogSettings → Registers → Receipt printer
Opening the cash drawerSettings → Point of sale → Open the cash drawer, and Settings → Registers → Cash drawer
Labels straight to a thermal printerThe label studio's Print to the thermal printer

Each till computer needs QZ Tray installed and running, the printer installed in the operating system with its own driver, and the printer's exact name as QZ Tray lists it.

The label studio

OptionChoices
Label size40 × 25 mm, 50 × 30 mm or 60 × 40 mm
Printer languageZPL / ZPL emulation (Zebra and printers that emulate it) or TSPL / TSPL emulation (TSC and printers that emulate it)
Resolution203 or 300 dpi
Copies1 to 500 per item, or One label per unit on hand
Show SKU, Show priceOn or off

Each label shows the product (and variant) name, the barcode with its digits, and the SKU and price when chosen; ZPL and TSPL labels also carry the business name at the top. A preview shows the first label, and the studio remembers the size, language, resolution and printer on this browser.

Choosing devices

DeviceWhat to look for
Barcode scannerWorks as a USB or Bluetooth keyboard and sends Enter after the code. On phones and tablets, the camera may be enough.
Receipt printer58 mm or 80 mm paper, with a driver for the till computer's operating system, so the browser can print to it.
Cash drawerPlugs into the receipt printer's drawer port and opens on the standard ESC/POS pulse, sent through QZ Tray.
Label printerA driver for printing from the browser; or ZPL or TSPL, for the downloaded command files and direct printing.
  1. 1

    Connect a barcode scanner

    A USB or Bluetooth scanner that works as a keyboard needs no driver and no set-up in Posify. To the computer it types the code and presses Enter; Posify tells a scan from typing by its speed.

    1. 1Send Enter after each code. This is the usual factory setting; without it the till never sees the end of the code.
    2. 2Type fast: a scan is a burst of characters no more than 50 ms apart on average and never more than 100 ms apart. Most scanners do this out of the box, and a Bluetooth scanner's batches are fine.
    3. 3Send codes of at least 4 characters. Shorter bursts are treated as typing.
    4. 4Add no prefix or suffix other than Enter. An extra printable character becomes part of the code, and the product is not found.
    Inside another text box (a customer's name, a note) the scanner types there, like a keyboard; in the product search box a scan still counts as a scan. While a dialog is open, the till refuses a scan with "Close the open dialog, then scan again.", so a scan never changes a sale halfway through a payment. While the till is locked, scans are ignored.

    Check: Scanning a product anywhere on the till screen adds it to the sale, whatever has the cursor.

  2. 2

    Scan with the camera

    Scan with camera, next to the Scan a barcode… field (F8), uses the device's camera. It uses the browser's own barcode reader where there is one, otherwise a reader built into Posify, and reads EAN, UPC, Code 128 and other retail barcodes, and QR codes.

    1. 1The browser asks once for permission to use the camera. If it was refused, allow the camera for the site in the browser's settings.
    2. 2Browsers give the camera only to an https:// address. On a plain http:// address the till says "This browser cannot scan with the camera."
    3. 3For offline use, open the camera scanner once while online: it downloads the first time it opens.
  3. 3

    Give every item a barcode

    Each product or variant carries a Barcode, its Barcode standard and its Barcode source. A product or variant saved without a barcode gets an internal EAN-13 starting with 20; Generate a barcode on the product form, and Generate barcodes for variants, do the same on demand, and a product imported from a CSV with an empty barcode gets one too.

    1. 1Codes starting with 2 are reserved for use inside one business, so internal codes scan at your tills and on your labels but are not trade barcodes for selling through others.
    2. 2A barcode belongs to one product or one variant across the catalogue. Saving a code another one holds is refused: "Barcode is already assigned to another product or variant".
    3. 3A scan looks the code up as a barcode or SKU, exactly, ignoring spaces, dashes and letter case. A 13-digit code that is a UPC-A with a leading 0 finds the UPC-A. A product with variants is found by the variant's own barcode or SKU.
    4. 4Several matches say "Multiple products match this code. Please fix duplicate SKU or barcode values."; none says "No product found for the scanned code."
  4. 4

    Print receipts through the browser

    Any receipt printer the computer can print to works: the receipt prints through the browser's print dialog. Set the paper width (58 mm or 80 mm) in Settings → Receipt; the page is already sized to it, with no margins. In the print dialog, choose the receipt printer.

    1. 1Settings → Point of sale → Print a receipt after every sale prints as soon as a sale is paid. Otherwise the cashier prints from the Sale complete screen, or again later from the till's Sales list.
    2. 2Settings → Point of sale → Sending receipts lets the till email or text the receipt instead of, or as well as, printing it.
    3. 3A sale taken offline prints its provisional number with a note saying so.

    Check: A test sale prints at the right width with no blank margin.

  5. 5

    Make a QZ Tray key and certificate

    Do this once, on any computer with OpenSSL. Posify signs every QZ Tray job on the server with the key, and gives each till the matching certificate.

    bash
    openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
      -keyout qz-private-key.pem -out qz-certificate.pem -subj "/CN=Your Business"
    Keep qz-private-key.pem secret: whoever has it can send jobs to every till that trusts the certificate.
  6. 6

    Give both to Posify

    Put both in .env, each on one line, with \n where the file has a line break, then restart Posify. Until both are set, Posify answers the till "QZ Tray is not configured", and the till prints through the browser.

    .env
    bash
    QZ_TRAY_CERTIFICATE="-----BEGIN CERTIFICATE-----\nMIID…\n-----END CERTIFICATE-----"
    QZ_TRAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE…\n-----END PRIVATE KEY-----"
    Print a .pem file as such a line
    bash
    awk 'NF { sub(/\r/, ""); printf "%s\\n", $0 }' qz-certificate.pem; echo
    Only people who may use the till (Use the POS) can fetch the certificate or have a job signed, and signing is rate-limited per person. All variables: Environment Variables.
  7. 7

    Install QZ Tray on each till computer

    Install QZ Tray from qz.io and start it. The first job asks whether to allow your site: allow it and tick Remember this decision.

    To skip that question altogether, have QZ Tray trust your certificate itself, as QZ Tray's own documentation describes for a self-generated certificate.
  8. 8

    Name the receipt printer

    Find printers, in the till's cash drawer set-up or in the label studio, lists the names QZ Tray reports. Type the receipt printer's name into Settings → Registers → (the register) → Receipt printer.

    Check: A sale prints straight to that printer, with no print dialog. If QZ Tray cannot print, the till opens the browser's print dialog instead.

  9. 9

    Set up the cash drawer

    The drawer plugs into the drawer port of the receipt printer. Posify opens it with the standard ESC/POS pulse, through QZ Tray, so QZ Tray must be set up on that computer.

    1. 1Settings → Point of sale → Open the cash drawer: on.
    2. 2Settings → Registers → (the register) → Cash drawer: on, for each register that has one.
    3. 3On that register's computer, open the till's Cash drawer dialog → Set up drawer printer: Find printers, choose the printer the drawer is plugged into, choose the Drawer pin (2 on most printers, 5 on some), press Test, then Save. This is kept on that computer; with nothing saved there, the till uses the register's receipt printer and pin 2.
    The till opens the drawer when cash changes hands (a sale or a balance paid in cash, a cash refund on a return) and on Cash in, Cash out and No sale. A drawer that does not open never stops a sale that has been taken.

    Check: Test opens the drawer. If it does not, the till says "The drawer did not open. Check the printer and QZ Tray."

  10. 10

    Print barcode labels

    Open the label studio from Products → All products (select products and choose Print labels, or Print labels on one row), from a product's page, or from the till, where Print labels prints labels for the items in the cart. Only products and variants with a barcode get a label.

    1. 1Print through the browser: works with any label printer that has a driver. The page is sized to the label in millimetres; print at actual size.
    2. 2Download ZPL or Download TSPL: saves the printer commands as a file, for a tool that sends files to the printer.
    3. 3Print to the thermal printer: sends the commands through QZ Tray to a printer chosen with Find printers.

ZPL and TSPL print plain Latin only

Any other letter (Bangla, Arabic, Chinese, accented letters) prints as ?. For names in other scripts, print through the browser.

TSPL assumes a 2 mm gap

For a roll with another gap between labels, calibrate the media on the printer.

How each label prints its barcode

In ZPL and TSPL, EAN-13 and UPC-A print as themselves and every other code as Code 128. Through the browser, a GTIN-14 prints as ITF-14. A barcode with a wrong check digit stops the print with a message naming the product.

Card terminals

Posify 1.0 does not connect to them. Card payments are taken on your own card reader and recorded at the till as Card, with an optional reference.

Customer-facing displays

Posify 1.0 does not drive a second screen facing the customer.

Weighing scales

Posify 1.0 does not read a scale. To sell by weight, give the product a unit with decimals (Products → Units: 3 decimals sells 0.250 kg) and type the weight as the quantity at the till.

KeyRequiredDescription
QZ_TRAY_CERTIFICATEOptionalThe certificate each till's QZ Tray trusts. PEM text on one line, with \n for each line break. Needed for receipts with no dialog, the cash drawer and direct label printing.
QZ_TRAY_PRIVATE_KEYOptionalThe key that signs the till's print jobs, in the same form. Keep it secret. Unset, receipts print through the browser's dialog and the drawer stays shut.

When QZ Tray fails, nothing is held up

Receipts open the browser's print dialog instead; the cash drawer stays shut; labels can still print through the browser or as a downloaded file. Find printers says "QZ Tray is not running on this computer" when the till cannot reach QZ Tray, or QZ Tray refuses the site: check the key, the certificate and Remember this decision.

Browser printing checklist

Choose the right printer in the dialog, print at Scale 100% (Actual size) with Margins None, and turn off Headers and footers. Calibrate a label printer's media and gap sensor before a long run.

Chapter 30 · Inventory

Stock per branch, at a moving average cost

Posify keeps the stock of every branch in a ledger. A sale, a return, a goods receipt, an adjustment, a transfer, a count and an opening import each write their movements to it, and nothing else changes a branch's figures. This chapter covers how stock is kept, each screen under Inventory, Settings → Inventory, and how stock reaches the books.

Read this first

Every change is a movement, and movements are never edited

Each product, or each variant of it, has one on-hand figure per branch; the catalogue total is the sum of the branches. A movement records how many units arrived or left, at which branch, when, why, by whom and from which document. A mistake is corrected by a later movement, an adjustment or a count.

  • All or nothing: a document and the stock it moves are saved together. If the shelf holds too little, nothing is saved and the screen names the short lines.
  • Saving twice moves stock once. If the connection drops after you press Save, pressing it again is answered with the first save. Change the form before trying again and Posify warns that an earlier try may have gone through: check the list first.
  • Each branch keeps a moving average cost per item. Units arriving at a known cost move the average; units leaving take it with them. Stock whose cost was never known is counted as unknown, never as 0.

Settings → Inventory

SettingWhat it doesNew business
Stock below zero in the back officeRefuse: an adjustment or a transfer that would take a level below zero is refused, while a stock count may always set what is really there. Allow: it goes through, shows negative and is reported until goods arrive or a count puts it right. The till keeps its own setting, Settings → Point of sale → Selling past zero stock.Refuse
Low stock atAn item is low at a branch when what is on hand falls to this or below, unless the branch, the variant or the product sets its own reorder point. People who may see stock are told when an item becomes low.10
Approve adjustmentsAdjustments made by someone whose role cannot approve wait for someone whose role can (Approve adjustments and counts). Stock does not move while they wait.Off
Approve stock countsA finished count waits for approval before its differences are applied.Off
Another person approvesWhoever made an adjustment or finished a count cannot approve it, even with the right to. A count waiting for approval is cancelled only by an approver, and only an approver imports opening stock.Off

These apply at every branch, so only someone who works at every branch changes them. The Manager role does not start with the Inventory settings permission, though a manager still approves adjustments and counts.

Adjustment reasons

ReasonDirection
Damaged, Expired, Lost, Theft, Internal useTakes stock out
FoundBrings stock in
Correction, OtherEither way

Two reasons are written by Posify itself: Stock count, when a count is applied, and Rejected on transfer, for units refused on arrival.

A transfer's statuses

StatusWhat it means
RequestedThe branch that needs the stock asked for it. The source approves it (it becomes Ready to ship and the units are set aside) or declines it with a reason; the asking end may withdraw it while it waits.
DraftBeing prepared. Nothing has moved.
Ready to shipCan go back to draft, be shipped or be cancelled.
In transitShip took the units out of the source. They are in nobody's on-hand figure; the destination's Stock list shows them as incoming.
CompletedEvery shipped unit was received or rejected, in one go or in parts.
CancelledBefore shipping, nothing moved. In transit, the units go back to the source at the cost they left with; refused once anything has been received.
DeclinedThe source refused the request.

The sender must work at the source branch and the receiver at the destination; either end sees the transfer.

The opening stock file

ColumnMeaning
sku or barcode (or code)The item. For a product with variants, the variant's own SKU or barcode.
location (or branch)The branch's code or name.
qtyUnits, above 0.
unit_costOptional. Absent, the item's own cost is used; with neither, the cost stays unknown.

Columns may come in any order and any case. Up to 2,000 rows and 5 MB; Download a sample shows the layout.

Stock in the books

DocumentPosts
Adjustment or count, units foundDr Inventory / Cr Inventory adjustments
Adjustment or count, units lostDr Inventory adjustments / Cr Inventory
Transfer (ship, receive, cancel)Nothing: one Inventory account serves every branch. Rejected units post as a stock adjustment.
Opening stockDr Inventory / Cr Opening balance equity, per branch

Units whose cost was never known book nothing, and the stock valuation report shows them apart. That report also shows units in transit as their own row, at the cost they shipped with, and counts them in its total.

Who may do what

PermissionAllows
See stockSee stock, movements, low stock, adjustments, transfers and counts, and export the Stock list.
Adjust stockMake adjustments, edit stock on the Stock list, set reorder points, import opening stock.
Transfer stockCreate, request, ship, receive and cancel transfers.
Count stockStart, count, finish and cancel counts.
Approve adjustments and countsApprove or reject adjustments and counts.
See costsSee cost and value on every inventory screen and file.

The preset roles: Administrator and Manager hold all six; Stock Keeper holds all but Approve adjustments and counts; Purchaser sees stock and costs. Everyone works only at the branches their account is given (Staff & Roles).

  1. 1

    Set the stock policies

    Settings → Inventory, the first table above: whether the back office may go below zero, the default low-stock point, and which changes wait for approval.

    Selling past zero at the till is decided elsewhere: per product (Sell below zero at the POS) or for every product in Settings → Point of sale. The back office follows Settings → Inventory.
  2. 2

    Bring in your opening stock

    Inventory → Opening stock → Choose a CSV file with what each branch holds when you start (the file table above). Preview checks every row, then Import writes them all at once.

    1. 1The import is all or nothing: one bad row and nothing is written. Fix the rows the preview lists and choose the file again.
    2. 2An item that already has movements at a branch is refused there: change it with an adjustment or a count.
    3. 3Importing the same file again with the same request changes nothing.
    4. 4It posts Inventory against Opening balance equity, per branch. Items with no cost are counted but not valued.

    Check: The preview says how many rows are ready and how many units, and Import reports the rows of opening stock imported.

  3. 3

    Check and correct stock on the Stock list

    Inventory → Stock lists every stocked item with its units at the chosen branch, or across your branches, and what is on its way: shipped transfers and open purchase orders.

    1. 1With a branch chosen, type a new figure in the Available column. Save sends the change as one adjustment (Correction), so a sale made since the page loaded is kept.
    2. 2Set reorder point gives the item its own low-stock point at that branch; Set bin location records where it sits, such as A-03.
    3. 3Export writes every row the filters give, not just the page on screen (up to 100,000 rows), with the value column only for someone who may see costs.
  4. 4

    Record an adjustment

    Inventory → Adjustments records units found or lost, with a reason from the table above. With Approve adjustments on, an adjustment by someone who cannot approve waits as pending and moves nothing until an approver presses Approve and apply.

    If the shelf no longer covers a pending adjustment when it is approved, the approval is refused and it stays pending.
  5. 5

    Move stock between branches

    Inventory → Transfers → Create transfer: choose From branch and To branch, add the items, then Save as draft, or Create, ready to ship.

    1. 1Ship transfer takes the units out of the source branch. They stop being available for sale there.
    2. 2At the destination, Receive items: Accept what arrived and Reject what is damaged or missing, in one go or in parts. Rejected units are written off at once as an adjustment.
    3. 3Cancel transfer before shipping moves nothing; in transit it brings the units back, until anything has been received.

    Check: The transfer reads Completed once every shipped unit is received or rejected.

  6. 6

    Ask another branch for stock

    Inventory → Transfers → Request stock, or Ask another branch on the till when an item is out. The source branch's senders hear of it in the bell and answer.

    1. 1Approve makes the request a transfer ready to ship, and sets the units aside for it: the Stock list shows them as Committed.
    2. 2Decline ends it with a reason, which the asking branch is told.
    3. 3The asking end may Withdraw request while it waits. Nothing moves stock until the transfer ships.
  7. 7

    Count the shelves

    Inventory → Stock counts → Start a count. A Full count puts every item the branch holds on the sheet, up to 5,000; a Partial count starts empty and fills as items are added or scanned. Several people may count one sheet at once.

    1. 1Click into the Scan box and scan: each scan counts one more unit of that item. The sheet walks the shelves in bin order.
    2. 2A line's expected figure is what the branch holds when the line is first counted. On approval, counted minus expected is applied as a change, so a sale rung up after the line was counted is kept, not undone. Lines nobody counted change nothing.
    3. 3An item may sit on only one open count of a branch at a time. Adding one another open count holds is refused and names that count: finish or cancel it first.
    4. 4Finish count applies the count at once as one adjustment (Stock count), or, with Approve stock counts on, waits for approval.
  8. 8

    Watch movements and low stock

    Inventory → Movements lists every movement, newest first, with the balance after each; Only sold below zero shows the oversold lines. Inventory → Low stock lists every item at or below its reorder point at its branch, worst first, with what is incoming and what is left to order.

    1. 1The reorder point is, in this order: the branch's own, the variant's, the product's, then Settings → Inventory. An item a branch has never stocked is not listed.
    2. 2Draft purchase orders makes one draft per supplier and branch for every listed item whose product has a default supplier, rounded up to the item's unit and priced at its cost. Nothing is sent, and pressing it again never orders twice.
    3. 3Adjustments, Transfers, Stock counts and Movements share the period picker: Today, Yesterday, Last 7 days, This month, All time or a custom range, in your business's days (Settings → General Settings → time zone).
    The daily low-stock digest (Settings → Notifications) lists the same items. A sale past zero sends an oversold alert once per item, branch and business day.

A kiosk sells from another branch's shelves

A branch with Hold stock here off keeps no figures of its own. Its Sells stock from branch is where its sales, returns and voids move stock, and its tills show that branch's figures; the sale and its takings stay the kiosk's. A kiosk that names no branch sells only services and items that keep no stock.

Below zero

The till may sell past zero when the product or Settings → Point of sale allows it; the back office only when Settings → Inventory allows it. A figure below zero shows as negative until a receipt or a count brings it back.

Batches and expiry

A product with Track batches and expiry is received with a batch number and expiry date. Sales take the batch that expires first, and expired batches are not sold unless someone with Sell from an expired batch allows it.

Bin locations

Each item may have one bin per branch, such as A-03 or Back store / Shelf 2. The Stock list sorts by it, and a count sheet walks the shelves in its order.

Changing a product that holds stock

Track stock off, or a change to a service or gift card, is refused while a branch holds any, a transfer carrying it is in transit, or it sits on an open count or an unshipped transfer. Archiving is refused while a branch holds any or a transfer is in transit. Removing a variant, adding variants, or a unit with fewer decimals is refused once the product has history that names it.

Transfers post nothing in the books

All branches share one Inventory account, so a transfer does not change the business's stock value. A branch's Inventory balance is then what it received and sold, not its shelf value after transfers; the business total is right. The books check counts units in transit at their shipped cost (Accounting).

Bring stock to zero before changing what a product is

Bring the stock to zero with an adjustment or a count, and finish or cancel the open counts and transfers, before switching tracking off, archiving the product or changing its variants.

Chapter 31 · Invoice Templates

Design the receipt and the sale invoice

Settings → Invoice templates designs what Posify prints for a sale: the till's receipt, and the sale invoice printed from a sale's page. Each has its own templates, and the one set as its default is what prints. Without a default, the till prints its standard receipt and the sale page keeps its own print, so nothing changes until you choose.

How it fits together

Two tabs, one default each

The page has two tabs, POS receipt and Sale invoice. A template belongs to one of them, and the tab's default is what prints. The line above the cards says which: Prints with "…", or Prints the standard design: "…".

  • POS receipt: printed by the till after a sale, when a sale is reprinted, and offline. The default travels in each register's snapshot, so an offline receipt prints the same way. A receipt template over 64 KB is not carried, and the till prints its standard receipt.
  • Sale invoice: printed from a sale's page with Print invoice, which shows only while the Sale invoice tab has a default.
  • Product labels are not designed here: they come from the label studio (Hardware).

Before you start

  • The Receipt settings permission: it opens Settings → Invoice templates, the editor and the preview.
  • To save, an account that works at every branch: templates apply at every branch. An account limited to some branches can open, edit and test print, but Save is off for it.
  • Your business details, logo, and each branch's address and receipt lines in place (Settings → General Settings, Settings → Branding, Settings → Receipt, Settings → Branches). The business and branch fields of a template print them.

Presets

PresetTabPaperWhat it looks like
Standard receiptPOS receiptThermal 80 mmToday's till receipt as a template: business, sale details, lines, totals, payments, barcode
Compact thermalPOS receiptThermal 80 mmA dense receipt with the totals, payments and a QR code of the sale number
Thermal 58 mmPOS receiptThermal 58 mmThe compact receipt on a narrow roll
Standard invoiceSale invoiceA4 portraitBusiness and customer side by side, lines with SKU and discount, totals, payments, signature
MinimalSale invoiceA4 portraitThin rules and white space
PremiumSale invoiceA4 portraitA coloured header band and boxed sections
Compact A5Sale invoiceA5 landscapeA dense page for small printers
US Letter invoiceSale invoiceUS LetterThe standard invoice on US Letter paper

The two Built-in cards, Standard receipt and Standard invoice, are what each tab prints while no template is its default. A preset's Set as default saves it as a template first; the Built-in card's Set as default removes the template default, so the standard design prints again.

Paper sizes

SizeWidth × heightPage length
A4 portrait210 × 297 mmFixed page
A4 landscape297 × 210 mmFixed page
A5 portrait148 × 210 mmFixed page
A5 landscape210 × 148 mmFixed page
US Letter215.9 × 279.4 mmFixed page
Thermal 80 mm80 mm rollGrows with content (roll)
Thermal 58 mm58 mm rollGrows with content (roll)
Custom sizeWidth 20–500 mm, height 20–1000 mmFixed page or roll

A new receipt template starts on Thermal 80 mm, a new invoice on A4 portrait. A roll grows with the sale and never prints shorter than its Shortest print.

Smart blocks

BlockWhat it prints
Business headerBusiness name, logo, address and phone
CustomerThe customer's name, phone and address
Sale summarySale number and date
Product tableName, SKU, qty, unit price and line total; continues across pages
Price summarySubtotal, discount, tax, total, payments, change and due; last page
BarcodeThe sale number
QR codeThe sale number
NotesThe sale's note
DividerA rule across the printable width
LogoThe business logo
Product rowsName, SKU and qty in compact rows; continues across pages

Smart blocks fill themselves from the sale; each has its own settings in the Properties panel.

Basic elements

ElementWhat it prints
TextFixed text, the same on every print, or a data field from the sale
ImageA picture of your own
BarcodeA fixed value you type, in Code 128, EAN-13 or UPC-A
QRA web address you type
LineA horizontal line
BoxA box with a thin border
ProductsName, qty and total, plain

Data a text can print

GroupFields
SaleSale number, Date, Payment status, Payment method, Cashier, Register, Sale channel, Sale note, Provisional number note, Tax exemption reason
CustomerCustomer name, Customer phone, Customer email, Customer address, Tax ID
AmountsSubtotal, Discount, Tax, Rounding, Total, Paid, Change, Balance due, Returned
ProductsAll product names, Number of lines, Total units
BusinessBusiness name, Business phone, Business email, Business address, Tax number, Logo
BranchBranch, Branch code, Receipt header, Receipt footer
PagePage number, Page count, Page label
Product lineItem, Variant, SKU, Barcode, Qty, Unit, Unit price, Amount, Discount, Total, Tax %, Image, Line note

A field a tab never has data for prints nothing there, and Review says so. A product table's columns pick from the Product line fields.

  1. 1

    Open the manager

    Settings → Invoice templates. Each tab lists, in order: a blank page (Start blank), the Built-in standard design, your saved templates, then the presets none of them was made from. Each card has Edit and Preview, and its menu holds the rest.

    Check: The line above the cards reads Prints the standard design: "Standard receipt" on a new business.

  2. 2

    Start a template

    New template (or Start blank) opens a blank page in the open tab. On a preset card, Edit opens it as an unsaved draft, and Save as template in its menu saves it under the first free name. Nothing is created until you first press Save template.

    1. 1A new template is made in your own language, and the words Posify adds when printing (labels, statuses, Page 1 of 3) follow that language.
    2. 2A tab holds at most 50 templates, and a template at most 300 elements.
    3. 3A template's name is unique within its tab, up to 80 characters.
    Where the pages are
    txt
    /settings/invoices?category=receipt          # the manager, POS receipt tab
    /settings/invoices?category=invoice          # the Sale invoice tab
    /invoice-templates/new?category=receipt      # a new, unsaved receipt template
    /invoice-templates/new?category=invoice&preset=minimal
    /invoice-templates/<id>/edit                 # a saved template in the editor
    /invoice-templates/preview?id=<id>           # preview a saved template
  3. 3

    Set up the page

    The right panel has three tabs: Design, Layers and Review. With nothing selected, Design shows the page: the paper and the template-wide look. The toolbar's Paper size menu switches size; Custom size… takes a width and height in millimetres, and elements stay where they are.

    Page length
    Fixed page, or Grows with content (roll) with a Shortest print.
    Margins
    Top, Right, Bottom and Left, in mm.
    Snap grid
    1, 2 or 5 mm.
    Background, Default font
    Fonts include Clean Sans, Compact Thermal, Elegant Serif, Bangla Friendly and Noto Sans Bengali.
    Amounts
    With the currency ($3,150.00), Plain (3150) or Two decimals (3150.00), and an optional text After every amount, such as /=.
    Dates
    d MMM yyyy, dd/MM/yy, dd/MM/yyyy, M/d/yyyy or yyyy-MM-dd.
    Digits
    Latin (123), Bangla (১২৩) or Arabic (١٢٣).
  4. 4

    Add and arrange elements

    Add to canvas: click an item to add it in the middle of the view, or drag it onto the page. Select an element and the Design tab sets its Position & size, Rotation and Prints on (Every page, First page, Last page, or Every page but the first), its content and its style.

    1. 1Arrange, above the canvas: Align to the page or the selection, Distribute three or more, Layer order, Duplicate, Lock, Hide and Delete.
    2. 2The Layers tab lists every element; the top of the list prints on top. Drag a row to change the order.
    3. 3Keys: arrows nudge by 1 mm (Shift: 10 mm), Delete removes, Ctrl + D duplicates, Esc deselects, Ctrl + Z undoes and Ctrl + Shift + Z redoes.
    4. 4Pages switches the canvas between Single page and First, middle and last pages, to see how a long sale flows.
  5. 5

    Fill a text from the sale

    A text element's Content asks "What should this show?": Fixed text, printed the same on every sale, or Data field, filled in from the sale (the last table above). A data field can have Text before, Text after, and what to print If empty; a Sample shows what it prints for the sample sale.

    Style changes the look only, from five style presets (Minimal, Bold, Premium, Compact, Thermal); the text, data field and settings stay as they are.
  6. 6

    Clear the warnings

    The toolbar's warnings button opens Review and selects the first thing to look at; press it again for the next. Review lists elements outside the printable area, elements that overlap, fields a tab never has data for, barcodes that cannot encode their value or are too narrow to scan, QR codes under a size a phone can scan, and text that does not fit its box even at 6 px.

    Check: Review says "Nothing to fix: everything is inside the page, nothing overlaps, and the codes can be drawn."

  7. 7

    Preview with sample data or a real sale

    The Review tab holds a live preview, and Preview on a card opens the full Template preview page. Show Sample data, choosing how many products the sample sale has, or A real sale: type its number (such as SAL-000123) and press Load. Previewing reads the sale and never changes it, and shows only sales within your branches.

  8. 8

    Print a test page

    Test print prints the template as it is now, at real size, through the browser. Nothing is saved.

    In the print dialog choose Scale 100% (Actual size), Margins None, and turn off Headers and footers, so the paper matches the template.
  9. 9

    Save and set as default

    Save template stores it. More save options, beside it, holds Save as… (a copy under a new name, leaving the saved one as it was) and Save & set as default. On the manager, Set as default and Remove default do the same from a card.

    1. 1If someone else saved the template after you opened it, Posify asks you to Reload (your changes here are lost) or Overwrite.
    2. 2Leaving with unsaved changes asks first. The browser keeps a copy, offered as Unsaved changes found → Restore them the next time you open the template.

    Check: The template's card shows Default, and the line above the cards reads Prints with "…" and its name.

  10. 10

    Look after your templates

    A card's menu holds Rename, Duplicate, Remove default, Restore preset and Delete.

    1. 1Restore preset puts the preset's layout back; the template keeps its name and default.
    2. 2Deleting the default makes the tab print the standard design again. It cannot be undone.
    3. 3Reset, in the editor, offers Discard unsaved changes, Restore preset layout or Reset styles only. You can undo it, and nothing is saved until you press Save.

The till never fails to print

If the receipt template cannot print (its fonts not ready within 4 seconds, a drawing error), the till prints the standard receipt and says "The receipt template couldn't print, so the standard receipt was printed." A failed invoice prints the sale page instead. A receipt template prints to the register's QZ printer, else the browser's dialog.

Long sales flow across pages

Product table and Product rows continue across pages, and each element prints on the pages you chose. A sale that would need more than 500 pages leaves the rest of its lines out, and the preview says so.

Any of the app's languages

A template prints in its own language, whichever the till or the reader uses, and in Latin, Bangla or Arabic-Indic digits. The preview shows the Template language.

Read-only for some accounts

In demo mode, and for an account limited to some branches, the manager switches off whatever writes: Edit, Preview and Test print keep working, and Save is off.

A receipt template still reads Settings → Receipt

With a receipt template as the default, the template decides the layout and the paper. The logo, business details, header and footer it prints still come from Settings → Receipt and the sale's branch, as the standard receipt's do.

Start from a preset

Open the preset closest to what you want, save it as a template, then change what differs. Restore preset is always there if the design drifts too far.

Chapter 32 · Accounting

The books: journals, statements and month-end

Posify keeps a double-entry ledger beside the shop. Every sale, return, purchase, payment, expense and stock change posts its own journal when it is saved, so nobody posts anything by hand to keep the books current. This chapter covers the chart of accounts, Settings → Accounting, what each document posts, opening figures, money in and out, closing a month and checking the books.

Read this first

Journals are never edited or deleted

A journal is a set of debit and credit lines that must balance to the smallest unit of your currency; one that does not is refused. Journals are append-only: a mistake is corrected by a document (a return, a void, a reversed receipt, a corrected expense), and a journal typed by hand is corrected by reversing it.

  • One currency, one clock: the books are kept in the currency and time zone of Settings → General Settings. Once a journal is posted the currency can no longer change, and while a month is closed the time zone cannot change either.
  • Posting never holds up the counter. If a journal cannot be posted, the document still stands and the posting waits under Accounting → Books check → Postings waiting, retried by the accounting-recoveries job every 15 minutes (Background Jobs).
  • Every line carries its document's branch, so each statement reads for one branch or the whole business.

Before you start

  • Settings → General Settings: the currency, the time zone, and Financial year and tax (Financial year starts in, On day), set before the first sale.
  • The background jobs scheduled: accounting-reconcile (daily, 02:15), accounting-recoveries (every 15 minutes) and recurring-expenses (hourly) (Background Jobs).
  • For PDF downloads, Chrome or Chromium on the server (Requirements). CSV works without it.

System accounts

CodeNameTypeWhat it holds
1000Cash on handAssetCash in the drawers, for every branch without a cash account of its own
1050Cash in transitAssetCash put into or taken out of a drawer, until it is banked, spent or put back
1100BankAssetCard, bank transfer and Other payments, unless Settings → Accounting names other accounts
1200Accounts receivableAssetWhat customers owe: credit sales, deposit balances, opening dues
1300InventoryAssetStock, at its moving average cost
1400Input tax receivableAssetTax on supplier bills
1500Supplier advancesAssetMoney paid to suppliers that no bill has taken yet
1600Inter-branch balancesAssetWhat the branches owe one another; 0 across the business
1700Fixed assetsAssetWhat the business's fixed assets cost
1750Accumulated depreciationAssetWhat has been written off fixed assets so far
2000Accounts payableLiabilitySupplier bills and opening dues still to pay, and expenses entered as unpaid
2100Goods received not billedLiabilityGoods received whose supplier bill is not entered yet
2200Output tax payableLiabilityTax charged on sales, less returns
2250Withholding tax payableLiabilityTax held back from supplier payments, owed to the tax office
2300Store credit payableLiabilityStore credit customers hold
2400Gift card liabilityLiabilityWhat is left on gift cards sold, issued or imported
2500Loyalty points liabilityLiabilityPoints customers hold, at their value when earned
2600Customer advancesLiabilityMoney from a customer no due has taken yet, and exchange credit not yet spent
2700Loans payableLiabilityWhat the business still owes on loans it took
3000Owner's equityEquityMoney the owner put in, and your own entries
3100Opening balance equityEquityThe other side of opening balances, opening dues and opening stock
3200Retained earningsEquityNo document posts to it (see the balance sheet below)
3300Owner's drawingsEquityMoney the owner took out for themselves
4000Sales revenueIncomeSales before discounts, net of tax; never gift cards
4100Sales returnsIncomeGoods taken back, at their price before discount
4200Discounts givenIncomeLine and sale discounts
4900Other incomeIncomeExpired store credit; a voided gift card's balance when no customer bought it
4910Gift card breakageIncomeWhat expired gift cards still held, only while breakage is switched on
4950Gain or loss on assets soldIncomeA fixed asset sold or scrapped above or below its book value
5000Cost of goods soldExpenseWhat the units sold cost
5100Inventory adjustmentsExpenseStock found or lost: adjustments and stock counts
5200Purchase price varianceExpenseA bill's price above (or below) the cost the goods were received at
6000Operating expensesExpenseCharges on supplier bills; the parent of the default expense categories
6100Loyalty rewardsExpenseThe value of points earned
6150Customer goodwillExpenseStore credit given by hand
6160Gift cards given awayExpenseGift cards issued from the back office with nothing paid
6200Bank chargesExpenseAn expense category for bank fees
6300Cash over and shortExpenseWhat a drawer count found over or short
6400Rounding differencesExpenseCash rounding and rounding leftovers
6500DepreciationExpenseThe month's share of what fixed assets cost
6600Bad debts and discounts allowedExpenseWhat customers owed that the business wrote off
6700Interest expenseExpenseThe interest part of a loan repayment

These exist in every installation, because the posting rules name them. Code and name are defaults you may change; type and kind never change, and they cannot be deactivated. Sales returns, Discounts given, Accumulated depreciation and Owner's drawings read below zero: they reduce the figure above them.

Settings → Accounting

SettingWhat it decidesUnset
Accountant tools in the menuWhether the sidebar offers Journals, Chart of accounts, General ledger, Trial balance, Fixed assets, Books check and Fiscal periods. Off, the statements and Money in and out stay, the books still keep themselves, and the pages still open from a link.On
Each branch's cashThe cash account a branch's tills take, give back and count in.Cash on hand (1000)
Default bank accountWhere bank money lands when nothing else is named.Bank (1100)
Card paymentsWhere card payments land.The default bank
Bank transfersWhere bank transfer payments land.The default bank
Other paymentsWhere Other payments land, such as a cheque or a wallet. They go to the bank, not the drawer, because the drawer is counted in cash only.The default bank

A branch's cash must be an active account of kind Cash, the default bank one of kind Bank, and a payment's account one of kind Cash or Bank: add them first in the chart or under Cash and bank. A change applies to what is posted from then on, since a receipt or payment stores the account it used. These apply at every branch, so an account limited to some branches can read them but not change them.

What posts what

EventDebitCredit
Sale, at the till or in the back officeEach payment's account (cash: the branch's cash; card, bank transfer, Other: their accounts; store credit, points, gift card: their liability); Accounts receivable for what is still owed; Discounts given; Cost of goods soldSales revenue, net of tax; Gift card liability for cards sold; Output tax payable; Inventory, at cost; Rounding differences when cash rounding took more
Balance collected at the tillEach payment's accountAccounts receivable
ReturnSales returns; Output tax payable; Inventory for units back on the shelf; Gift card liability for a card taken backDiscounts given (those goods' share); Accounts receivable first; the balances paid with; the refund's account; Cost of goods sold
Cash inThe branch's cashCash in transit
Cash outCash in transitThe branch's cash
Drawer closed overThat payment's accountCash over and short
Drawer closed shortCash over and shortThat payment's account
Goods receivedInventory, net of taxGoods received not billed
Supplier billGoods received not billed; Purchase price variance; Operating expenses for charges; Input tax receivableAccounts payable
Supplier paymentAccounts payable for each bill it pays; Supplier advances for the restThe account it was paid from
Purchase returnGoods received not billed for unbilled units; Accounts payable for billed onesInventory; Input tax receivable; Purchase price variance
Stock foundInventoryInventory adjustments
Stock lostInventory adjustmentsInventory
Opening stockInventory, per branchOpening balance equity
Transfer between branchesNothing is posted—
Stock true-upCost of goods sold when stock sold past zero is worth less than booked; Inventory when worth moreThe other one
Customer receiptThe account it came intoAccounts receivable for each due it pays; Customer advances for the rest
Customer write-offBad debts and discounts allowedAccounts receivable
Expense, paidIts category's accountThe account it was paid from
Expense, not paid yetIts category's accountAccounts payable, until Mark as paid
Fund transferThe account the money went toThe account it left
Opening balance of an assetThe accountOpening balance equity
Opening balance of a liability or equityOpening balance equityThe account
Opening due, a customer'sAccounts receivableOpening balance equity
Opening due, a supplier'sOpening balance equityAccounts payable
Owner put money inThe cash or bank accountOwner's equity
Owner took money outOwner's drawingsThe cash or bank account
Loan receivedThe cash or bank accountLoans payable
Loan repaymentLoans payable for the principal; Interest expense for the interestThe cash or bank account
Fixed asset enteredIts asset account, at costThe account it was paid from, or Opening balance equity when already owned
Monthly depreciationDepreciationAccumulated depreciation

A summary: Dr is the debit side, Cr the credit side. Any document reversed or voided posts the exact reverse, dated as the next table says. Loyalty points, store credit and gift cards have their own table in Loyalty & Gift Cards.

How corrections are dated

CorrectionDated
A sale voidedWhen it was voided
A returnWhen the goods came back
A customer receipt, supplier payment or fund transfer reversedWhen it was reversed
An opening balance or opening due reversedWith its own date, so a report between the two never counts both figures
An expense corrected, its payment undone, or the expense voidedWith the expense's own date, so its month is restated
A manual journal reversedWith the journal it reverses

A journal is dated when its event happened: the sale's time, the day goods arrived, the bill's date. Any journal whose date falls in a closed month is posted on the first day still open instead.

Statements and where they are

StatementWhereShows
Trial balanceAccounting → Trial balanceEvery account's debit, credit and balance as of a day; one branch, or each branch apart
General ledgerAccounting → General ledgerOne account's lines between two days: brought forward, each line with its running balance and a link to its document, carried forward
Profit and lossStatements → Profit and lossNet sales, cost of sales, gross profit and Gross margin, operating expenses, operating profit, other income and expenses, Net profit; a % of sales column
Balance sheetStatements → Balance sheetAssets, liabilities and equity as of a day, with Retained earnings (earlier years) worked out each time and Profit for this financial year beside it; checks that assets equal liabilities plus equity
Cash flowStatements → Cash flowWhere cash came from and went: operating activities (net profit, charges that were not cash put back, day-to-day balances), investing (fixed assets bought and sold), financing (the owner and loans); ties to the cash book
Changes in equityStatements → Changes in equityEquity at the start, the period's net profit, money the owner put in and took out, opening balances recorded, and equity at the end, which is the balance sheet's total equity
Cash bookStatements → Cash bookEvery cash and bank account, and Cash in transit once used: brought forward, money in, money out, carried forward; Open the book for one account line by line
Expenses by categoryStatements → Expenses by categoryEvery line posted to an expense account, nested under its parent, with each category's share; Include cost of sales adds the cost-of-sales accounts
Tax reportStatements → Tax reportOutput and input tax by month and rate, a Not by rate line, tax-exempt sales, and the net payable or reclaimable (Tax)
Receivables, PayablesMoney in and outThe agings: customers by days since the sale (0–30, 31–60, 61–90, over 90), open bills by days past due
Customer and supplier statementsThe Statement tab of a customer or supplierEvery sale or bill, payment, return, reversal, void, refund and opening due, with a running balance

The trial balance, the general ledger and the statements are read from the journals, so they agree with each other to the cent. The agings and the customer and supplier statements are read from the documents; the books check compares the two. All reports → Money owed and statements links to them too.

Who may do what

To…Permission
See the journals, ledger, trial balance, chart and books checkSee the books
Read the statementsSee the books, or Financial reports
Read the tax reportSee the books, or Tax reports
Add or change accountsManage the chart of accounts, and see every branch
Post or reverse a manual journal; opening balances and opening dues; Post now; bank reconciliationPost journal entries
Close or reopen a monthClose financial periods, and see every branch
Record expensesRecord expenses
Move money between cash and bank accountsMove money between cash and bank accounts
Reverse receipts, payments, transfers and goods received; void bills and expensesReverse payments, receipts, transfers and goods received; void bills and expenses
Write off what a customer owesWrite off what customers owe
Take a customer receiptTake payments against dues
Take a return's credit off a bill; record money a supplier paid backPay suppliers
Change Settings → AccountingAccounting, in the Settings group

Permission names as they appear in Staff → Roles. The Accountant and External Accountant roles start with every accounting permission and the Accounting settings; a Manager starts with See the books, Record expenses and Move money between cash and bank accounts.

  1. 1

    Check the chart of accounts

    Accounting → Chart of accounts lists every account by type, with its balance as of today; click a name to open its ledger. Add account creates one of your own: a code, a name, its type (Assets, Liabilities, Equity, Income, Expenses), its kind, and optionally the account it sits under and a description. Add bank account is a shortcut.

    1. 1Codes are unique. An account sits under an active account of the same type, at most three levels deep, and its type decides where it shows in the statements.
    2. 2Your own account's type and kind change only until a journal names it, and only while Settings → Accounting does not use it.
    3. 3Deactivate takes an account out of the pickers; its journals stay. It is refused while the account holds a balance, has active accounts under it, or is used in Settings → Accounting. Show deactivated lists them, and Activate brings one back.
    4. 4Expense categories are accounts too: the defaults (Rent & utilities, Salaries & wages, Marketing & advertising and others, codes 6010–6099) sit under Operating expenses.
    Nothing is ever deleted from the chart. Only a person who sees every branch can add or change accounts.
  2. 2

    Point the tills at your accounts

    Settings → Accounting, the second table above. Leave everything unset to use the system's Cash on hand and Bank, or add a cash account per branch and your real bank accounts first, then choose them here.

  3. 3

    Enter what the business held on day one

    Moving from another system? Money in and out → Cash and bank → Opening balances → Add opening balance, one per account. Each posts against Opening balance equity.

    Day
    The day the books start here.
    Account
    An asset, liability or equity account. Income and expense accounts start at zero.
    Amount
    On the account's usual side: what a cash or bank account held, what a loan still owed. Below zero means the other side, such as an overdrawn bank.
    Branch, Note
    Optional.
    Accounts that a list of documents keeps are refused here, because their documents are the figure: customers' dues, suppliers' payables, goods received not billed, stock, gift cards, points, store credit and both kinds of advances. An opening balance is never edited: reverse it with a reason and enter it again. The cash in a drawer's float is entered here too, on the branch's cash account: opening a drawer posts nothing.
  4. 4

    Bring in what customers and suppliers owed

    Enter each old balance as an opening due: one at a time from the customer's or supplier's Statement tab → Add opening due (the branch, the day, the amount, and optionally a due date and a reference), or many at once from Money in and out → Receivables or Payables → Import opening dues.

    1. 1The file's columns: Name, Phone, Email (and Code for suppliers), Amount, As of, Due date, Branch, Reference, Note. Amounts are plain numbers, 1200.50, not 1,200.50.
    2. 2A row finds its customer or supplier by email, then phone (a supplier's code first), then by a name only one of them has. The import creates nobody: add them first.
    3. 3It shows a preview and writes nothing until you confirm.
    4. 4Receipts and supplier payments pay opening dues like any other due, oldest first. A customer's opening due counts against their credit limit.
    An opening due is never edited, and can be reversed only while nothing has paid any of it. Stock comes in through Inventory → Opening stock (Inventory).
  5. 5

    Record customer receipts

    Money in and out → Customer receipts → Receive payment records money a customer paid toward what they owe. It pays credit sales and opening dues, oldest first or as you choose; money no due takes is kept as the customer's advance, and Apply advance sets it against a later due. At the till, Receive due does the same into the open drawer.

    1. 1A deposit's balance is not paid by a receipt: it is collected at the till, where paying it hands the goods over.
    2. 2A receipt is never edited. Reverse receipt, with a reason, undoes it, dated the day you reverse it; a sale a receipt paid cannot be voided until then.
    3. 3Write off, on a customer's Statement tab, gives up a due that will never be paid and posts it to Bad debts and discounts allowed.
  6. 6

    Record expenses

    Money in and out → Expenses → Record expense enters a cost no sale or purchase records: rent, salaries, advertising. Each expense has a category, and a category is an expense account; New category adds one.

    1. 1Paid now: choose the account it was paid from. Not paid yet: it is owed and shows under Payables as an unpaid expense until Mark as paid, dated the day the money left.
    2. 2Repeats records the expense again by itself on each day it falls due, through the hourly recurring-expenses job.
    3. 3Editing an expense's money reverses the old version on its own date and posts the new one; voiding reverses everything it posted.
    A cash account pays out only what the books say it holds: an expense, a bill marked as paid or a transfer that would take it below zero is refused, naming the account and its balance. Someone with Post journal entries is offered Record anyway. A bank account may be overdrawn.
  7. 7

    Move money and clear Cash in transit

    Money in and out → Cash and bank shows each cash and bank account with its balance, with Add bank account, Add cash account and Transfer money. A transfer is reversed, never edited.

    1. 1Cash a cashier put in or took out sits in Cash in transit until you say where it went.
    2. 2Banked: Transfer money from Cash in transit to the bank.
    3. 3Spent on a paid-out: record an expense paid from Cash in transit.
    4. 4Put back: Transfer money from Cash in transit to the branch's cash.
    A cash account belongs to a branch, and its money moves on that branch's books whichever branch the document names. A person limited to some branches is offered only their branches' cash, besides the bank accounts and Cash in transit.
  8. 8

    Close a month

    Accounting → Fiscal periods → Close a month. Only a month that has ended can be closed, and only one after the last close; closing it also closes every earlier month still open. Months follow the business's own clock.

    1. 1Before it closes, the month is checked: postings waiting, documents dated since the last close whose journal is missing or cannot be posted, and the trial balance at the month's end. Fix these first (Accounting → Books check), or choose Close anyway and say why.
    2. 2The close keeps a snapshot: the trial balance at the month's end, the month's income, expenses, net result and number of journals, and your note.
    3. 3Afterwards, a document dated in the closed month is still accepted; its journal posts on the first day still open, marked with the month it belongs to. A manual journal dated in it is refused.
    4. 4Reopen undoes only the latest close. Journals moved out of the month while it was closed stay where they were posted.
    Closing and reopening need Close financial periods and a person who sees every branch. A person limited to some branches sees the dates of closes but not their figures.
  9. 9

    Post a manual journal

    Accounting → Journals → New journal posts a journal typed by hand: an accrual, a correction, a loan repayment, tax paid to the tax office. Reverse, on the journal's page, posts its mirror once, dated like the original.

    1. 1Say what it is for: the memo is required.
    2. 2At least two lines and at most 100; each line a debit or a credit, not both; every account active. The form shows "Out of balance by …" until debits equal credits.
    3. 3The date must be after the last closed month. A date after today is allowed, with a warning.
    4. 4A person limited to some branches names one of their branches on every line.
    5. 5Refused accounts, because their documents are the figure: Accounts receivable, Accounts payable, Goods received not billed, Inventory, Gift card liability, Loyalty points liability, Store credit payable, Customer advances and Supplier advances.
    A journal on a tax account counts in the tax report too, under Not by rate. Only journals typed by hand are reversed here; an automatic journal is corrected through its document.
  10. 10

    Read the statements

    The statements table above says where each one is. Periods: This month, Last month, This quarter, Last quarter, This financial year, Last financial year, or custom dates; the balance sheet takes Today, End of last month, End of last quarter or End of last financial year.

    1. 1Columns: Total only; Each branch (profit and loss, expenses); Each month, up to 24 months; Compared with the period before; Compared with a year earlier.
    2. 2The financial year starts on the day set in Settings → General Settings → Financial year and tax, and quarters keep that day: a year starting on 6 April has quarters starting 6 April, 6 July, 6 October and 6 January.
    3. 3Posify 1.0 posts no year-end closing journal: the balance sheet works out Retained earnings (earlier years) from the journals each time.
    4. 4A person limited to some branches sees only their branches' lines, with a note saying so; their figures need not balance on their own.
  11. 11

    Run the books check

    Accounting → Books check answers one question: do the journals still say what the documents behind them say? It first names any background job the books depend on that is not running, then shows the trial balance, Postings waiting (with Post now), What needs a look, Closed months and Control accounts.

    1. 1Check the documents replays every document through the posting rules and lists journals missing, journals that differ, journals a document no longer posts, and documents that cannot be posted. It stops on a time limit and says so.
    2. 2Each finding says how it is fixed: Post it, Rebuild the kind, or Review by hand.
    3. 3Control accounts compares each account that stands for a list of balances with that list: Inventory with the stock valuation; the gift card, points and store credit liabilities with what customers hold; receivables, payables and advances with their documents.
    It reads every branch, so it needs See the books and a person who sees the whole business. Every night the accounting-reconcile job posts anything missing and retries what waits; when something needs a look, everyone with Post journal entries gets "The books need a look" in the bell, once a day.
  12. 12

    Reconcile from the server

    The same check from the command line, run from the app's folder. It posts what is missing and never posts anything twice. Run the dry run first; if it exits with code 2, run it without --dry-run, and if it still exits 2, open Accounting → Books check. Every option, exit code and the rebuild: Backups & Recovery.

    bash
    pnpm accounting:reconcile --dry-run   # report only, write nothing
    pnpm accounting:reconcile             # post what is missing

Fixed assets

Accounting → Fixed assets → New asset enters something the business keeps for years: its cost, Useful life (years), Worth at the end, and how it came, bought from a cash or bank account or already owned when the books began. It is written off in equal monthly shares by the nightly books job; Sold or scrapped books the gain or loss, and Void reverses every journal it posted.

Bank reconciliation

Money in and out → Bank reconciliation: start a statement with its date and balance (Start ticking), tick each line of the bank's statement against the books until the difference is zero, then Finish. A bank charge the books lack is posted first with New journal. It needs Post journal entries and a person who sees the whole business.

Owner's money and loans

Money in and out → Owner's money and loans records Owner put money in and Owner took money out (equity, never income or expense), and Record a loan with each repayment: the principal lowers the loan, the interest is an expense. Each is reversed, never edited.

Tax settlements

Optional, on the tax report: Settle tax records what you paid the tax office for a period, or got back, so the tax accounts read zero for it. The tax report itself is not a tax return; it gives the totals for your accountant (Tax).

One currency

No report converts between currencies. A journal kept in a currency other than the books' is listed by the books check under What needs a look.

CSV and PDF

Every statement, both agings, the party statements, the trial balance, a general ledger and the journal list download as CSV or PDF, in the reader's language, up to 20,000 rows a file. Text starting with =, +, - or @ gets a leading ' in a CSV so a spreadsheet never runs it. PDF needs Chrome or Chromium on the server (or CHROME_PATH); the prebuilt Docker image does not include it (Docker Image).

Set the currency and time zone before the first sale

Once a journal is posted the currency can no longer change, and while a month is closed the time zone cannot change either: moved, a journal posted after the close could file under a day of the closed month.

After an upgrade or a restore

Run pnpm accounting:reconcile --dry-run before anything else. It reports what the books lack and writes nothing (Backups & Recovery, Updates & Migrations).

Chapter 33 · Loyalty & Gift Cards

Loyalty points, store credit and gift cards

A customer can hold value with your business in three ways: loyalty points earned on what they buy, store credit on their account, and gift cards that whoever holds the code can spend. All three live on the server and are used online only. All three are liabilities in the books: money the business owes until it is spent.

Read this first

Points and gift cards need two switches each

One switch runs the programme; the other lets the till take it as a payment. Store credit needs no programme switch: a customer has it as soon as someone gives them some.

  • Points are booked at what they are worth when they are earned, and Posify 1.0 does not expire them.
  • Gift card codes are handed over once. Showing one again, or setting a new PIN, is a separate permission that only the Administrator holds to begin with.

Switching them on

To…Switch on
Earn loyalty pointsSettings → Loyalty → Loyalty points
Pay with points, at the till or on a back-office saleAlso Settings → Payments → Loyalty points
Sell gift cards at the tillSettings → Gift cards → Sell and reload gift cards, and a product of kind Gift card
Pay with a gift cardSettings → Gift cards → Accept gift cards as payment (on unless switched off), and Settings → Payments → Gift card
Pay with store creditSettings → Payments → Store credit

Settings → Loyalty

SettingWhat it meansNew business
Loyalty pointsSales to a customer earn points, which they can spend at the till.Off
Points back on all productsThe share of what the customer pays that comes back as points (0–100%), after discounts and before tax. A product or a category can give its own %; this is for the rest.1%
Rounding of earned pointsPoints are whole: Round down, or Round to nearest.Round down
Value of one pointWhat one point pays at the till.0.01
Fewest points spent at onceA customer spends at least this many at a time. 0 sets no minimum.100
Largest share of a sale paid in pointsPoints pay at most this share of a sale (1–100%). 100% lets them pay all of it.50%
Services earn pointsOn, services earn at the all-products %. Off, they earn none unless they or their category give a % of their own. Gift cards never earn.On
TiersName, From (lifetime points) and Multiplier; at most 10.Bronze, Silver, Gold, Platinum

The tab shows a live example of the settings; with the defaults it reads "A sale of 100.00 earns 100 points; 1000 points pay 10.00". The expiry of store credit from returns is on Settings → Payments.

Settings → Gift cards

SettingWhat it meansNew business
Sell and reload gift cardsThe till sells new cards and tops up old ones.Off
Accept gift cards as paymentThe till takes cards as payment, with Settings → Payments → Gift card on too.On
CharactersLetters and numbers (leaving out the easily misread 0, O, 1, I and L), or Numbers only.Letters and numbers
LengthRandom characters in each code, the prefix not counted: 12 to 24.16
Group sizeCodes print in groups of this many characters, joined by dashes; 0 prints one block (0–8).4
PrefixUp to 6 letters and digits before every code.None
Smallest amountThe least a card may be sold or topped up for.1
Largest amountThe most one card may hold, top-ups included.100,000
A new card expires afterDays from the day the card is sold, to the end of its last day; 0 means cards never expire (up to 3650).365
An expired card given money back lastsWhen a return puts money back on a card that has expired since the sale, the card lasts this many days from the return (1–365).30
Ask for a PINEvery new card gets a PIN, printed with its code, and paying with the card asks for it.Off
PIN lengthDigits in a new card's PIN (4–8). Cards already sold keep theirs.4
A reload extends the expiryA top-up gives the card at least the expiry of a card sold that day; never a shorter one.On
Remind the holder before expiryDays before its expiry a card with money on it is emailed once; 0 sends no reminder (up to 365). Needs email set up.14
Book expired cards as income (breakage)What an expired card still holds is booked as income and the card goes to 0. Ask your accountant first.Off

The tab shows what a code will look like.

When store credit expires

Where it came fromExpires
A return refunded to store creditAt the end of the last day of Settings → Payments → Store credit from returns expires after (0 keeps it forever)
Given by handOn the date you chose, or never
Given back by a return or void of a sale it paid forWhen the credit it came from would have
A voided gift cardWhen the card would have

Store credit is kept in parts, each with its own expiry, in calendar days where the business is: credit refunded at 21:00 on 19 October with the setting at 30 is good until 23:59:59 on 18 November. The store-credit job, every 15 minutes, takes expired credit off the balance (Background Jobs).

Importing existing gift cards

ColumnMeaning
codeThe code the holder already has: 8 to 40 letters and digits, once in the file and not already on a card. Empty: a new code is made.
balanceRequired: what the card still holds, such as 25.50.
expires_atThe last day it can be spent, YYYY-MM-DD, today or later. Empty: it never expires.
customerAn existing customer's phone number or email address.
noteUp to 500 characters.

Header names in any case. Every row is checked before anything is written, and problems are listed by row number, never by code. Ready rows go in batches of 100, and a batch sent again after a lost answer writes nothing more.

In the books

EventDebitCredit
Points earned, or added by handLoyalty rewards (6100)Loyalty points liability (2500)
Points taken back by a return or void, or taken off by handLoyalty points liabilityLoyalty rewards
Points, store credit or a gift card spent on a saleIts liability, as a line of the sale's journalThe sale's own lines
A gift card sold or reloadedThe sale's own linesGift card liability (2400), as a line of the sale's journal; never sales revenue
Store credit refunded on a returnThe return's own linesStore credit payable (2300), as a line of the return's journal
Store credit given by handCustomer goodwill (6150)Store credit payable
Store credit taken off by handStore credit payableCustomer goodwill
Store credit expiredStore credit payableOther income (4900)
A gift card voided by handGift card liabilityStore credit payable (its buyer), or Other income (no customer)
A gift card issued from the back officeGift cards given away (6160)Gift card liability
Gift cards imported, one journal per batch of 100Opening balance equity (3100)Gift card liability
A gift card expired with money on it, while breakage is onGift card liabilityGift card breakage (4910)

The books check compares each liability with what customers hold, and says so if they differ (Accounting).

Who may do what

To…Permission
Change Settings → Loyalty or Settings → Gift cardsLoyalty, Gift cards (in the Settings group)
Add or take off points by handAdd or take off points by hand
Pay with pointsUse the POS at the till, or Create sales on a back-office sale
Give or take off store credit by handSet credit limits, tax exemption and store credit
Sell and reload gift cards at the tillSell and reload gift cards
Take gift cards as paymentTake gift cards as payment
Void a gift card by handVoid gift cards
Block and unblock a gift cardBlock and unblock gift cards
Show a card's code, give it a new PIN, email its code again, print its slipShow gift card codes and set new PINs (Administrator only to begin with)
The Gift cards screen, its export, a card's note and Extend expiryManage gift cards
Issue a card with nothing paid for itIssue gift cards with nothing paid (Administrator only to begin with)
Import existing cards from a fileImport existing gift cards (Administrator only to begin with)
The four loyalty points reportsSales reports, or See the loyalty points reports
The gift card reportSales reports
A customer's Loyalty tabSee customers

Permission names as they appear in Staff → Roles. See the loyalty points reports opens only the four points reports, and the reports menu with them: give it to someone who looks after the programme but should not see the other sales reports.

  1. 1

    Switch loyalty on

    Settings → Loyalty → Loyalty points, then Settings → Payments → Loyalty points so the till can take them. Set the rate, the value of a point and the spending rules (the Settings → Loyalty table above).

    Switching loyalty off stops earning and spending. Points already held are kept, and returns still take back the points their goods earned.

    Check: The live example on the tab shows what a sale earns and what points pay.

  2. 2

    Give products and categories their own rate

    For each line of a sale Posify looks, in this order, at the product's own % (the product's edit page → Loyalty points → Points back), then its category's % or the nearest parent category that sets one (Loyalty points back), then Settings → Loyalty → Points back on all products.

    1. 1Empty means take it from the level above; 0% means no points here. A category at 0% with one product in it at 5% gives points only on that product.
    2. 2The lines' points are added up and rounded once for the whole sale, and a tier's multiplier scales the total.
    3. 3A sale keeps the % each line earned at: changing a rate later changes only the sales made after it.
    4. 4Only someone with the Loyalty settings permission can set a product's or a category's %. Anyone else who edits the product sees it but cannot change it.
  3. 3

    Set up tiers

    Settings → Loyalty → Tiers. A customer is in the highest tier whose starting points they have earned in all: their lifetime points, which are the points earned less those taken back by returns and voids. Spending does not lower them. A tier's Multiplier scales what its members earn: 1 is the base rate, 2 earns double.

    1. 1The first tier always starts at 0 points, so every customer is in one. Two tiers cannot start at the same number of points.
    2. 2A new business has Bronze (0), Silver (500), Gold (2000) and Platinum (5000), each at multiplier 1. Remove every tier and everyone earns at the base rate.
    3. 3The tier counts the points earned before the sale.
  4. 4

    Know what earns points

    A sale earns when it is rung up, at the till or as a back-office sale, if it has a customer and loyalty is on.

    1. 1Walk-in sales earn nothing: a sale earns only for the customer on it.
    2. 2The basis is each line's amount after its own discount and its share of the sale discount, before tax.
    3. 3Gift card lines never earn. The part paid with points or a gift card earns nothing; store credit, cash, card and the rest all earn.
    4. 4Deposits and sales on account earn as the money comes in: a deposit's balance taken at the till, or a customer receipt paid toward the sale. A receipt reversed takes back the points it brought.
    5. 5A sale taken offline for a named customer earns when it reaches the server, dated at the time it was rung up, by the loyalty settings as they are when it syncs.
  5. 5

    Spend points at the till and on back-office sales

    With a customer on the sale, the payment dialog offers Loyalty points: their points, a Points to spend box, Use … for the most they may spend, what the points pay, and the rules. On Sales → All sales → New sale, choosing a customer who has points shows Pay with points on the Payment card, which opens the same panel.

    1. 1The server checks every redemption: whole points, at least the minimum, no more than the customer holds, rounded down to your currency's smallest unit, at most the largest share of the sale less any gift card lines, and no more than is left to pay.
    2. 2Points and gift cards never pay for a gift card.
    3. 3Two tills spending the same points at once: one succeeds, the other is refused. If the sale does not go through, no points are spent.
    4. 4On a back-office sale, Loyalty points is not in the payment method list: points are paid only through Pay with points, which works out the share on what the server will charge, tax and cash rounding included.

    Check: The receipt shows the points earned and spent, and the balance after the sale when Settings → Receipt → Show the loyalty balance is on.

  6. 6

    Adjust points by hand

    Open the customer → Loyalty tab → Adjust points. Choose Add points or Take points off, enter whole points and a reason. Use it for points given by mistake or as a goodwill gesture; points from sales move by themselves.

    Taking off never takes the balance below zero. An archived customer's points cannot be adjusted: restore the customer first. The activity log records each adjustment with the balance before and after.
  7. 7

    Give or take off store credit

    Open the customer → Store credit tab. Give credit takes an amount, an optional expiry and a reason; Take off takes an amount and a reason, and removes the credit that expires soonest first. Give credit is for goodwill and Take off for credit given by mistake; refunds to store credit come from returns, not from here.

    1. 1A customer also gets store credit from a return refunded to Store credit (not for a walk-in sale), from a return or void of a sale paid with store credit, and from a voided gift card they bought.
    2. 2At the till, Store credit pays no more than the customer holds, spending the credit that expires soonest first.
    3. 3Credit On hold at a POS that no sale took is given back by the store-credit job after 15 minutes. The tab shows what Expires next.
    4. 4Archived customers cannot be given new store credit.
  8. 8

    Set up gift cards

    Settings → Gift cards (the table above), then Settings → Payments → Gift card. Then add the product the till sells cards through: Products → All products, a new product of kind Gift card.

    1. 1The kind is fixed once the product is created.
    2. 2A gift card holds no stock and is never taxed when sold; tax is charged on what it buys.
    3. 3Instead of a price it has a Suggested amount (0 = any amount), which the sell dialog starts from. The cashier can change it either way.
  9. 9

    Sell or reload a card at the till

    Tap the gift card product. Sell a gift card offers New card (the amount, how many cards, and optionally an email address to send the code to) or Reload a card (type or scan the code, Check, then the amount to add).

    1. 1A card is sold at its value: no tax, no discount, no points. A back-office sale refuses a gift card.
    2. 2A sale with a gift card takes no sale-wide discount; line discounts on the other lines still work.
    3. 3Points, gift cards, store credit and exchange credit cannot buy a gift card; Cash, Card, Bank transfer and Other can.
    4. 4At most 50 new cards in one sale. A reload needs a live card: not void, not blocked, not expired.
    The code is handed over once: large on the Sale complete screen with a copy button, on that sale's receipt (with the PIN when there is one), and by email when an address was typed and email is set up. The email never carries the PIN. A receipt printed again later shows only the card number and the last four characters of the code.
  10. 10

    Check a balance or take a card as payment

    At the till, the Gift card button in the cart's toolbar opens Gift card balance; in the back office, Gift cards → Check a code. To pay, choose Gift card in the payment dialog, type or scan the code and press Check. Paying all or part of the sale shows what it leaves on the card, and the receipt prints it.

    1. 1No PIN is needed to see a balance, and the code is not kept.
    2. 2A card with a PIN asks for it. Five wrong PINs lock the card's PIN for 15 minutes the first time, an hour the next, then a day each time after.
    3. 3A card that is void, blocked, expired or empty is refused, as is more than it holds.
    4. 4Code lookups are limited per person: 30 lookups and 10 codes not found in 15 minutes.
  11. 11

    Block, unblock or void a lost card

    Gift cards → open the card. Block, with a reason, stops it being spent or reloaded at any till ("This gift card is blocked"), whether or not some of it has been spent. No money moves: its balance stays on it and stays owed. Unblock, with a reason, lets it be spent again.

    1. 1Void, with a reason, takes the whole remaining balance off for good. It works on a card nothing has been spent from, or on a blocked card, that has not expired: block a partly spent card first.
    2. 2The balance goes onto the store credit of the customer who bought it, expiring when the card would have, or to the business's income when no customer bought it. The dialog says which before you confirm.
    3. 3A card sold by mistake goes back through its sale instead, with a void or a return, which gives the money back.
  12. 12

    Issue or import cards from the back office

    Issue gift card on the Gift cards screen gives a card with nothing paid for it: the amount, Why it is given (a promotion, compensation, other), and optionally a customer, an email address and a note; the expiry is filled in from Settings → Gift cards, and empty means it never expires. Import brings in cards customers already hold from before Posify, from a CSV file (the import table above).

    1. 1An issued card's code and PIN show once, in the dialog. Issuing works while selling at the till is off, and is refused while cards are not taken as payment.
    2. 2Codes made for imported rows without one are shown once, as a file to download: keep it safe. Imported cards have no PIN; a manager can set one.
    3. 3Issued and imported cards count as issued in the reports, and spend, reload, block and void like any card.

Gift card expiry and breakage

A card lasts to the end of its last day on the business's clock. Past it, a card cannot be spent, reloaded, voided by hand or returned; Extend expiry on its page gives it a later last day. Once a day the gift-card-expiry job reminds holders by email, never with the code or PIN, and, only while breakage is on, takes each expired card that still holds money (blocked ones excepted) to 0 and books Gift card breakage.

The Gift cards screen

Gift cards, in the sidebar's Operations group, lists every card with tabs (All, Active, Spent, Blocked, Void, Expired), a search by card number (GC-000012 or just 12) or the last four characters of a code, the Issued filter, and four tiles: Owed on live cards, Left on expired cards, Issued this month, Spent this month. Export never holds a code or a PIN.

Show code, New PIN, Email the code again, Print slip

On a card's page, for a holder who lost the code or PIN. Each asks why (3 to 300 characters) and records the reason in the activity log with your name; the code and the PIN never are. Emails lists every email sent about the card and whether it went out.

Returns of sales paid with these

Points and gift card value never come back as cash. A return first comes off any balance still owed, then goes back to points, the gift card or store credit in the order the sale was paid, and only the rest by the cashier's method; the return dialog shows the split. A void gives back everything; a void of a sale paid with a card voided or expired since is refused, so take it as a return.

Returns and voids of points

A return takes back the points its goods earned, in proportion, rounded down; the last return takes back exactly what is left. A void takes back everything the sale earned and gives back any points spent on it. A balance may go below zero; the next points pay it back first.

Offline

An offline till does not offer Loyalty points, Store credit or Gift card, cannot sell a gift card, and cannot check a balance (Offline Selling).

Reports

All reports → Loyalty and gift cards: Loyalty points, Loyalty points by customer, Loyalty points by tier, Loyalty points by branch, and Gift cards (one block per currency). Each has the period picker and downloads as CSV or PDF. Points added or taken off by hand belong to no branch: they have their own row, No branch (by hand).

Ask your accountant before booking breakage

With Book expired cards as income off, an expired card's balance stays owed, and the gift card report shows it as left on expired cards. Whether that money may be kept as income depends on the law where you trade. Switched on, it includes cards that expired before you switched it on.

Selling and taking cards are separate

Switching Sell and reload gift cards off stops only new cards and reloads; the till keeps taking cards already sold. Switching Accept gift cards as payment off, or Gift card in Settings → Payments, asks first, saying how many cards and how much they hold: that money is still owed.

Keep the code permission close

A card's code and PIN together are the whole card, so Manage gift cards alone does not show them. Give Show gift card codes and set new PINs only to the people who must answer for lost cards.

Chapter 34 · Backups & Recovery

Back up, restore and get back in

Posify keeps everything in one PostgreSQL database: sales, stock, customers, journals, settings and sign-ins. One pg_dump file therefore backs up the whole business, apart from the product images, logos and documents in your storage bucket. This chapter covers backups and restores, getting back into the owner account, and checking the books after a restore or an upgrade.

Before you start

  • PostgreSQL's client tools, pg_dump and pg_restore, of the server's major version or newer. On Windows they are in C:\Program Files\PostgreSQL\17\bin.
  • Your DATABASE_URL. The examples use postgresql://posify:a-strong-password@127.0.0.1:5432/posify: put yours in its place.
  • For the pnpm commands: a terminal in the app's folder (the one with .env), or in the container (Docker Image).

What to keep, and where it lives

WhatWhere it livesHow to keep it
Business dataThe PostgreSQL database: sales, stock, customers, journals, settings and sign-ins.pg_dump, before every upgrade and every night (steps 1 to 4).
FilesYour storage bucket: product images, logos and documents.Your storage provider's own tools. The database backup does not hold them.
Server settings.env, or the panel's environment: secrets, addresses and keys.A copy in a safe place, such as your password manager.
  1. 1

    Back up the database now

    pg_dump writes the whole database to one file: every table, its data and the record of the migrations, so a restored copy knows which migrations it has.

    Linux and macOS
    bash
    pg_dump --format=custom --file=posify-$(date +%Y%m%d-%H%M).dump "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"
    Windows PowerShell
    powershell
    & "C:\Program Files\PostgreSQL\17\bin\pg_dump.exe" --format=custom --file="posify-$(Get-Date -Format yyyyMMdd-HHmm).dump" "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"
    Back up before every upgrade, and on a schedule (next step).

    Check: A file such as posify-20260101-0300.dump is in the current folder, and it is not empty.

  2. 2

    Back up every night

    Run the same command from the server's crontab, into a folder outside the app. Copy the files off the server now and then: a backup that lives only on the server is lost with it.

    1. 1Create /var/backups/posify first, writable by the account whose crontab runs the lines.
    2. 2In a crontab, write each % as \%, as above: crontab treats % as a special character.
    3. 3The second line deletes backups older than 14 days. Keep as many as you need.
    crontab -e
    bash
    30 1 * * *  pg_dump --format=custom --file=/var/backups/posify/posify-$(date +\%Y\%m\%d-\%H\%M).dump "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"
    45 1 * * *  find /var/backups/posify -name 'posify-*.dump' -mtime +14 -delete

    Check: The next morning, ls -lh /var/backups/posify lists a new .dump file.

  3. 3

    Back up PostgreSQL that runs in Docker

    Run the tools inside the database container and copy the file out. posify-pg is the database container's name in these examples.

    bash
    docker exec posify-pg pg_dump -U posify --format=custom --file=/tmp/posify.dump posify
    docker cp posify-pg:/tmp/posify.dump ./posify.dump
    Copy the file with docker cp, as here. Redirecting docker exec … pg_dump output into a file with > damages it in Windows PowerShell, which rewrites the bytes as text.

    Check: posify.dump is in the current folder on the host, and it is not empty.

  4. 4

    Back up a managed database

    pg_dump and pg_restore work with the provider's direct connection string. Most providers also keep backups or offer point-in-time recovery from their own dashboard, depending on the plan.

  5. 5

    Restore a backup

    A restore replaces Posify's tables with the backup's. Stop the app first (sudo systemctl stop posify, pm2 stop posify or docker stop posify), then run:

    1. 1--clean --if-exists drops each of Posify's tables before restoring it.
    2. 2--single-transaction makes the restore all or nothing.
    3. 3--no-owner makes the user in the string the owner of what it restores.
    4. 4If the code is newer than the backup, run pnpm db:migrate. If you are going back to the old code too, start that code instead.
    5. 5Start the app, then run pnpm accounting:reconcile --dry-run (step 10).
    bash
    pg_restore --clean --if-exists --no-owner --single-transaction \
      --dbname="postgresql://posify:a-strong-password@127.0.0.1:5432/posify" ./posify-20260101-0300.dump

    Check: The app opens with the backup's data, and the reconcile ends with Dry run: nothing was written.

  6. 6

    Restore into PostgreSQL in Docker

    Copy the file into the database container and restore it there. Stop the app first.

    bash
    docker cp ./posify.dump posify-pg:/tmp/posify.dump
    docker exec posify-pg pg_restore -U posify --clean --if-exists --no-owner --single-transaction --dbname=posify /tmp/posify.dump

    Check: The command ends without an error, and the app opens with the backup's data after you start it.

  7. 7

    Look at a backup without touching the live database

    Restore it into a new database and point a test copy of the app at it. Do this once before you need a backup, so you know yours works.

    bash
    sudo -u postgres createdb --owner=posify posify_check
    pg_restore --no-owner --dbname="postgresql://posify:a-strong-password@127.0.0.1:5432/posify_check" ./posify-20260101-0300.dump

    Check: A test copy of the app whose DATABASE_URL ends in /posify_check opens with the backup's sales and products.

  8. 8

    Get back into the owner account

    pnpm create-admin creates or restores an owner account from the command line: use it when the owner's password is lost, or that account was suspended. Run it in the app's folder.

    1. 1An account with that email: it is put on the Administrator role and made active. It becomes the business's owner unless another active owner exists.
    2. 2No account with that email: one is created on the Administrator role, and made the owner unless another active owner exists.
    3. 3The password: the one you type. Without one, ADMIN_PASSWORD from .env is used. If that is empty too, a new account gets a random password, printed once, and an existing account keeps its password.
    4. 4Setting a password ends every open session of that account.
    5. 5If the business was not yet marked installed, the command marks it, and the install wizard closes.
    bash
    pnpm create-admin you@example.com "a-new-password" "Your Name"
    .env.example ships ADMIN_PASSWORD=change-me. If that line is still in .env and you type no password, the password becomes change-me: type it, or change or delete that line. A password typed on the command line can end up in your shell history, so change it from the profile page after you sign in.

    Check: For an existing account, the terminal prints ✓ you@example.com is on the Administrator role and is the Owner. and ✓ Password set; every open session was ended.

  9. 9

    Lost the authenticator app as well

    A new password does not turn two-step verification off. If you still have a backup code, sign in with it: Lost your phone? Use a backup code, on the code step. If the authenticator app and the backup codes are both gone, add --reset-2fa.

    bash
    pnpm create-admin you@example.com "a-new-password" --reset-2fa
    It removes the two-step secret and the backup codes and ends every session. Set two-step verification up again after you sign in (Security).

    Check: The terminal prints ✓ Two-step verification turned off; set it up again from the profile page after signing in.

  10. 10

    Check the books

    Every sale, purchase, payment and stock change posts a journal. pnpm accounting:reconcile replays the documents through the posting rules and compares the result with the journals. It posts any journal a document is missing (never one twice), retries postings that failed earlier, rebuilds the customers' dues and the suppliers' payables where they drifted, and reports the trial balance. Run it after an upgrade, after restoring a backup, or when Accounting → Books check asks you to.

    1. 1Exit code 0: the books follow the documents.
    2. 2Exit code 1: something failed, or the trial balance does not balance. Read the output.
    3. 3Exit code 2: a dry run found a missing journal or a drifted balance, or a journal differs from the rules. Run it without --dry-run; if journals still differ, Accounting → Books check names them and the repair for each.
    4. 4Exit code 3: it stopped on --budget. Run it again to continue.
    5. 5--from and --to read the days in the business's time zone. --kind takes kinds such as sale, sale_return, goods_receipt, supplier_bill and expense; an unknown kind stops the command and lists the known ones.
    6. 6--rebuild works on one kind: it reverses each journal that differs from the rules and posts the right one, and reverses journals the documents no longer post. It never deletes, and a second run changes nothing.
    bash
    pnpm accounting:reconcile --dry-run                        # report only, write nothing
    pnpm accounting:reconcile                                  # post what is missing
    pnpm accounting:reconcile --kind=sale,goods_receipt        # only these kinds of document
    pnpm accounting:reconcile --from=2026-01-01 --to=2026-01-31
    pnpm accounting:reconcile --rebuild --kind=sale            # rebuild one kind's journals
    pnpm accounting:reconcile --budget=60                      # stop after 60 seconds
    pnpm accounting:reconcile --json                           # the report as JSON
    The nightly accounting-reconcile job does the same with a time limit (Background Jobs). More on the books: Accounting.

    Check: The last lines read Trial balance: debits …, credits … — balanced, and with --dry-run, Dry run: nothing was written.

  11. 11

    Run these commands in the Docker image

    The image ships the tools these commands need. pnpm db:migrate reads DATABASE_URL straight from the container's environment. The other commands read a .env file, which the image does not hold, so create an empty one first: the container's environment still supplies every value.

    bash
    docker exec posify pnpm db:migrate --list
    docker exec posify touch .env
    docker exec posify pnpm create-admin you@example.com "a-new-password"
    docker exec posify pnpm accounting:reconcile --dry-run
    posify is the app container's name. The image has no pg_dump: take backups from the host or from the database's own container (step 3). In a deploy panel, run the same commands in the container's terminal, after cd /app.

    Check: pnpm db:migrate --list ends with … applied, 0 pending.

Never point db:seed or db:reset at a live business

The seed writes demo sign-ins whose passwords are published, and pnpm db:reset deletes every sale, product, customer and journal without asking. Before you run either, check which database .env names (Database Setup).

Chapter 35 · What's New in 1.0

Posify 1.0, the first release

Posify 1.0 is the first release: a point of sale and back office for one business with many branches and registers, on your own server and your own PostgreSQL database. There is nothing to upgrade from. This chapter sums up what 1.0 includes, area by area, and the few things worth doing once after installing.

After installing

Nothing is mandatory; three things are worth doing once

A new install runs pnpm db:migrate once, on an empty database, before the first start. It creates every table, and pnpm db:migrate --list then shows each migration as applied. After the install wizard:

  • Set up the background jobs (Background Jobs). Without them, emails that fail their first try are never retried, digests and reminders do not go out, and the nightly books check does not run.
  • Check the books: pnpm accounting:reconcile --dry-run is a health check that writes nothing. Exit code 0 means everything is in order.
  • Schedule database backups (Backups & Recovery).
Two checks
bash
pnpm db:migrate --list               # every migration: applied
pnpm accounting:reconcile --dry-run  # exit code 0: the books are in order
Go to the Go-Live Checklist

Branches and registers

One business with many branches. Each branch has its own registers, stock and staff, and reports show one branch or all of them. Installing creates a Main Branch with one register, Counter 1.

The till, online and offline

Cash, card and other tenders, deposits, credit sales, returns, voids, holds, cash in and out, and register opening and closing with X and Z reports. When the internet drops, the till keeps selling and sends the queued sales when it comes back (Offline Selling).

Sales and receipts

Every sale, return and receipt in the back office. Receipts go out by print, email or text message, and Settings → Invoice templates holds the receipt and sale invoice designs (Invoice Templates).

Products

Categories, brands, units, variants, barcodes and labels, with CSV import and export. A product saved without a barcode gets an internal one that scans at your tills.

Inventory

Stock per branch at a moving average cost: adjustments, transfers between branches, stock counts, a full movement history, low-stock lists and an opening stock import (Inventory).

Purchasing

Purchase orders, goods receipts, supplier bills, supplier payments and purchase returns.

Customers and suppliers

Balances, statements, credit limits and opening dues, CSV export, and CSV import of customers.

Customers and marketing

Each customer's consent to offers by SMS and by email, with its history. Segments built from rules, campaigns by SMS or email with quiet hours and a daily SMS limit, automations such as birthday wishes, and coupons at the till and on a back-office invoice. Offer emails carry an unsubscribe link, and a reply of STOP is honoured. Campaigns need the marketing-send background job (Background Jobs).

Loyalty, store credit and gift cards

Points, store credit and gift cards, earned and spent at the till (Loyalty & Gift Cards).

Double-entry accounting

Every sale, purchase, payment and stock change posts a journal. Chart of accounts, manual journals, expenses (repeating ones too), cash and bank accounts, profit and loss, balance sheet, cash book, receivables and payables aging, and a books check (Accounting).

Tax

Tax rates and groups, prices with or without tax, exemptions, and a tax report by month and rate. A new business charges no tax until you add rates and groups (Tax).

Staff, roles and sign-in

Nine preset roles (Administrator, Manager, Cashier, Accountant, Stock Keeper, Purchaser, Supervisor, Read-only and External Accountant) and your own roles, staff limited to their branches and registers, two-factor sign-in and an activity log (Staff & Roles).

Reports

46 reports across sales, registers, stock, purchasing, profit, finance and loyalty, with CSV and PDF export. PDFs need Chrome or Chromium on the server (Node Server).

Notifications

An in-app bell, email, and text messages through Twilio or another SMS provider. Settings → Notifications decides who hears of what (Notifications).

Languages and themes

18 languages, Arabic right to left, light and dark themes, and an installable app: Chrome and Edge offer Install app once the business has a favicon or logo (Languages & RTL).

Hardware

Barcode scanners (the device's camera too), receipt printers, label printers and a cash drawer opened through the receipt printer. QZ Tray prints without a dialog and opens the drawer (Hardware).

Your server, your database

PostgreSQL 16 or newer, run as a Docker image that GitHub Actions builds, or as a Node server behind nginx or Caddy (Choose Your Path).

Environment variables in 1.0

All variables are new in 1.0; Environment Variables lists them. CHROME_PATH, for PDF exports, is optional and not in .env.example.

What 1.0 does not connect to

Card terminals: take the card on your own reader and record it at the till as Card, with an optional reference. Customer-facing displays. Weighing scales: to sell by weight, give the product a unit with decimals and type the weight as the quantity (Hardware).

Try it before you install

The public demo runs at posify-demo.neurolightstudio.com.

Chapter 36 · Updates & Migrations

Upgrade to a new release

This chapter is for a business that is already installed and running. Read the notes of every release you cross, oldest first; one pnpm db:migrate then brings the database up to the newest release, whatever it skipped. Posify 1.0 is the first release, so keep this routine for the next one: each release's notes are in docs/UPGRADE.md in its download.

Read this first

New code never starts on old tables

Posify never creates or changes its tables by itself. New code that meets the old tables fails, and once the migrations have run, the old code may not run on the new tables either. So: back up, build the new release in a new folder, stop the app, run pnpm db:migrate, and only then start the new code.

  • Back up the database first. pnpm db:migrate is all or nothing and safe to run twice, but a backup is what makes a bad upgrade a short problem.
  • Unzip the new release into a new folder, never over the old one: a file the new release removed would stay behind and still be built.
  • Keep your .env. Never overwrite it with the new .env.example; compare the two (step 3).
  • Going back means the old folder and the backup, together.

Before you start

  • The new release's download from CodeCanyon, and the section of its docs/UPGRADE.md for every release you cross.
  • A terminal on the server, or your panel's terminal.
  • A quiet time: while you work, maintenance mode closes the app to everyone whose address is not on its allow-list.

How pnpm db:migrate works

RuleWhat it means
Only what is missingThe database records each migration it has, in drizzle.__drizzle_migrations. A run applies only the ones it lacks, oldest first, so a release you skipped is caught up in the same run.
All or nothingEvery pending migration is applied in one transaction. If one fails, nothing is applied: fix the cause and run it again.
Safe to run twiceWith nothing pending it says "The database is up to date. Nothing to apply."
One run at a timeA second run on the same database waits for the first to finish.
Unknown migrationsIt refuses a database that holds a migration this code does not know: a newer or a different build migrated it.
Changed migrationsIt warns, without stopping, when a migration that already ran has changed since. A released migration is never changed; a later fix is a new migration.
Which databaseDATABASE_URL from the environment first, else from .env in the app's folder. Its first line names the database and server it reached.

pnpm db:migrate --list shows every migration as applied (and when) or pending, and --dry-run shows the pending ones; neither writes anything. It exits 1 when it fails or refuses.

  1. 1

    Check Node.js and PostgreSQL

    The release's package.json names the minimum Node.js under engines (24.11.0 for 1.0). A release that needs a newer PostgreSQL than 16 says so in its section.

    bash
    node --version
    psql "postgresql://posify:a-strong-password@127.0.0.1:5432/posify" -c "SELECT version()"

    Check: Both versions are at least what the release asks for.

  2. 2

    Put the new code in a new folder

    Unzip the new release into a new folder and copy your .env into it. Keep the old folder until the new one runs well: it is your way back.

    Do not unzip over the old folder, and never overwrite .env with the new .env.example.

    Check: The new folder holds the release and your .env, and the old folder is untouched.

  3. 3

    Compare .env with the new .env.example

    In the new folder, this lists the names in the new .env.example (set or commented out) that your .env does not have. Most new names are optional; the release's section says when one is required.

    Linux and macOS
    bash
    comm -23 \
      <(grep -oE '^#? ?[A-Z][A-Z0-9_]+=' .env.example | tr -d '# =' | sort -u) \
      <(grep -oE '^[A-Z][A-Z0-9_]+=' .env | tr -d '=' | sort -u)
    Windows PowerShell
    powershell
    $names = { param($file) Select-String -Path $file -CaseSensitive -Pattern '^#? ?([A-Z][A-Z0-9_]+)=' | ForEach-Object { $_.Matches[0].Groups[1].Value } | Sort-Object -Unique }
    Compare-Object (& $names .env.example) (& $names .env) | Where-Object SideIndicator -eq '<=' | ForEach-Object InputObject

    Check: The list is empty, or holds only names you have decided about.

  4. 4

    Turn on maintenance mode

    Settings → Maintenance Mode closes the app to everyone whose address is not on its allow-list.

    1. 1Switch on Enable Maintenance Mode.
    2. 2Under Allowlisted IP addresses, add your own IP address, one per line, to keep working.
    3. 3Optional: a Headline, a Maintenance Message, a background image, and Show countdown with Expected back online.
    4. 4Click Save Maintenance Settings.
    Signing in and the Settings pages stay open during maintenance, so an administrator can always switch it off. The background jobs keep running.

    Check: A phone on mobile data shows the maintenance page, while you still see the app.

  5. 5

    Back up the database

    Use your own DATABASE_URL. For PostgreSQL in Docker and managed databases, see Backups & Recovery.

    Linux and macOS
    bash
    pg_dump --format=custom --file=posify-$(date +%Y%m%d-%H%M).dump "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"
    Windows PowerShell
    powershell
    & "C:\Program Files\PostgreSQL\17\bin\pg_dump.exe" --format=custom --file="posify-$(Get-Date -Format yyyyMMdd-HHmm).dump" "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"

    Check: The new .dump file is there, and it is not empty.

  6. 6

    Install and build the new release

    In the new folder, install the packages and build. The old app keeps running meanwhile.

    1. 1On a server with 8 GB of RAM or less, or while the old app runs beside it, build with BUILD_MAX_CPUS=2 pnpm build.
    bash
    pnpm install --frozen-lockfile
    pnpm build

    Check: The build ends with check:chunks — … preloaded chunk references, all in .next.

  7. 7

    Stop the app and run the migrations

    The app never changes its tables itself, so the new code needs pnpm db:migrate to have run first. Stop the app (sudo systemctl stop posify or pm2 stop posify), then, in the new folder:

    1. 1Then do any other step the release's section lists for a release you cross.
    bash
    pnpm db:migrate --dry-run   # what will be applied; writes nothing
    pnpm db:migrate             # apply it

    Check: The dry run lists what is pending and writes nothing. The real run ends with a Done: line, or says "The database is up to date. Nothing to apply."

  8. 8

    Start the new code, then turn maintenance mode off

    Point your service at the new folder and start it.

    1. 1systemd: set WorkingDirectory in /etc/systemd/system/posify.service to the new folder, then run sudo systemctl daemon-reload and sudo systemctl start posify.
    2. 2pm2: run pm2 delete posify, then the pm2 start command from the new folder (Node Server), then pm2 save.
    3. 3Then open Settings → Maintenance Mode, switch Enable Maintenance Mode off and click Save Maintenance Settings.

    Check: The app opens for everyone, with your data.

  9. 9

    Check the books

    pnpm accounting:reconcile --dry-run writes nothing. Its exit code says what to do: in bash, echo $? right after the command shows it; in PowerShell, $LASTEXITCODE.

    1. 10: the books follow the documents. Nothing to do.
    2. 22: something needs posting or a look. Run pnpm accounting:reconcile without --dry-run to post what is missing and rebuild the customer and supplier balances.
    3. 3Still 2 after that: a journal differs from the posting rules. Accounting → Books check names it and the repair.
    4. 41 or 3: see step "Check the books" in Backups & Recovery.
    bash
    pnpm accounting:reconcile --dry-run

    Check: The command exits with code 0.

  10. 10

    Add any new background job

    If a release adds a job, its section says so. Settings → Maintenance Mode → Background jobs shows the lines your server should be calling: compare them with your crontab or scheduler (Background Jobs).

    Check: Every job shows Running.

  11. 11

    Upgrade the prebuilt Docker image

    With the image, GitHub builds the new release and the server only pulls it: the list below replaces steps 2, 6, 7 and 8. Compare the env file with the new .env.example (step 3) as well.

    1. 1Turn on maintenance mode and back up the database (steps 4 and 5).
    2. 2Put the new release into your GitHub repository and push. The workflow builds and pushes a new image (Docker Image).
    3. 3On the server, pull the new image, stop the old container, run the migrations in a one-off container, then start the new one, as below.
    4. 4Turn maintenance mode off.
    bash
    docker pull ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main
    docker rm -f posify
    docker run --rm --env-file /opt/posify/.env ghcr.io/YOUR-ACCOUNT/YOUR-REPO:main pnpm db:migrate   # the tables
    docker run -d --name posify ...   # the same command you started it with
    docker exec posify sh -c "touch .env && pnpm accounting:reconcile --dry-run"
    Add --network posify to the one-off container when PostgreSQL runs on that Docker network. In a deploy panel, redeploy and run the migrations in the container's terminal instead (Dokploy & Panels).

    Check: The reconcile ends with Dry run: nothing was written.

  12. 12

    Roll back

    Once the migrations have run, the old code may not run on the new tables. Going back takes the old code and the backup together.

    1. 1Node server: stop the app, restore the backup (Backups & Recovery), and point the service back at the old folder.
    2. 2Docker image: restore the backup, then run the previous image's short-SHA tag instead of main.

    Check: The old version opens with the data as it was before the upgrade.

Releases you skipped

One pnpm db:migrate catches up every release you skipped. Still read each skipped release's section, oldest first: a section says when a release needs anything more. Data a release needs to move or fill in is part of its migrations; a step that needs a decision from you is listed in its section, with the command to run.

Never change a business's tables another way

Nothing but pnpm db:migrate changes a business's tables. Never run drizzle-kit push or drizzle-kit generate against one.

Chapter 37 · Troubleshooting

Fix common problems

Most problems have a known cause and a short fix. The tables group them by where they show up: installing and building, the database, the install wizard, signing in, the background jobs, messages and files, PDFs, and the till. Check here before you open a support ticket.

Start here

Find the exact message first

Most fixes below quote the exact words Posify shows. Copy a few words of your message and search this page (Ctrl+F, or Cmd+F on a Mac). The message is usually in one of these places:

  • The install wizard: each row of System check names its problem.
  • A Node server: journalctl -u posify -f under systemd, or pm2 logs posify.
  • The Docker image: docker logs posify --tail 100.
  • A deploy panel: the application's logs.
  • Commands such as pnpm db:migrate print their own messages in the terminal.
  • The till: its banner and dialogs.

Installing and building

ProblemWhat to do
pnpm install failsCheck that the hidden files .pnpmfile.cjs and pnpm-workspace.yaml sit next to package.json: they are easy to lose when copying. Run corepack enable, so pnpm is the pinned 10.24.0, and install with pnpm install --frozen-lockfile.
Build runs out of memoryThe build needs several GB of RAM. Set BUILD_MAX_CPUS=2 in .env (or run BUILD_MAX_CPUS=2 pnpm build), or build in GitHub Actions and run the prebuilt image (Docker Image).
Workflow stops at once"Set NEXT_PUBLIC_APP_URL under Settings -> Secrets and variables -> Actions -> Variables.": add that repository variable, then run the workflow again.
Workflow type check failsNo image is pushed. If you changed the code, fix what pnpm typecheck reports. If you did not, contact support with a screenshot of the run.
No prebuilt .next"ERROR: no prebuilt .next/ in the build context.": something built deploy/Dockerfile without the workflow's build. Run the image the workflow pushes, or build on the server (Node Server).
docker pull refusedLog in again with docker login ghcr.io and a classic token with read:packages: the old one may have expired. Write the image name in lowercase.
.env not foundpnpm create-admin, pnpm accounting:reconcile and the other database commands read a .env file. In the Docker image or a panel's terminal, run touch .env in /app first; the environment still supplies every value.
Missing DATABASE_URL"Missing DATABASE_URL: run through pnpm create-admin, which loads .env.": run the command with pnpm from the app's folder, and check that .env (or the container's environment) holds DATABASE_URL.

The database and migrations

ProblemWhat to do
DATABASE_URL not setThe app says "Please define the DATABASE_URL environment variable inside .env", or pnpm db:migrate says DATABASE_URL is not set. Put it in .env (or the container's or panel's environment), then restart (Database Setup).
Not a PostgreSQL URL"DATABASE_URL is not a URL" or "DATABASE_URL must be a postgresql:// URL": write it as postgresql://USER:PASSWORD@HOST:5432/DATABASE.
Server did not answer"The PostgreSQL server did not answer": check the host and port in DATABASE_URL, that PostgreSQL runs, and that it accepts connections from this server (listen_addresses, pg_hba.conf, firewall). Inside a container, 127.0.0.1 is the container itself.
Password refusedpassword authentication failed for user "…": the user or password in DATABASE_URL is wrong, or the password holds a character that must be percent-encoded (@ : / # %).
Permission deniedpermission denied for schema public from pnpm db:migrate: the user in DATABASE_URL must own the database. Run ALTER DATABASE posify OWNER TO posify; as the postgres user.
Tables missingrelation "…" does not exist in the log, or a command that says "This database has no posify tables yet": the tables are missing, or older than the code. Run pnpm db:migrate, then try again.
Unknown migration"This database has 1 migration(s) this code does not have": a newer or a different build of Posify migrated it. Run that build, or restore the backup you took before upgrading. Nothing was applied.
A migration failed"A migration failed, so the transaction was rolled back: nothing was applied." The line under it names the cause: fix it and run pnpm db:migrate again.
Migrate waits"Another pnpm db:migrate is running on this database; waiting for it to finish …": two runs take turns. Let the first one finish.
Changed migration warning"… was changed after this database applied it": a released migration was edited in your copy. Put the original back; a fix belongs in a new migration.
Incomplete copy"No migrations under lib/pg/migrations: this copy of posify is incomplete.": copy the release again, every folder included.

The install wizard

ProblemWhat to do
Database check failsIts line names the cause: DATABASE_URL not set, a server that did not answer, a refused user or password, a database that does not exist, no tables yet, or a user that may not read them. Fix that one, then press Check again. With no cause given, check DATABASE_URL (user, password, host, port, database name), that PostgreSQL accepts connections from this server, and that pnpm db:migrate ran against that same database.
Error page, no wizardPages do not send you to the wizard while the database cannot be reached. Open /install yourself: its Database connection row names the cause.
Node.js too old"Node.js 24.11 or newer is required": run the app with Node.js 26, or at least 24.11.0 (Requirements).
Authentication secret"BETTER_AUTH_SECRET is …": set a unique random value of 32+ characters (openssl rand -base64 48), then restart.
Installation token row"INSTALL_TOKEN is not set…" or "… characters. Use at least 32": put a 32+ character value in INSTALL_TOKEN (openssl rand -hex 32), then restart the app.
Token refused"That installation token does not match INSTALL_TOKEN in the server's .env file.": paste the exact INSTALL_TOKEN value the app runs with.
Application URL warning"NEXT_PUBLIC_APP_URL is …, but this installer is open on …": make NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL the address you open, then rebuild and restart.
Setup not finished"Your business is installed, but setup is not finished": sign in, open Settings → General Settings, check the business name, language and currency, then click Save.
/install not foundThe business is installed and the wizard is closed for good. Sign in at /login; if you are locked out, see the next table.

Signing in and addresses

ProblemWhat to do
Sign-in fails hereSign-in trusts the addresses in NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL (and a private network address the page is open on). Open Posify on that address, or set both variables to the one you use, then rebuild and restart (Domain & HTTPS).
Insecure auth configurationThe log shows [auth] Insecure auth configuration: BETTER_AUTH_SECRET … and nobody can sign in. Set a unique random value of 32+ characters, then restart.
Email links point elsewhereLinks in emails follow the configured address. If they point to http://localhost:3000 or an old domain, set BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL to the right one, then rebuild and restart.
Owner password lostForgot password? on the sign-in page sends a reset link once email is set up. Otherwise run pnpm create-admin you@example.com "a-new-password" (Backups & Recovery).
Two-step codes lostSign in with a backup code (Lost your phone? Use a backup code). With none left, add --reset-2fa to pnpm create-admin.
Account locked"Too many failed sign-in attempts. This account is locked for …": wait that long, or have an administrator use Unlock an account under Settings → Security & Access Control (Security).
Everyone shares one limitBehind a CDN other than Cloudflare, or a load balancer that forwards from a public address, every visitor arrives as its address. Set TRUSTED_PROXIES (Domain & HTTPS).
Maintenance page for allSign in at /login, which stays open during maintenance, open Settings → Maintenance Mode, switch Enable Maintenance Mode off and click Save Maintenance Settings. To keep working during maintenance, add your IP address under Allowlisted IP addresses.
Deletes refused"Demo mode is enabled…": DEMO_MODE or NEXT_PUBLIC_DEMO_MODE is on. On a real business, remove both and restart, and rebuild if NEXT_PUBLIC_DEMO_MODE was set (Security).

Background jobs

ProblemWhat to do
Jobs answer 401CRON_SECRET is missing, still the placeholder, shorter than 16 characters, or the scheduler sends a different value. The log says which, once, for example [cron] CRON_SECRET is not set; …. A refused call is not recorded, so the job keeps looking stopped.
Background jobs have stoppedThe bell names jobs that have not run within their allowance. Right after installing this is expected. Otherwise check the scheduler lines for those jobs, test one by hand, and read Settings → Maintenance Mode → Background jobs (Background Jobs).
A job shows FailingIt runs, but failed three times in a row. Its last error shows under it in Settings → Maintenance Mode → Background jobs; the app's log has the rest.
curl not foundA panel schedule that runs inside the container cannot use curl: the image has none. Use the node -e … command from Background Jobs instead.
Digests at the wrong hourDigests go out once the business's clock reaches Settings → Notifications "Daily digests from", in the time zone set in Settings → General Settings, not the server's. Check both.
Jobs stop after a new secretChange CRON_SECRET on the app and in every scheduler line at the same time, then restart the app (with the image, a new container).

Email, text messages and storage

ProblemWhat to do
No password reset emailsEmail is not set up, so Forgot password? tells people to ask the owner or a manager. Set up Settings → Email and send a test (Email / SMTP).
Failed emails not retriedEmails and texts that fail their first try are retried only by the email-deliveries job. Check that it runs (Background Jobs).
No text messagesTexts go out only after SMS is switched on in Settings → SMS (Twilio) and one test text has been sent from there (Text Messages).
Example values usedSMTP or storage lines uncommented with the .env.example values (smtp.example.com, your-bucket-name, …) count as real settings. Fill them in properly, or comment them out again and use Settings.
A .env change does nothingFor SMTP, SMS and storage, a value saved in Settings always wins; the .env variable is only a fallback for each field. Change it in Settings.
Uploads unavailableStorage is not set up yet. Add the bucket under Settings → Storage Settings (Storage & Media).
Public URL problems"API credentials are correct, but no Public URL is set…" or "…the public URL is not accessible": make the bucket publicly readable and put its address in Public URL.
Upload refused by nginxnginx answers 413 Request Entity Too Large: raise client_max_body_size to at least the largest file size set in Settings → Storage Settings, then reload nginx.
Images at full sizeImages from your own domain or MinIO are optimized only when STORAGE_PUBLIC_URL (or STORAGE_ENDPOINT) was set when the app was built. Set it and rebuild; for the image, in the workflow's Build step environment.

PDF exports

ProblemWhat to do
PDF export needs Chrome"PDF export needs Chrome or Chromium on the server. The CSV works without it.": install Chromium and the Noto fonts, or set CHROME_PATH to yours (Node Server).
Receipt emails without PDFThe same cause: the server has no Chrome or Chromium. The email itself still goes out.
Empty boxes in PDFsBengali, Hindi, Arabic, Chinese and Japanese text prints as boxes without the Noto fonts: sudo apt-get install -y fonts-noto-core fonts-noto-cjk.
No PDFs with the imageThe shipped deploy/Dockerfile has no Chromium. Add the lines from step 3 of Docker Image, push, and run the new image.

The till, offline selling and printing

ProblemWhat to do
Register not reached yet"This register has not reached the server on this device yet, so it cannot be used offline.": open the till once on that device while online and signed in (Offline Selling).
Till never works offlineThe offline till needs a production build (pnpm build and pnpm start, or the image; pnpm dev has none) and an https:// address, or localhost on the same machine. A plain http:// network address cannot work offline.
Reconnect to keep sellingThe offline selling window has passed: Settings → Point of sale → Locking and offline selling → Offline selling window, 1 to 72 hours, 12 by default. Reconnect and sign in; nothing taken before is lost.
Too many unsynced sales"This register has too many unsynced sales. Reconnect to sync before taking more.": a register holds at most 500. Reconnect so the queue syncs.
Browser cannot store sales"This browser cannot store offline sales, so the sale was not taken.": a private window, or blocked site data. Use a normal window and allow the site's storage.
An offline sale needs reviewThe server refused a queued sale. On the device that took it, open the till, press Review on the banner, fix the cause in the back office and press Send again. Press Discard only once the sale is recorded another way.
Payment refused offline"… cannot be taken while the register is offline": loyalty points, store credit and gift cards need a connection.
Camera will not scan"This browser cannot scan with the camera.": the camera works only on an https:// address, with the browser allowed to use it. Offline, it works only after it was opened once online.
No product found"No product found for the scanned code.": no product or variant has that barcode or SKU. Check that the scanner sends Enter after the code and adds no other prefix or suffix (Hardware).
Several products match"Multiple products match this code. Please fix duplicate SKU or barcode values.": give each product or variant its own code.
Scan refused in a dialog"Close the open dialog, then scan again.": a scan is refused while a dialog is open, so it cannot change a sale halfway through a payment.
Print dialog every timeReceipts go straight to the register's Receipt printer only through QZ Tray. Check that QZ Tray runs on that computer and that the printer's name matches what Find printers lists.
QZ Tray not configured"QZ Tray is not configured. Add QZ_TRAY_CERTIFICATE and QZ_TRAY_PRIVATE_KEY.": set both, each on one line with \n for every line break, then restart (Hardware).
QZ Tray not running"QZ Tray is not running on this computer": start QZ Tray, and allow your site when it asks (tick Remember this decision).
Drawer does not open"The drawer did not open. Check the printer and QZ Tray.": turn on Settings → Point of sale → Open the cash drawer and the register's Cash drawer, pick the printer the drawer plugs into, and try Drawer pin 5 if 2 does nothing.
Labels print question marksZPL and TSPL labels print plain Latin characters only. For names in other scripts, print the labels through the browser.

Before you open a support ticket

Open it at support.neurolightstudio.com, with the Posify version (1.0), how you run it (Docker image, panel or Node server), the exact message, the last lines of the log, and what you already tried. Never send your .env values, keys or passwords. Prefer to have Posify installed for you? Book paid installation help.

Updates·Last updated October 27, 2026
↑ Back to top