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 sectionChoose 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 sectionQuickstart
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 sectionRequirements
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 sectionPosify 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.
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 itRun 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
The prebuilt Docker image
Prebuilt imageGitHub 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
Dokploy or another deploy panel
Web panelA 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
A Node server you run yourself
Full controlYou 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
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 onhttps://. - 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_TOKENandCRON_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
| Path | Background jobs | Shell for commands | Updating |
|---|---|---|---|
| Your computer | Not set up, which is fine for testing. Without them, failed emails are not retried and no digests go out. | Yes, your own terminal | Unzip the new release into a new folder, copy .env across, install, build and run pnpm db:migrate |
| Prebuilt Docker image | The host's crontab, or a hosted cron service, calls the 11 job URLs on your public address | Yes: docker exec posify … on the server | Push 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 panel | The panel's cron, or the host's crontab, calls the 11 job URLs | Yes, the container's terminal in the panel | Push the release to main, then redeploy, or let the workflow do it. Run pnpm db:migrate in the terminal, with maintenance mode on. |
| Node server | You add 11 crontab lines once (Background Jobs) | Yes, over SSH | Unzip 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.
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
.nvmrcnames.node -vshows yours. - pnpm 10.24.0 through Corepack: after
corepack enable,pnpm -vin the app folder prints10.24.0. - PostgreSQL 16 or newer, with an empty database and a user that owns it, for example user
posifyand databaseposify. 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.jsonand.env.example.
- 1
Install the packages
Open a terminal in the app folder and install the packages Posify needs. The first install downloads a lot.
- 1Windows: open the app folder in File Explorer, click the address bar, type
powershelland press Enter. - 2macOS or Linux: open Terminal, type
cdand a space, drag the app folder into the window, and press Enter. - 3Run the two commands below. Corepack may ask whether to download pnpm: type
Yand press Enter.
bashcorepack enable pnpm install --frozen-lockfileERR_PNPM_LOCKFILE_CONFIG_MISMATCHmeans hidden files such as.pnpmfile.cjswere lost while copying the folder. A permission error fromcorepack enable, orcorepacknot found? Set Up Your Computer shows the fixes.Check: The output ends with a line like
Done in … using pnpm v10.24.0. YellowWARNlines are normal. A line withERR_PNPMis not. - 1Windows: open the app folder in File Explorer, click the address bar, type
- 2
Make three random values
Posify needs three secrets:
BETTER_AUTH_SECRETsigns sessions,INSTALL_TOKENproves to the install wizard that you own this copy, andCRON_SECRETprotects the background jobs. Run the firstopensslcommand once and the second twice, and copy each result. Noopenssl? Run thenodecommand three times instead.With opensslbashopenssl rand -base64 48 # BETTER_AUTH_SECRET openssl rand -hex 32 # INSTALL_TOKEN, CRON_SECRETNo openssl (for example on Windows)? Node works everywherebashnode -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
Create the .env file
.envholds your settings. Start from.env.example: it has the optional variables commented out. Mail and storage can wait; Settings has a page for each.- 1Copy
.env.exampleto.envwith the first box below (macOS and Linux) or the second (Windows PowerShell). - 2Open
.envin a text editor:notepad .envon Windows,open -e .envon macOS,nano .envon Linux. - 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. - 4Delete the
ADMIN_PASSWORD=change-meline, sopnpm create-adminnever falls back to that password. Save the file.
macOS and Linuxbashcp .env.example .envWindows (PowerShell)powershellCopy-Item .env.example .env.env: change these linesbashDATABASE_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=andINSTALL_TOKEN=are no longer empty, andCRON_SECRETis no longerreplace-with-a-long-random-secret. - 1Copy
- 4
Create the tables
Posify never creates or changes tables by itself.
pnpm db:migratecreates every table in the empty database thatDATABASE_URLnames. Its first line names the database and the server it reached, so you can see it is the right one.bashpnpm db:migrate pnpm db:migrate --listpassword authentication failedmeans a wrong user or password inDATABASE_URL, or a password character that must be percent-encoded (@ : / # %).permission denied for schema publicmeans the user does not own the database: runALTER DATABASE posify OWNER TO posify;as thepostgresuser. More in Database Setup.Check: The first command ends with
Done: … applied; … in place., andpnpm db:migrate --listends with… applied, 0 pending.Running it again is harmless: it saysThe database is up to date. Nothing to apply. - 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 herebashpnpm build pnpm startOr: the development server, with no buildbashpnpm devPort 3000 taken? Start on another one withPORT=3001 pnpm start(PowerShell:$env:PORT = "3001"; pnpm start), and set both URL lines in.envtohttp://localhost:3001before you build. Running the App explains both ways to run.Check: The build ends with
check:chunks — … preloaded chunk references, all in .next.Thenpnpm startprints✓ Ready in …and Posify answers onhttp://localhost:3000. - 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.- 1System check: the Node.js, Database connection, Authentication secret and Installation token rows must pass; Application URL only warns. Paste your
INSTALL_TOKENvalue into Installation token, then press Continue. - 2About your business: Business name, Business email (optional), Default language, Currency, Time zone, and whether Prices include tax.
- 3Create the owner account: Your name, Email and Password. The owner holds every permission and cannot be removed or suspended by anyone else.
- 4Where media is stored: choose your storage provider, paste the bucket's keys and press Test connection, or tick Set storage up later.
- 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 changedNEXT_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.
- 1System check: the Node.js, Database connection, Authentication secret and Installation token rows must pass; Application URL only warns. Paste your
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).
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
| Component | Version | Notes |
|---|---|---|
| PostgreSQL | 16 or newer; tested on 17 | One 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.js | 24.11.0 or newer; 26 (LTS) recommended | The 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. |
| pnpm | 10.24.0 | Run corepack enable once; pnpm then uses the version package.json pins. Use pnpm only: the lockfile, pnpm-lock.yaml, is pnpm's. |
| Operating system | Linux, macOS or Windows | Posify's guides give commands for Debian and Ubuntu, macOS with Homebrew, and Windows PowerShell. The Docker image is based on node:24-bookworm-slim. |
| Browser | A modern browser on a computer, tablet or phone | The 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. |
| HTTPS | Required in production | Browsers 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). |
| Storage | One S3-compatible bucket | Cloudflare 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. |
| An SMTP account | For password resets, emailed receipts and notifications. Set it in Settings → Email or with the SMTP_* variables (Email / SMTP). | |
| Text messages | Optional: Twilio or another SMS gateway | For 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). |
| Chromium | Optional | A 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
| Path | Where the build runs | Build memory on your server | Notes |
|---|---|---|---|
| Your computer | On your computer | Several 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 image | On GitHub Actions | None | The server pulls the image and runs it. A volume at /app/.next/cache keeps the optimized images across deploys. |
| Deploy panel | On GitHub Actions | None | The panel runs the same image. Mount the same /app/.next/cache volume in the panel. |
| Node server | On the server | Several GB of RAM | On 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).
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
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:17image 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 databasebashsudo -u postgres psql -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'" sudo -u postgres createdb --owner=posify posifyUse a password of letters and digits only: it keeps the connection string simple.openssl rand -hex 24makes one. Put it in place ofa-strong-passwordin every command.Check: You have the database name, the user name and its password, and the server's address and port.
- 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:migrateand 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.1when PostgreSQL runs on the same machine; the container's name, such asposify-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=requireat the end for a server across the network. Managed databases usually include it: keep it.
The finished string looks like thistxtpostgresql://posify:a-strong-password@127.0.0.1:5432/posifyA password with@,:,/,#or%must be percent-encoded in the string, or the user and host are read wrong:@becomes%40,:%3A,/%2F,#%23and%%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=requirefor a managed database). - 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
opensslcommands work on macOS and Linux; thenodecommand works everywhere.- 1Open a terminal. Windows: press Start, type
powershelland press Enter. macOS: Applications → Utilities → Terminal. - 2Run
openssl rand -base64 48and save the line it prints asBETTER_AUTH_SECRET. - 3Run
openssl rand -hex 32and save the line asINSTALL_TOKEN. - 4Run
openssl rand -hex 32again and save the new line asCRON_SECRET. - 5No
openssl? Run thenodecommand instead, once for each of the three.
macOS and Linuxbashopenssl rand -base64 48 # BETTER_AUTH_SECRET openssl rand -hex 32 # INSTALL_TOKEN, CRON_SECRETWindows, macOS and Linux (uses Node.js)bashnode -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 suitsCRON_SECRETbest: 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.
- 1Open a terminal. Windows: press Start, type
- 4
Decide the address
BETTER_AUTH_URLandNEXT_PUBLIC_APP_URLboth 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.comandhttps://your-domain.comare two different addresses, so pick one.- Your computer
http://localhost:3000, as.env.exampleships it.- A live business
- Your domain or subdomain with
https://, for examplehttps://pos.your-domain.com. Point it at your server and give it HTTPS before you open the wizard: Domain & HTTPS.
NEXT_PUBLIC_APP_URLis 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 ishttp://localhost:3000), with nothing after the domain name. - 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.devaddress 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
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
587uses STARTTLS;465uses 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
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
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.
bashopenssl req -x509 -newkey rsa:2048 -nodes -days 3650 \ -keyout qz-private-key.pem -out qz-certificate.pem -subj "/CN=Your Business"Keepqz-private-key.pemsecret: whoever has it can send jobs to every till that trusts the certificate. Hardware shows how to put both into.envand set up each till.Check: You have two files,
qz-private-key.pemandqz-certificate.pem. - 9
Write down your environment values
Environment variables are the settings Posify reads when it starts: each one is a
NAME=valueline. 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)bashDATABASE_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.envinto a panel, never.env.exampleas it is: its placeholders count as real values.ADMIN_PASSWORD=change-mebecomes the passwordpnpm create-admingives, and theCRON_SECRETplaceholder 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
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.
- 1Your own computer, to try Posify: Set Up Your Computer.
- 2The prebuilt Docker image on your server: Docker Image.
- 3Dokploy or another deploy panel: Dokploy & Panels.
- 4A Node server you run yourself: Node Server.
- 5Not sure yet? Compare the paths in Choose Your Path.
- 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.
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
Install Node.js 26
Node.js runs Posify. It needs version 24.11.0 or newer; install 26 (LTS), the version
.nvmrcnames and the one the Docker image uses.- 1Open nodejs.org/en/download.
- 2Pick a version that starts with
v24. The labels on the page may differ slightly. - 3Windows: download the Windows Installer (.msi). macOS: download the macOS Installer (.pkg). Run it and keep the default options.
- 4Linux: follow the instructions the same page gives for your system, with version 24.
- 5Close every terminal window that is open, then open a new one. Windows: press Start, type
powershelland press Enter. macOS: Applications → Utilities → Terminal. - 6Run
node -v.
Check the versionbashnode -vAlready have Node.js? Ifnode -vprintsv24.11.0or higher, keep it and go to the next step.Check:
node -vprintsv26and more numbers. Any version fromv24.11.0works; the install wizard's System check refuses an older one. - 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.jsonnames: 10.24.0. You turn it on once.- 1Run
corepack enablein any terminal. - 2Permission error? On Windows, press Start, type
powershell, right-click Windows PowerShell → Run as administrator, and run it there. On macOS or Linux, runsudo corepack enable. - 3
corepacknot recognized or not found? Node.js 25 and newer no longer include it. Runnpm install -g corepackfirst, thencorepack enable.
bashcorepack enableCheck:
corepack enableprints nothing when it works. You check the pnpm version in the app folder, in the last step. - 1Run
- 3
Install PostgreSQL on Linux (Debian, Ubuntu)
Posify needs PostgreSQL 16 or newer.
aptinstalls your distribution's version: Ubuntu 24.04 ships 16 and Debian 13 ships 17, which are fine. Then create a userposifyand an empty databaseposifythat the user owns. Put your own password in place ofa-strong-password: letters and digits only keep the connection string simple.1. Install, then check the versionbashsudo apt install postgresql psql --version2. Create the user and the databasebashsudo -u postgres psql -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'" sudo -u postgres createdb --owner=posify posifyDebian 12 (PostgreSQL 15) and Ubuntu 22.04 (14) are too old. Add the PostgreSQL project's own repository first (postgresql.org/download/linux), then runsudo apt install postgresql-17.Check:
psql --versionprints 16 or newer. TheCREATE ROLEcommand printsCREATE ROLE, andcreatedbprints nothing. - 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.- 1Run the two commands in the first box.
- 2
postgresql@17does not put its tools on your PATH. Runbrew info postgresql@17, add the folder it names to your PATH, then open a new terminal. - 3Run the commands in the second box, with your own password in place of
a-strong-password.
1. Install and start PostgreSQL 17bashbrew install postgresql@17 brew services start postgresql@172. Create the user and the databasebashpsql postgres -c "CREATE ROLE posify LOGIN PASSWORD 'a-strong-password'" createdb --owner=posify posifyCheck: The
psql postgrescommand printsCREATE ROLE, andcreatedbprints nothing. - 5
Install PostgreSQL on Windows
Install PostgreSQL with the installer from postgresql.org/download/windows. It runs PostgreSQL as a Windows service (
postgresql-x64-17for version 17) and asks you for a password for thepostgressuperuser. Its tools are inC:\Program Files\PostgreSQL\17\bin, which it does not add to your PATH, so the commands below name that folder.- 1Run the installer, and save the
postgrespassword you set in it. - 2Open PowerShell and run the three lines below, with your own password in place of
a-strong-password.
PowerShell: create the user and the databasepowershell$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 posifyEach command asks for thepostgrespassword you set in the installer.Check:
psql.exeprintsCREATE ROLE, andcreatedb.exeprints nothing. - 1Run the installer, and save the
- 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 namedposify-pg-data.macOS and Linuxbashdocker 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:17Windows PowerShell: the same command on one linepowershelldocker 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:17Keep the image on one major version (postgres:17, neverlatest): a newer major version cannot open the older one's data without an upgrade.Check:
docker pslistsposify-pgwith a status that starts withUp. - 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.
- 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.
- 2Unzip the file into a new folder. Windows: right-click it → Extract All… → Extract. macOS: double-click it. Linux: run
unzipfollowed by the file name. - 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.exampleandnext.config.ts. - 4Move the app folder to a place you will keep, for example
C:\posifyon Windows or aposifyfolder in your home folder. - 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,.dockerignoreand the.githubfolder, which holds the workflow that builds the Docker image. Keeppnpm-workspace.yamlandpnpm-lock.yamltoo. Without.pnpmfile.cjsthe install stops withERR_PNPM_LOCKFILE_CONFIG_MISMATCH.Check: Inside the app folder you see
package.json,pnpm-lock.yaml,pnpm-workspace.yaml,.pnpmfile.cjs,.nvmrcand.env.example. Files that start with a dot missing? Turn on hidden files and look again; still missing, download the zip again. - 8
Open a terminal in the app folder
From here on, every command runs inside the app folder, the one with
package.json.- 1Windows: open the app folder in File Explorer, click the address bar, type
powershelland press Enter. PowerShell opens in that folder. - 2macOS: open Terminal, type
cdand a space, drag the app folder from Finder into the window, then press Enter. - 3Linux: right-click inside the folder in your file manager → Open in Terminal, or
cdinto it.
Check that you are in the right folderbash# Windows (PowerShell) dir package.json # macOS or Linux ls package.jsonCheck: The command lists
package.json.Cannot find pathorNo such file or directorymeans you are in the wrong folder. - 1Windows: open the app folder in File Explorer, click the address bar, type
- 9
Install the packages
Check the pnpm version first. Then pnpm downloads everything Posify needs into a new
node_modulesfolder;--frozen-lockfileinstalls exactly the versions inpnpm-lock.yaml. The first install downloads a lot.- 1Run
pnpm -v. The first time, Corepack may say it is about to download pnpm and askDo you want to continue? [Y/n]. TypeYand press Enter. - 2Run
pnpm install --frozen-lockfileand wait until you can type again.
bashpnpm -v pnpm install --frozen-lockfileERR_PNPM_LOCKFILE_CONFIG_MISMATCHmeans hidden files such as.pnpmfile.cjswere lost while copying: unzip the download again with hidden files shown. Ifpnpm -vdoes not print10.24.0, runcorepack enableagain and open a new terminal.Check:
pnpm -vprints10.24.0, and the install ends with a line likeDone in … using pnpm v10.24.0. Anode_modulesfolder now sits next topackage.json. YellowWARNlines are normal; a line withERR_PNPMis not. - 1Run
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.
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-lockfilefinished 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
| Variable | Local value (.env) | Live value |
|---|---|---|
| DATABASE_URL | postgresql://posify:a-strong-password@127.0.0.1:5432/posify | Your server's string, or the one your provider gives you, usually ending with ?sslmode=require |
| BETTER_AUTH_SECRET | A random value of 32+ characters, from openssl rand -base64 48 | The same kind of value |
| BETTER_AUTH_URL | http://localhost:3000 | https://pos.your-domain.com: the exact address people open |
| NEXT_PUBLIC_APP_URL | http://localhost:3000 | The same address as BETTER_AUTH_URL. Built into the app: rebuild after a change |
| INSTALL_TOKEN | A random value of 32+ characters, from openssl rand -hex 32 | The same kind of value |
| CRON_SECRET | 16+ random characters; openssl rand -hex 32 is better | The 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
| Group | Variables | When you need them |
|---|---|---|
| Database | DATABASE_URL; commented out: DATABASE_POOL_MAX, DATABASE_DEBUG, RATE_LIMIT_STORE, TRUSTED_PROXIES | Always. The commented ones are optional. |
| Authentication and app | BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL | Always. |
| Installer | INSTALL_TOKEN | For a new business. Only the install wizard uses it. |
| Scheduled jobs | CRON_SECRET | For the background jobs. |
| Demo mode | DEMO_MODE, commented out | Only for a public demo. |
| Owner account | ADMIN_NAME, ADMIN_PASSWORD | Fallbacks for pnpm create-admin. |
| Email (SMTP) | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, commented out | For email, unless you set it in Settings → Email. |
| SMS through Twilio | TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_MESSAGING_SERVICE_SID, TWILIO_FROM_NUMBER, commented out | Optional; Settings → SMS (Twilio) can hold them instead. |
| Object storage | The STORAGE_* variables, commented out | For uploads, unless you set storage in the wizard or in Settings → Storage Settings. |
| QZ Tray | QZ_TRAY_CERTIFICATE, QZ_TRAY_PRIVATE_KEY, commented out | Optional, for printing with no dialog and for the cash drawer. |
| Build and cache | BUILD_MAX_CPUS, BUILD_SOURCE_MAPS, PAGE_CACHE_MEMORY_MB, IMAGE_CACHE_DISK_MB, commented out | Optional; 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
Make the random values
BETTER_AUTH_SECRET,INSTALL_TOKENandCRON_SECRETneed long random values. Use the ones you made in "Generate your secrets" in Before You Install, or make them now.With opensslbashopenssl rand -base64 48 # BETTER_AUTH_SECRET openssl rand -hex 32 # INSTALL_TOKEN, CRON_SECRETNo openssl (for example on Windows)? Node works everywherebashnode -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 suitsCRON_SECRETbest: crontab treats%as a special character, and a hex secret has none.Check: Each run prints a different line of 64 characters.
- 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 Linuxbashcp .env.example .envWindows (PowerShell)powershellCopy-Item .env.example .envWindows can hide file extensions, so a file saved as.env.txtstill looks like.envin File Explorer. Posify ignores that file. The check below shows the real name.Check:
dir .env(Windows) orls -a .env(macOS and Linux) lists a file named exactly.env, next topackage.json. - 3
Fill in your values
Open
.envin a text editor:notepad .envon Windows,open -e .envon macOS,nano .envon Linux. Change the six lines in the box below, replacing each<…>placeholder, the<and>too, and save..env (local)bashDATABASE_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.exampleshipsADMIN_PASSWORD=change-me. Left in.env,change-mebecomes the passwordpnpm create-admingives when you type none. Delete the line, or change it to a strong password.Check: No
CHANGE_ME,<or>is left,BETTER_AUTH_SECRET=andINSTALL_TOKEN=are filled, andCRON_SECRETis no longerreplace-with-a-long-random-secret. Later, the wizard's System check shows the Authentication secret and Installation token rows passed. - 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.envinstead, remove the#and put in your real values.- 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_CERTIFICATEandQZ_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 assmtp.example.comoryour-bucket-name: Posify treats any value there as a real setting. - 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
.envfile 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
.envinto it. See Dokploy & Panels. - GitHub, for the image
NEXT_PUBLIC_APP_URLalso 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.exampleas it is. Its placeholders count as real values: theCRON_SECRETplaceholder makes every background job answer 401, andADMIN_PASSWORD=change-mebecomes the passwordpnpm create-admingives.Check: Every variable from the first table is set, spelled exactly as shown, and no value still contains
<,>orCHANGE_ME. - 6
Rebuild after changing NEXT_PUBLIC_APP_URL
NEXT_PUBLIC_APP_URLis written into the app when it is built. Changing it in.envafterwards changes nothing until you build again.- Your computer
- Stop the app with Ctrl+C, run
pnpm build, thenpnpm start.pnpm devpicks 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_URLmust 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.
| Key | Required | Description |
|---|---|---|
DATABASE_URL | Required | The 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_MAX | Optional | Connections 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_DEBUG | Optional | true logs every SQL statement and its parameters. Development only: never in production. Commented out in .env.example. |
RATE_LIMIT_STORE | Optional | Where 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_PROXIES | Optional | Only 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_SECRET | Required | Signs 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_URL | Required | The 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_URL | Required | The 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_TOKEN | Required | Required 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_SECRET | Required | Required 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_MODE | Optional | true (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_NAME | Optional | The name pnpm create-admin gives a new account when you type none. Unset, the part of the email before @. .env.example sets Owner. |
ADMIN_PASSWORD | Optional | The 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_HOST | Optional | Your 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_PORT | Optional | 587 uses STARTTLS, 465 uses TLS. Default 587. |
SMTP_USER | Optional | Your SMTP user name. Email from .env alone is sent only when SMTP_USER and SMTP_PASS are both set. |
SMTP_PASS | Optional | Your SMTP password. |
SMTP_FROM | Optional | The sender, for example "Your Business <no-reply@example.com>". In a Docker env file, write it without the quotes. |
TWILIO_ACCOUNT_SID | Optional | Your 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_TOKEN | Optional | Your Twilio auth token. |
TWILIO_MESSAGING_SERVICE_SID | Optional | A Twilio Messaging Service (it starts with MG). Set this or TWILIO_FROM_NUMBER; this one is preferred when you have one. |
TWILIO_FROM_NUMBER | Optional | A Twilio number in international form, for example +15551234567, or a sender ID. Used when you have no Messaging Service. |
STORAGE_ACCESS_KEY_ID | Optional | The 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_KEY | Optional | The bucket's secret key. |
STORAGE_ACCOUNT_ID | Optional | Cloudflare R2 only: your R2 account ID. |
STORAGE_ENDPOINT | Optional | MinIO: your server's S3 API URL. Leave it blank for AWS S3. |
STORAGE_REGION | Optional | AWS 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_BUCKET | Optional | The bucket name. |
STORAGE_PUBLIC_URL | Optional | The 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_CERTIFICATE | Optional | The 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_KEY | Optional | The 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_CPUS | Optional | Caps 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_MAPS | Optional | true adds server-side source maps to the build. Off by default. |
PAGE_CACHE_MEMORY_MB | Optional | Memory, 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_MB | Optional | Disk, in MB, for optimized images in .next/cache/images. The least recently used go first. Default 1024. |
CHROME_PATH | Optional | Not 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_MODE | Optional | Not 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_NAME | Optional | Not in .env.example. The sender name in emails and texts while the business has no name in Settings → General Settings. |
NEXT_PUBLIC_SUPPORT_EMAIL | Optional | Not in .env.example. An address the "no access" page offers for help. |
CLOUDFLARE_R2_PUBLIC_URL | Optional | Not 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_SECRET | Optional | Not 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.
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
.envfile in the app folder (Environment Variables). pnpm install --frozen-lockfilefinished in the app folder.
Where PostgreSQL can run
| Option | DATABASE_URL | Notes |
|---|---|---|
| On the same machine | postgresql://posify:a-strong-password@127.0.0.1:5432/posify | Linux, macOS or Windows, installed as in Set Up Your Computer. |
| Docker, app on the host | postgresql://posify:a-strong-password@127.0.0.1:5432/posify | The posify-pg container publishes port 5432 on 127.0.0.1 only. |
| Docker, app in another container | postgresql://posify:a-strong-password@posify-pg:5432/posify | Put 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 database | The string the provider gives you | Neon, Supabase, AWS RDS, DigitalOcean and others, on version 16 or newer. Keep the ?sslmode=require it usually ends with. |
The database commands
| Command | What it does | Writes? |
|---|---|---|
| pnpm db:migrate | Creates and updates Posify's tables | Yes; not with --list or --dry-run |
| pnpm db:seed | A small demo business with three demo sign-ins | Yes |
| pnpm db:seed --template=demo | The full demo business, with up to 30 days of trading | Yes |
| pnpm db:seed:audit | Checks a demo database's books and stock | No |
| pnpm db:reset | Deletes every record in Posify's tables | Yes, everything |
| pnpm create-admin | Creates or restores an owner account (Backups & Recovery) | Yes |
| pnpm accounting:reconcile | Checks 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
Put the connection string in .env
DATABASE_URLholds the connection string, in the formpostgresql://USER:PASSWORD@HOST:PORT/DATABASE. Set it in.envand save. If the app is running, restart it.- Port
5432is 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=requireat the end: it usually wants TLS. Itslisten_addressesandpg_hba.confdecide whether it accepts the app's connections. Keep it closed to the internet, and open it only to the app's address.
.envbashDATABASE_URL=postgresql://posify:a-strong-password@127.0.0.1:5432/posifyCheck: The line starts with
DATABASE_URL=postgresql://, has no spaces, and names your user, password, host, port and database. - 2
Managed database: pick the right string
Some providers give two strings: a pooled one (PgBouncer, Supabase's pooler, Neon's
-poolerhost) and a direct one. The app works through either; use the pooled one when you run many app instances. Runpnpm db:migrateover the direct one, by putting it in front of the command.macOS and LinuxbashDATABASE_URL="postgresql://…direct…" pnpm db:migrateWindows (PowerShell)powershell$env:DATABASE_URL = "postgresql://…direct…"; pnpm db:migrateIn PowerShell the value stays set until you close that terminal or runRemove-Item Env:DATABASE_URL. Do one of the two before you run anything else there. - 3
Check the connection
Before you create the tables, check that the string works and that the server is new enough.
psqlcomes with PostgreSQL. On Windows it is inC:\Program Files\PostgreSQL\17\bin; on macOS, add Homebrew's folder to your PATH first, as in Set Up Your Computer.bashpsql "postgresql://posify:a-strong-password@127.0.0.1:5432/posify" -c "SELECT version()" -c "SHOW server_encoding"NotUTF8? Create the database again withcreatedb --encoding=UTF8 --template=template0 --owner=posify posify.Check: You see PostgreSQL 16 or newer, and
UTF8. - 4
See what will be applied
Posify's tables come from the SQL migrations in
lib/pg/migrations, one folder per change.pnpm db:migrateapplies the ones your database does not have yet, oldest first, and records each one. These two flags look without writing anything.bashpnpm db:migrate --list # every migration: applied (and when) or pending pnpm db:migrate --dry-run # the pending ones; writes nothingCheck: 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
Create the tables
Run
pnpm db:migrateonce on the empty database, before the first start. Every pending migration is applied in one transaction: all of them, or none.bashpnpm db:migrateThe 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., andpnpm db:migrate --listnow ends with… applied, 0 pending. - 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_URLmust own the database: runALTER DATABASE posify OWNER TO posify;as thepostgresuser. - 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
Optional: load the small demo business
pnpm db:seedsets 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 theTZenvironment variable, else UTC; change it later in Settings → General Settings.bashpnpm 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.--forceseeds 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) andcashier@example.com/Cashier@123(Cashier). - 8
Optional: load the full demo business
pnpm db:seed --template=demowrites 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, runpnpm db:migratefirst 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.- 12 branches and 3 registers.
- 27 people in six of the built-in roles. Only the three demo sign-ins can sign in.
- 38 categories, 60 products and 26 variants, every one with a barcode, plus 2 units and 2 tax groups.
- 45 suppliers and 40 customers. Their phone numbers use the
010prefix, which no mobile operator serves, so a text sent to one reaches nobody. - 5Marketing already in use: customers with their consent to offers and their birthdays, three offer templates in English and Bangla, two segments, the coupon
PLAT10and two finished campaigns with their results. The automations are off. Nothing in the demo is really sent. - 630 days of trading up to today, or what
--daysasks for (1 to 30): sales, returns, purchase orders, goods receipts, supplier bills and payments, expenses, transfers between branches and customer receipts. - 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.
bashpnpm 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 setDEMO_MODE=trueand 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, thenSign in with:and the three demo sign-ins. - 9
Optional: check a demo database
pnpm db:seed:auditchecks a database made bypnpm db:seed --template=demoagain: 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
--no-history: check only the demo records and the credentials, not the books, stock and history. - 2
--no-coverage: skip the check that every kind of event happened; useful after a short--dayshistory. - 3
--json: print the whole report as JSON.
bashpnpm db:seed:audit pnpm db:seed:audit --no-history pnpm db:seed:audit --jsonCheck: Every line starts with
✓, and the command exits with code 0. A✗line names the check that failed, and the exit code is 1. - 1
- 10
Empty a test database
pnpm db:resetdeletes 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 runpnpm db:migrateagain, and the document counters start again from the beginning. Any other table in the database is left untouched and listed at the end.bashpnpm db:resetIt deletes data and does not ask first. Check which databaseDATABASE_URLin.envnames before you press Enter. A listed table that is not Posify's usually means a shared database, or that.envnames the wrong one.Check: The output ends with
Database reset completed successfully!andTotal 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.
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-lockfilefinished in the app folder. - Your
.envfile sits next topackage.json, with the values from Environment Variables. - The tables exist:
pnpm db:migrateran against the database inDATABASE_URL(Database Setup).
Running the app
| Script | What it does |
|---|---|
| pnpm dev | A development server on http://localhost:3000. No offline till. |
| pnpm build | The production build. It skips the type check on purpose, and ends by checking the pages' preload lists (check:chunks), repairing what it can. |
| pnpm start | The production server, on port 3000 unless PORT says otherwise. |
Database and maintenance
| Script | What it does |
|---|---|
| pnpm db:migrate | Creates 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-admin | pnpm create-admin <email> [password] [name] [--reset-2fa] creates or restores an owner account. |
| pnpm accounting:reconcile | Checks the books against the documents and posts any journal that is missing. --dry-run writes nothing. |
| pnpm db:seed | A 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=demo | The full demo business with 30 days of trading. Wants an empty database. |
| pnpm db:seed:audit | Checks a demo database: the books balance and the stock adds up. Reads only. |
| pnpm db:reset | Deletes 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
| Script | What it does |
|---|---|
| pnpm typecheck | The type check. pnpm build skips it, so run this before you ship a change. |
| pnpm lint | ESLint, errors only. |
| pnpm test | The unit tests (Vitest). |
| pnpm check:i18n | Every language file has every key of locales/en.json, with the same arguments. |
| pnpm check:chunks | After a build: every script a page preloads exists. |
| pnpm check:build-db | Builds with the database address pointed at a counter: the build must make no database connection. |
- 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.
- 1Open a terminal in the app folder, the folder with
package.json. - 2Run
pnpm dev. - 3Wait for the line that starts with
✓ Ready in, and leave the window open.
bashpnpm devPort 3000 is in use … using available port 3001 insteadmeans another program has port 3000, often an olderpnpm dev. Close it, press Ctrl+C here and runpnpm devagain: your.envaddresses say port 3000.Check: The
Local:line showshttp://localhost:3000, theEnvironments:line lists.env, and✓ Ready in …appears. NoEnvironments:line? Posify did not find your.env: check that it sits next topackage.jsonand is not named.env.txt. - 1Open a terminal in the app folder, the folder with
- 2
Open Posify in your browser
Open
http://localhost:3000. Typelocalhost, 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. Openhttp://localhost:3000/installyourself: the Database connection row names the fix. If/installanswers "not found", this database already holds a business, for example frompnpm db:seed: sign in athttp://localhost:3000/logininstead.Check: The address changes to
http://localhost:3000/install, and the page says "Set up your business", with "System check" below it. - 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
.envarehttp://localhost:3000. No bucket yet? Tick Set storage up later on the storage step.Do not runpnpm create-adminorpnpm db:seedbefore 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
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.
- 1Stop
pnpm devwith Ctrl+C: the production server needs port 3000 too. - 2Run
pnpm buildand wait until it finishes. - 3Run
pnpm start, then openhttp://localhost:3000.
Build, then startbashpnpm build pnpm startThe build never connects to the database, so it works while PostgreSQL is stopped; start the database beforepnpm start.pnpm startwithout a build stops withCould not find a production build.Check: The build ends with
check:chunks — … preloaded chunk references, all in .next.pnpm startprints✓ Ready in …, andhttp://localhost:3000opens Posify. - 1Stop
- 5
Use another port
Posify listens on port 3000. To use another one, set
PORTin the command itself: the port is chosen before.envis read, so aPORTline in.envdoes nothing.macOS and LinuxbashPORT=3001 pnpm startWindows (PowerShell)powershell$env:PORT = "3001"; pnpm startChange both URL values in.envto the new address, for examplehttp://localhost:3001, and runpnpm buildagain. Otherwise the wizard's Application URL row warns, and links in emails point at the old address. - 6
Check types and run tests (people who change the code)
You need this only if you change the code.
pnpm buildskips the type check on purpose, so run these before you ship a change.bashpnpm typecheck pnpm lint pnpm test pnpm check:i18nLow on memory for the type checkbashNODE_OPTIONS=--max-old-space-size=8192 ./node_modules/.bin/tsc --noEmit -p tsconfig.check.jsonCheck: Each command finishes without listing errors.
- 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 seeTerminate batch job (Y/N)?. TypeYand press Enter.Check: The terminal shows its prompt again, and
http://localhost:3000no 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).
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/Dockerfilenever 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:migratein 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
| File | What it does |
|---|---|
| .github/workflows/deploy-image.yml | On 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/Dockerfile | Assembles 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. |
| .dockerignore | Keeps 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
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
mainbranch, without.env,node_modulesor.next.- 1Show hidden files before you copy anything: the workflow is in
.github, and.dockerignorestarts with a dot too. Windows Explorer: View → Show → Hidden items. macOS Finder: Cmd+Shift+. (full stop). - 2To build from other branches as well, add them under
on: push: branches:in.github/workflows/deploy-image.yml.
Never commit a.envfile: it holds your secrets. The server keeps its own env file (step 6).Check: The repository's
mainbranch shows.github,deployandpackage.jsonat its top level. - 1Show hidden files before you copy anything: the workflow is in
- 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 withSet 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_URLwith your address. - 3
Add Chromium for PDF exports (optional)
The
deploy/Dockerfileas 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 afterRUN corepack enableindeploy/Dockerfile, and commit the change before the first build.- 1The Noto fonts let Bengali, Hindi, Arabic, Chinese and Japanese text print instead of empty boxes.
- 2The image gets larger. The container runs as root; Posify then starts Chromium with
--no-sandboxitself. - 3Adding it later works the same way: change the file, push, and run the new image.
deploy/DockerfiledockerfileRUN 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/chromiumCheck: Once the app runs: Statements → Profit and loss → PDF downloads a PDF.
- 4
Build the first image
Push to
main, or open the Actions tab → Deploy image → Run workflow. The run installs the packages, runspnpm typecheck, builds the app and pushes the image.- 1Wait for the green check. If you changed the code and the type check fails, no image is pushed.
- 2Open your GitHub account's (or organization's) Packages: the image is there, private by default.
- 3Each run tags the image twice:
main, and its short commit SHA, for example8a45278. 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
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:packagesscope.- 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. - 2On the server, run the command below with your token and your GitHub user name.
bashecho "YOUR-TOKEN" | docker login ghcr.io -u YOUR-GITHUB-USER --password-stdinWhen the token expires,docker pullis refused. Make a new token and log in again.Check: Docker prints
Login Succeeded. - 1On GitHub: your profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Tick only
- 6
Write the env file
The container reads its settings from an env file on the server:
/opt/posify/.envin these examples. Start from.env.examplein the download and fill it in as Environment Variables explains.- 1
--env-filereads each value literally. Write values without quotes:SMTP_FROM=Your Business <no-reply@example.com>, notSMTP_FROM="Your Business <no-reply@example.com>". The same goes for the one-lineQZ_TRAY_*values. - 2
NEXT_PUBLIC_APP_URLmust equal the GitHub variable from step 2, andBETTER_AUTH_URLmust be the same address. - 3
DATABASE_URLmust be reachable from inside the container. There,127.0.0.1is the container itself (step 7).
Check: The file holds your own values, with no quotes around them and no placeholder left.
- 1
- 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.- 1Replace
a-strong-passwordin both places. Letters and digits only keep the connection string simple. - 2Add
--network posifyto thedocker runcommands in steps 8 and 9. - 3Keep the image on one major version (
postgres:17, neverlatest): a newer major version cannot open the older one's data without an upgrade.
A Docker network and PostgreSQL 17 on itbashdocker 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:17The matching line in /opt/posify/.envbashDATABASE_URL=postgresql://posify:a-strong-password@posify-pg:5432/posifyCheck:
docker pslistsposify-pgwith a status that starts withUp. - 1Replace
- 8
Pull the image and create the tables
Run
pnpm db:migrateonce, in a one-off container, before the app starts. It readsDATABASE_URLfrom the env file, like the app does.- 1Write your account and repository names in lowercase, as the Packages page shows them.
- 2With the network from step 7, write
--network posifyafter--rm.
bashdocker 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:migrateCheck: The first line names the database and server it reached, for example
db:migrate — posify on posify-pg:5432, and the run ends with aDone:line. - 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.
- 1With the network from step 7, add
--network posifyto the first line. - 2
-p 127.0.0.1:3000:3000keeps the app's port private. Only a reverse proxy on the server reaches it. - 3The volume at
/app/.next/cachekeeps optimized images across deploys, so they are not made again after every update. - 4In PowerShell, put the whole command on one line, or end each line with a backtick instead of
\.
bashdocker 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:mainDocker reads the env file when it creates the container. After you change the file, rundocker rm -f posifyand thedocker runcommand again:docker restartkeeps the old values.Check:
docker psshowsposifywith a status that starts withUp, andcurl -I http://127.0.0.1:3000answers307with alocationthat ends in/install. - 1With the network from step 7, add
- 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.comopens with a padlock and shows the install wizard. - 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
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
Run commands inside the container
pnpm db:migratereadsDATABASE_URLfrom the container's environment. The other database commands read a.envfile, which the image does not hold, so create an empty one first. The container's environment still supplies every value.- 1
posifyis the app container's name in these examples. - 2Each
docker runmakes a new container without the empty.env: runtouch .envagain after an update. - 3The image has no
pg_dump. Take backups from the host or from the database's own container (Backups & Recovery).
bashdocker 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-runCheck:
pnpm db:migrate --listends with… applied, 0 pending. - 1
- 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.
- 1Add
--network posifyto bothdocker runcommands if you use that network. - 2The migrations run in the one-off container before the new app starts.
- 3Then turn maintenance mode off.
bashdocker 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: … — balancedandDry run: nothing was written. - 1Add
- 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.bashdocker 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-SHAIf 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).
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:migratein 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_URLvariable, 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:packagesscope (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
.envvalues (Environment Variables), and a domain you can point at the server (Domain & HTTPS).
- 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:packagesscope.
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.ioregistry. - 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.ioregistry from step 1.
If the panel has a field for the container's command, leave it empty. The image starts the app withpnpm start; anything typed there replaces it.Check: The application shows the image with the tag
main. - 3
Copy the runtime variables
Copy every runtime variable from your
.envinto the application's environment in the panel. The container reads its settings from there: the image holds no.envfile.- 1
NEXT_PUBLIC_APP_URLmust equal the GitHub variable. Changing it in the panel does not change the image: change the GitHub variable, run the workflow, then redeploy. - 2
BETTER_AUTH_URLmust be the same address. - 3
DATABASE_URLmust be reachable from inside the container, where127.0.0.1is the container itself. Use the address the panel gives its database service, or your managed database's connection string. - 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_TOKENandCRON_SECRET, with your values. - 1
- 4
Set the port and the cache volume
The container listens on port 3000. A volume at
/app/.next/cachekeeps 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
3000and a volume mounted at/app/.next/cache. - 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, soTRUSTED_PROXIESstays unset.Check: After the first deploy (next step),
https://pos.example.comanswers with a padlock. - 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
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".bashcd /app pnpm db:migrateCheck: The first line names the database and server it reached, and the run ends with a
Done:line. - 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
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
Redeploy after each new image
Every push to
mainbuilds 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.deployto 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
Run the migrations after an update
An update that brings migrations needs
pnpm db:migratein 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.- 1Settings → Maintenance Mode: turn on Enable Maintenance Mode, add your own IP address under Allowlisted IP addresses, and click Save Maintenance Settings.
- 2Back up the database (Backups & Recovery).
- 3Push the release, and redeploy once the run is green (or let the workflow do it).
- 4In the container's terminal:
cd /app && pnpm db:migrate, thentouch .env && pnpm accounting:reconcile --dry-run. - 5Turn maintenance mode off.
Check:
pnpm db:migrate --listends with… applied, 0 pending., and the reconcile ends withDry run: nothing was written. - 12
Run other commands in the terminal
pnpm create-adminandpnpm accounting:reconcileread a.envfile, 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.bashcd /app touch .env pnpm create-admin you@example.com "a-new-password" pnpm accounting:reconcile --dry-runThe image has nopg_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.
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:migratebefore the first start and after every update: the app never creates or changes its tables. NEXT_PUBLIC_APP_URLis built into the app. After you change it, runpnpm buildagain, 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 (
.nvmrcnames 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
.envin 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
| Setting | Default | What it controls |
|---|---|---|
| BUILD_MAX_CPUS | one worker per core | Workers 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_MB | 50 | Memory 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_MB | 1024 | Disk for optimized images in .next/cache/images. The least recently used go first. |
| DATABASE_POOL_MAX | 10 | Database 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_STORE | the database | Where 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
Install, migrate and build
From the app's folder, enable Corepack, install the packages, create the tables in the database
.envnames, and build.- 1
corepack enablegives you the pnpm versionpackage.jsonpins (10.24.0). - 2On 8 GB of RAM or less, build with
BUILD_MAX_CPUS=2 pnpm build, or putBUILD_MAX_CPUS=2in.env. - 3
pnpm startruns 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, on127.0.0.1only.
bashcd /opt/posify corepack enable pnpm install --frozen-lockfile pnpm db:migrate pnpm build pnpm startThe build makes no database connection, so a wrongDATABASE_URLonly shows once the app runs.Check:
pnpm db:migratenames the database and server on its first line and ends with aDone:line. The build ends withcheck:chunks — … preloaded chunk references, all in .next. - 1
- 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
WorkingDirectoryis the app's folder. The app reads.envfrom there. - 2
ExecStartneeds the full path tonode:which nodeshows it (with nvm it is under your home folder). - 3
Useris the account that owns/opt/posify.
/etc/systemd/system/posify.serviceini[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.targetThenbashsudo systemctl daemon-reload sudo systemctl enable --now posify journalctl -u posify -f # the app's logThe unit starts the app on127.0.0.1only, so nobody reaches it without the proxy.Check:
systemctl status posifyshowsactive (running), andcurl -I http://127.0.0.1:3000answers307with alocationthat ends in/install. - 1
- 3
Or keep it running with pm2
Use pm2 instead of systemd if you prefer it. From the app's folder:
bashpm2 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 bootpm2 startuponly prints a command. Run that command too, or pm2 does not start after a reboot.Check:
pm2 listshowsposifyasonline. - 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, withpos.example.comreplaced by your domain, then reload the proxy.- 1nginx: get the certificate with Certbot or your provider. On nginx older than 1.25.1, write
listen 443 ssl http2;instead of thehttp2 on;line. - 2nginx:
client_max_body_sizemust be at least the largest file size set in Settings → Storage Settings, because uploads pass through the app. - 3Caddy needs the domain to point at the server before it can get the certificate.
nginxnginxserver { 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)txtpos.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, setTRUSTED_PROXIES(Domain & HTTPS).Check:
https://pos.example.comopens with a padlock and shows the install wizard. - 1nginx: get the certificate with Certbot or your provider. On nginx older than 1.25.1, write
- 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.
- 1A Linux server needs the Noto fonts too, or Bengali, Hindi, Arabic, Chinese and Japanese text prints as empty boxes.
- 2Posify looks at
CHROME_PATHfirst. Otherwise, on Linux:/usr/bin/chromium,/usr/bin/chromium-browser,/usr/bin/google-chrome,/usr/bin/google-chrome-stable,/snap/bin/chromiumand/usr/bin/microsoft-edge. - 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. - 4Set
CHROME_PATHin.envonly when yours is somewhere else. At most two browsers print at once; each closes when its file is done.
Debian / Ubuntubashsudo apt-get install -y chromium fonts-noto-core fonts-noto-cjkAlpinebashapk add chromium font-noto font-noto-bengali font-noto-arabic font-noto-devanagari font-noto-cjkCheck: Once the app runs and you are signed in: Statements → Profit and loss → PDF downloads a PDF.
- 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
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
Update to a new release
Follow Updates & Migrations: unzip the new release into a new folder, copy
.envacross, 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.- 1systemd: change
WorkingDirectoryin/etc/systemd/system/posify.serviceto the new folder, then runsudo systemctl daemon-reloadandsudo systemctl restart posify. - 2pm2: run
pm2 delete posify, then thepm2 startcommand from the new folder, thenpm2 save.
Check:
systemctl status posify(orpm2 list) shows the app running from the new folder. - 1systemd: change
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).
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,
/installanswers "not found" for good. That is the lock, not a fault. pnpm create-adminandpnpm db:seedalso 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:migratehas run on its database: the wizard's database check reads Posify's tables. - In
.env(or the panel's environment):DATABASE_URL,BETTER_AUTH_SECRETandINSTALL_TOKEN(each of the two at least 32 random characters), andNEXT_PUBLIC_APP_URLandBETTER_AUTH_URLset 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 Posify | Where the value is | After 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 image | The 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 panel | The 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
| Item | What you get |
|---|---|
| The business | Its settings: the name, email, default language, currency, time zone and whether prices include tax, and the storage bucket if you entered one. |
| The owner account | Your account, on the Administrator role and marked as the owner: every permission, and nobody else can remove or suspend it. |
| Roles | The preset roles: Administrator, Manager, Cashier, Accountant, Stock Keeper, Purchaser, Supervisor, Read-only and External Accountant. |
| Main Branch | One branch, code MAIN, that sells at the counter, holds stock and accepts returns. |
| Counter 1 | One register at Main Branch, code R1. |
| Units | Piece, Box, Pack, Dozen, Kilogram, Gram, Litre, Millilitre and Metre. |
| Chart of accounts | The system accounts the journals post to, and the first expense categories. |
| Sample data | Only 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
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/installyourself: 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
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.
- 1Node.js (the row shows your version): 24.11 or newer, or the row says "Node.js 24.11 or newer is required".
- 2Database connection: it must reach PostgreSQL and read Posify's tables. A row that fails names the cause:
DATABASE_URLnot set, a server that did not answer, a refused user or password, a database that does not exist, no tables yet (runpnpm db:migrate), or a user that may not read them. - 3When the database cannot be reached at all, the other rows say "Not checked — the installer could not reach its database".
- 4Authentication secret:
BETTER_AUTH_SECRETmust be set, at least 32 characters long, and not an example value. - 5Installation token:
INSTALL_TOKENmust 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." - 6Application URL:
NEXT_PUBLIC_APP_URLandBETTER_AUTH_URLmust 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." - 7Fix a value as the table "Where to fix a failed check" shows, then press Check again.
Make random valuesbashopenssl rand -base64 48 # BETTER_AUTH_SECRET openssl rand -hex 32 # INSTALL_TOKEN, CRON_SECRETNo openssl (for example on Windows)bashnode -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 -fanddocker run); in a panel, a redeploy.Check: All five rows show a green tick, and the Installation token box appears under them.
- 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.
- 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_TOKENvalue 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
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
USDuntil 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
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.
- 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
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.
- 1Under Storage provider, pick Cloudflare R2 (selected first), AWS S3, MinIO or DigitalOcean Spaces. The form shows that provider's fields.
- 2Fill them in and press Test connection. It uploads a small file and reads it back through the Public URL.
- 3No bucket yet? Tick Set storage up later. The install finishes, but uploads stay unavailable until you add the bucket under Settings → Storage Settings.
- 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
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.
- 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.
- 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
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"The default branch, register and units could not be created — add them under Settings after signing in."
- 2"The sample data could not be created — you can add products from Products after signing in."
- 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.
- 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
/installnow answers "not found". - 9
Set up the rest
Nothing else is mandatory, but most businesses do these next.
- 1Background jobs: Background Jobs. Emails and texts that fail their first try are only retried by them.
- 2Email: Settings → Email, or the
SMTP_*variables (Email / SMTP). - 3Text messages (optional): Settings → SMS (Twilio). Texts go out only after SMS is switched on and one test message has been sent (Text Messages).
- 4Tax: rates and groups under Settings → Tax (Tax).
- 5Opening balances, if you move from another system (Accounting).
- 6Storage, if you skipped it: Settings → Storage Settings (Storage & Media).
- 7Scanners, printers and the cash drawer (Hardware).
- 8Then work through the Go-Live Checklist.
- 10
Locked out, or /install answers not found
/installanswers "not found" once the business is installed: sign in at/logininstead. Lost the owner's password? Use Forgot password? on the sign-in page (it needs email), or restore the account from the command line withpnpm create-admin, as Backups & Recovery shows.bashpnpm create-admin you@example.com "a-new-password"Only on a test database you can throw away:pnpm db:resetempties 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.
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
.envand the scheduler.
The server and its address
| Check | Where | Done when |
|---|---|---|
| HTTPS address | Domain & HTTPS | https://pos.example.com opens with a padlock, and port 3000 is reachable only through the proxy. |
| App address | NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL, rebuilt after the last change | Both 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. |
| Secrets | BETTER_AUTH_SECRET and CRON_SECRET | Your own random values: 32+ characters for the first, 16+ for the second. No placeholder left. |
| Owner fallback password | ADMIN_PASSWORD in .env | Changed or deleted. .env.example ships change-me, which pnpm create-admin uses when you type no password. |
| Demo mode off | DEMO_MODE and NEXT_PUBLIC_DEMO_MODE | Both 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-ins | The database | It was set up by the wizard, not pnpm db:seed: signing in as owner@example.com with Owner@123 fails. |
| Maintenance mode off | Settings → Maintenance Mode | Enable Maintenance Mode is off, and saved. |
| Proxies | TRUSTED_PROXIES | Unset, unless another CDN or a load balancer forwards from a public address (Domain & HTTPS). |
Jobs, backups and the books
| Check | Where | Done when |
|---|---|---|
| Background jobs | The 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. |
| Backups | A nightly pg_dump, copied off the server (Backups & Recovery) | A backup restored into a test database opens with your data. |
| Books check | pnpm accounting:reconcile --dry-run | It exits with code 0. |
| PDF exports | Chromium and the Noto fonts on the server (Node Server) | Statements → Profit and loss → PDF downloads a PDF. |
Messages and files
| Check | Where | Done when |
|---|---|---|
| Settings → Email (Email / SMTP) | Send test email reaches your inbox. Password resets, receipts and notifications need it. | |
| Text messages | Settings → SMS (Twilio), optional (Text Messages) | SMS is switched on and one test text has been sent: texts go out only after that. |
| Storage | Settings → Storage Settings (Storage & Media) | Test connection reports "… connected and public URL verified", and a product image you upload shows. |
| Who hears of what | Settings → Notifications (Notifications) | Daily digests from and Registers closed by match your trading hours. |
The business
| Check | Where | Done when |
|---|---|---|
| Business details | Settings → General Settings | Name, 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. |
| Tax | Settings → Tax (Tax) | Your rates and groups exist: a new business charges no tax until you add them. |
| Branches and registers | Settings → Branches and Settings → Registers | Main Branch and Counter 1 carry your names, and each till device has its own register. |
| Payments | Settings → Payments | Only the tenders you take are switched on. |
| Receipt | Settings → Receipt (Hardware) | Paper width (58 mm or 80 mm), logo, header and footer are as you want them. |
| Opening figures | Accounting 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 data | Products, Customers and Suppliers | If you installed with Add sample data: the sample records you will not use are archived or deleted. |
| Staff | Staff and Roles (Staff & Roles) | Everyone has their own account and role. Nobody else uses the owner's sign-in. |
| Two-step sign-in | Your profile, and Settings → Security & Access Control (Security) | On for the owner at least. |
The counter
| Check | Where | Done when |
|---|---|---|
| Scanner | Hardware | A scan on the till screen adds the product: the scanner sends Enter after each code. |
| Receipt printer | Settings → Receipt and Settings → Registers | Receipts print on the receipt printer, sized to the paper width. |
| Cash drawer | Settings → Point of sale → Open the cash drawer, the register's Cash drawer switch, and QZ Tray | Test in the till's Set up drawer printer opens the drawer. |
| Offline readiness | Each 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.
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_SECRETvalue from.env: at least 16 random characters.openssl rand -hex 32makes a good one. - Your public address, for example
https://pos.example.com.
The eleven jobs
| Job (/api/cron/…) | Schedule | What it does |
|---|---|---|
| email-deliveries | */5 * * * *: every 5 minutes | Retries queued email and text messages. |
| store-credit | */15 * * * *: every 15 minutes | Expires store credit past its date and gives back abandoned till holds. |
| recurring-expenses | 10 * * * *: hourly, at :10 | Records the copies repeating expenses owe, each on the day it fell due. |
| notification-digests | 5 * * * *: hourly, at :05 | Sends the day's digests (low stock, late orders, bills due, customers' dues, expiring store credit). |
| register-watch | 20 * * * *: hourly, at :20 | Reports registers still open past Settings → Notifications "Registers closed by". |
| housekeeping | 40 3 * * *: daily, 03:40 | Deletes old delivery logs, spent request keys, expired rate-limit counters and old notifications. Never a business document. |
| accounting-reconcile | 15 2 * * *: daily, 02:15 | Posts 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 minutes | Posts the journals that failed to post as soon as each is due to be tried again (Books check → Postings waiting). |
| gift-card-expiry | 0 4 * * *: daily, 04:00 | Reminds holders of gift cards that expire soon, and, when Settings → Gift cards books breakage, takes what expired cards still hold into income. |
| staff-access | 25 * * * *: hourly, at :25 | Warns 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 minute | Starts 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
| Schedule | Jobs | Not running after |
|---|---|---|
| Every minute | marketing-send | 30 minutes without a run |
| Every 5 minutes | email-deliveries | 30 minutes without a run |
| Every 15 minutes | store-credit, accounting-recoveries | 2 hours |
| Hourly | notification-digests, recurring-expenses, register-watch, staff-access | 6 hours |
| Daily | accounting-reconcile, housekeeping, gift-card-expiry | 36 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
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.- 1Node server: put
CRON_SECRET=…in.env, then restart the app. - 2Docker image: put it in the env file, then run
docker rm -f posifyand thedocker runcommand again. - 3Deploy panel: add it to the application's environment and redeploy.
bashopenssl rand -hex 32No openssl (for example on Windows)bashnode -e "console.log(require('crypto').randomBytes(32).toString('hex'))"The app refuses a missing value, the.env.exampleplaceholderreplace-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. - 1Node server: put
- 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.
- 1Run
crontab -e. - 2Paste the block. Put your value after
CRON_SECRET=and your domain in place ofYOUR-DOMAIN, then save. - 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. - 4Run
crontab -lto see what was saved.
crontab -ebashCRON_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/nullCrontab treats%as a special character. A hex secret (openssl rand -hex 32) has none.Check:
crontab -llists theCRON_SECRET=line and eleven job lines. - 1Run
- 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 onnode:24-bookworm-slim, has none. Use Node there instead, with one schedule per line below.- 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. - 2The command calls the app inside the container (
http://127.0.0.1:3000) with theCRON_SECRETfrom the container's environment, prints each job with its status, and fails when a call does not succeed.
One command per schedulebash# * * * * * 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-expiryCheck: A schedule's run log shows each job with
200, for examplestore-credit 200. - 1For each schedule, use the cron expression in the comment and the
- 4
On Windows: Task Scheduler
Create one Task Scheduler task per job that runs
curl.exewith the same arguments as its crontab line. Windows 10 and 11 includecurl.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
Test one job by hand
Call one job yourself to prove the secret and the address.
housekeepingis safe at any time: it deletes only old logs, spent keys and old notifications, never a business document. SetCRON_SECRETin that terminal first, as the first line of each block does.macOS and LinuxbashCRON_SECRET=paste-the-value-from-your-.env curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/housekeepingWindows PowerShellpowershell$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 saysThe 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 printssuccessasTrue. - 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.
- 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.
- 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.
- 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.
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
- Posify runs on the server: Docker Image, Dokploy & Panels or Node Server.
- Access to your domain's DNS settings.
- Ports 80 and 443 open on the server, and in your provider's firewall if it has one.
- 1
Choose the final address
Pick one address, such as
pos.example.com, and use exactly that one everywhere: inNEXT_PUBLIC_APP_URLandBETTER_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
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.comshows your server's IP address. - 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).
- 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.
Caddyfiletxtpos.example.com { reverse_proxy 127.0.0.1:3000 }Check:
https://pos.example.comopens with a padlock. - 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
- 4
Set the two address variables
NEXT_PUBLIC_APP_URLandBETTER_AUTH_URLmust both be the https address, for examplehttps://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
NEXT_PUBLIC_APP_URLis written into the app when it is built. Changing it in.envchanges nothing until you build again. - 2Node server: edit
.env, runpnpm build, then restart. - 3Prebuilt image: change the GitHub variable, run the workflow and deploy the new image. Keep the env file's value equal to it.
- 4
BETTER_AUTH_URLis 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/loginworks. - 1
- 5
Open the tills on the https address
Browsers allow the offline till only on an
https://address, or onlocalhoston the same machine. A till opened on a plainhttp://network address, such ashttp://192.168.1.5:3000, cannot sell offline, and the camera scanner does not work there either.- 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.
- 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
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
Behind another CDN or a load balancer
Posify finds each visitor's IP address from the proxy's
X-Forwarded-Forheader. 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. SetTRUSTED_PROXIESonly when another CDN or a load balancer forwards from a public address.- 1Comma-separated IP addresses and CIDR ranges. The word
cloudflarestands for Cloudflare's ranges. - 2Without it, every visitor arrives as one of the CDN's addresses and shares its limits with everyone else there.
.envbashTRUSTED_PROXIES=203.0.113.0/24 - 1Comma-separated IP addresses and CIDR ranges. The word
- 8
Changing the domain later
Do the steps above again for the new address, then update everything that still names the old one.
- 1The DNS record, and the proxy's site or the panel's domain.
- 2
NEXT_PUBLIC_APP_URLandBETTER_AUTH_URL, then rebuild (step 4). - 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.
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
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
| General Settings | Store 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 branding | Branding & Appearance, Languages & RTL, Tax |
| Branding | Light Theme Logo, Dark Theme Logo and Favicon; Primary, Secondary and Accent colours; Chart colours; the default light or dark mode. | General and branding | Branding & Appearance |
| Tax | Your 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. | Tax | Tax |
| Inventory | Stock 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. | Inventory | Inventory |
| Accounting | The 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. | Accounting | Accounting |
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
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
| Branches | The 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. | Branches | Point of Sale |
| Registers | The POS terminals of each branch: name, code, receipt prefix, receipt printer, cash drawer, and whether each one is active. | Registers | Point of Sale, Hardware |
Selling
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
| Point of sale | How 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 sale | Point of Sale, Offline Selling |
| Payments | The 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 methods | Point of Sale |
| Receipt | What 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. | Receipt | Point of Sale, Tax |
| Invoice templates | The designs of the receipt and the A4 sale invoice. | Receipt | Invoice Templates |
| Loyalty | How customers earn points, what a point pays at the POS, and the tiers they climb. | Loyalty | Loyalty & Gift Cards |
| Gift cards | Whether 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 cards | Loyalty & Gift Cards |
| Numbering | The 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 numbering | This table; register prefixes in Point of Sale |
Communication
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
The switch that turns email on, the mail server and its setup guide, the sender, Send test email, and the Delivery log (/settings/email/deliveries). | Email / 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 messages | Text Messages |
| Notifications | Which 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. | Notifications | Notifications |
| Marketing | The 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: manage | Text Messages, Background Jobs, User Manual |
Security
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
| Security & Access Control | Session 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-in | Security |
Advanced
| Page | What it holds | Permission | Explained in |
|---|---|---|---|
| Storage Settings | The 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. | Storage | Storage & Media |
| Maintenance Mode | The 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 mode | Security, 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 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 jobsSettings 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.
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_REGIONdoes not change the region of AWS S3, Spaces or MinIO: the page's AWS Region (us-east-1, ornyc3for 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.envalready holds storage keys, the wizard says so and you can leave the step alone. - A field filled from
.envsays Set via environment variable. A value saved here overrides it.
The four providers
| Provider | Fields on the page | Where Posify reaches it | Public URL / CDN |
|---|---|---|---|
| Cloudflare R2 | R2 Account ID (32 characters, from R2 → Overview), Bucket Name, Access Key ID, Secret Access Key | https://<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 S3 | AWS Region, Bucket Name, Access Key ID, Secret Access Key | Worked 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 Spaces | AWS 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 Key | https://<region>.digitaloceanspaces.com | Optional: left empty, files are served from the Space itself. Or paste the CDN endpoint (…cdn.digitaloceanspaces.com). |
| MinIO | Endpoint URL, AWS Region (us-east-1 is fine, MinIO ignores it), Bucket Name, Access Key ID, Secret Access Key | The 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
| File | Uploaded from | Who can open it |
|---|---|---|
| Product, category and brand images | The product, category and brand forms | Anyone who has the file's address |
| Logos and favicon | Settings → Branding, and Receipt logo in Settings → Receipt | Anyone who has the address |
| Maintenance background | Settings → Maintenance Mode | Anyone who has the address |
| Profile photos | Each person's profile | Anyone who has the address |
| Images in invoice templates | The invoice template editor | Anyone who has the address |
| Expense receipts | An expense's receipt | Staff, from Posify, when a private bucket is named |
| Journal attachments | A 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
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.
- 1Cloudflare R2: in the Cloudflare dashboard, open R2 → Create bucket.
- 2AWS S3: create a bucket in the S3 console and note its region.
- 3DigitalOcean Spaces: Spaces Object Storage → Create a Space. Pick a datacenter near your branches: a Space cannot move to another datacenter later.
- 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/dataloses every uploaded file on the next redeploy. Serve it over HTTPS on its own subdomain too: browsers block mixed content, so anhttp://endpoint breaks every image on an HTTPS install. - 2
Create access keys
Give Posify keys that can read, write, list and delete in that bucket, and nothing more.
- 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.
- 2AWS S3: in IAM, create a user with programmatic access and a policy granting
s3:PutObject,s3:GetObject,s3:DeleteObjectands3:ListBucketon that bucket. - 3DigitalOcean Spaces: API → Spaces Keys → Generate New Key.
- 4MinIO: Access Keys → Create access key, in the console.
- 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.
- 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.
- 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.
- 3DigitalOcean Spaces: Space → Settings → set File Listing to public, or enable the CDN.
- 4MinIO: run
mc anonymous set download myminio/<bucket>, wheremyminiois yourmcalias for the server.
- 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.
- 1Type the fields the table above lists for that provider.
- 2Public URL / CDN: the address from the previous step. R2 marks it Required.
- 3Or type the same fields in the install wizard's step Where media is stored, and press Test connection there.
A field that.envalready fills shows Set via environment variable under it, and you can leave it empty here. - 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.- 1Create a second bucket in the same account, with public access off and no domain connected.
- 2Make sure the keys from Create access keys may use it too.
- 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
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.
- 1Press Test Connection and read the result under the fields.
- 2Press Save Storage Settings.
- 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.envcannot be tested with it: save the provider and read the Connected chip, which checks the bucket with what is saved and what.envsupplies.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
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)
20by default- Max Video Size (MB)
1024by default- Path Prefix
uploads/by default: the folder uploads go into
- 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.
- 1In the bucket's CORS rules, allow
PUTfrom your Posify address (for examplehttps://pos.example.com) with theContent-Typeheader. - 2An SVG always goes through Posify, which turns it into a regular image. A logo keeps its vector.
- 1In the bucket's CORS rules, allow
- 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.
- 1Search files… and the All, Images, Videos and Documents filters find a file; Copy URL copies its address.
- 2Upload adds files straight to the library.
- 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.
- 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.
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| Key | Required | Description |
|---|---|---|
STORAGE_ACCESS_KEY_ID | Optional | The bucket's access key ID. Needed for uploads unless Settings holds it. |
STORAGE_SECRET_ACCESS_KEY | Optional | The bucket's secret key. |
STORAGE_ACCOUNT_ID | Optional | Cloudflare R2 only: your R2 account ID. |
STORAGE_ENDPOINT | Optional | MinIO only: your server's S3 API URL. The other providers ignore it. |
STORAGE_REGION | Optional | Shipped 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_BUCKET | Optional | The public bucket's name. |
STORAGE_PRIVATE_BUCKET | Optional | The private bucket for expense receipts and journal attachments. Not listed in .env.example. |
STORAGE_PUBLIC_URL | Optional | The 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.
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
| Provider | Server and Port | Username | Password |
|---|---|---|---|
| Gmail | smtp.gmail.com, 587 | Your full Gmail address | An 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 Mail | smtppro.zoho.com for an address on your own domain, smtp.zoho.com for an @zoho.com one; 587 | Your full Zoho address | Your 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, 465 | The full email address | That mailbox's password |
| Brevo | smtp-relay.brevo.com, 587 | Your SMTP login, ending in @smtp-brevo.com | An SMTP key from SMTP & API → SMTP. Your Brevo password does not work. |
| SendGrid | smtp.sendgrid.net, 587 | The word apikey | An API key with Mail Send access |
| Amazon SES | The SMTP endpoint, email-smtp.<region>.amazonaws.com; 587 | The SMTP username from Create SMTP credentials | The 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
| When it goes out | To | |
|---|---|---|
| Invitation | Administration → 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 reset | Forgot 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 changed | After a password is changed, reset, or set by someone else. Not after the first password chosen from an invitation. | The account's address |
| Receipt | The 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 card | A card sold with an email address on its line: its number, code, PIN, balance and expiry. | That address |
| Gift card reminder | Before 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 reminder | Send 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 |
| Notifications | The events ticked Email under Settings → Notifications, and the Access ends soon notices. | The staff each event concerns |
| Test email | Send test email on Settings → Email. | The address you type |
- 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_USERandSMTP_PASSin.env: those then send.Check: The Mail server and Sender cards appear.
- 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) or465(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
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
Save, then send a test email
The test goes through the saved settings, so save first.
- 1Press Save Changes at the foot of the page.
- 2Press Send test email. Send a test to holds your own address; change it if you like.
- 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
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 yourCRON_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.bashcurl -fsS -H "Authorization: Bearer $CRON_SECRET" https://YOUR-DOMAIN/api/cron/email-deliveriesWithout 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
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).- 1The All, Waiting, Sent and Failed tabs, a date filter and the search (address, subject or category) narrow the list.
- 2Each row shows its status (Queued, Sending, Sent, Retrying, Failed or Cancelled) and its tries, such as Try 2 of 4, with the error.
- 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
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.
| Key | Required | Description |
|---|---|---|
SMTP_HOST | Optional | Your SMTP server. Default smtp.gmail.com. |
SMTP_PORT | Optional | 587 uses STARTTLS, 465 uses TLS. Default 587. |
SMTP_USER | Optional | SMTP username. Together with SMTP_PASS it sends email even while the switch in Settings is off. |
SMTP_PASS | Optional | SMTP password. |
SMTP_FROM | Optional | The 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.
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. .envalone never switches SMS on. TheTWILIO_*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
| Text | When it goes out | To |
|---|---|---|
| Receipt | The 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 |
| Notifications | The events ticked Text under Settings → Notifications → For the team. | The number on each person's profile, under Text alerts |
| Customer reminders | Due 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 code | Someone verifies their number on their profile, for password recovery. | That number |
| Password reset code | Forgot password? while Settings → Security & Access Control → Password reset by text message is on. | The verified number |
| Test text | Send a test text on Settings → SMS (Twilio). | The number you type |
- 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
.envalready holds Twilio details, the fields show Set via environment variable, and the test is all that is left. - 2
Enter the Twilio account
Copy both values from Account Info in the Twilio Console.
- Account SID
ACfollowed 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
Choose who texts come from
Send from offers one of two senders.
- 1Messaging Service: a Messaging Service SID (
MGfollowed by 32 letters and digits). Recommended: Twilio picks the right number for each country and handles STOP replies. - 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.envstill sends in place of a number typed here. - 1Messaging Service: a Messaging Service SID (
- 4
Save, then send the test text
The test uses the saved details, so save first.
- 1Press Save Changes.
- 2Under Send a test text, type a mobile number with its country code.
- 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
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
50by default: the most codes texted in a day to confirm a number or reset a password;0turns codes by text off
- 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).- 1Statuses: Queued, Sending, Sent, Delivered, Undelivered, Retrying and Failed.
- 2Billed as 2 texts, or more, marks a long message that was split into parts.
- 3Resend now and Resend all send failed texts again, and each one is billed again.
- 4A text that fails is retried by the same job as email,
/api/cron/email-deliveries, up to four tries in all.
- 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.envfallback and sends no delivery reports, so its texts stay at Sent. It still needs a saved setup and an accepted test text.
| Key | Required | Description |
|---|---|---|
TWILIO_ACCOUNT_SID | Optional | Your Twilio account SID (AC…). Used while the Account SID field in Settings is empty. |
TWILIO_AUTH_TOKEN | Optional | Your Twilio auth token. |
TWILIO_MESSAGING_SERVICE_SID | Optional | A Twilio Messaging Service (MG…). Preferred: when it is set, it sends in place of any number. |
TWILIO_FROM_NUMBER | Optional | A 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.
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
| Event | What and when | Who hears it |
|---|---|---|
| Low stock | A list per branch of the items at or below their reorder point. Once a day. | See stock |
| Out of stock | An 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 late | A sent order whose expected date has passed with goods still to come. Once a day. | Receive goods, or Approve purchase orders |
| Supplier bill due | A bill about to fall due, and again once it is past due. Once a day. | Pay suppliers |
| Customers' old dues | Who 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 open | A register still open after Registers closed by. Checked every hour. | Registers (in the Settings group), and the cashier who opened it |
| Sold below zero | Units sold that a branch did not have, at the POS or from an offline sale. When it happens. | See stock |
| Offline sale needs review | A sale taken offline that the server refused when it synced. When it happens. | Edit sales |
| Store credit expiring | How much customers' store credit expires soon. Once a day. | Set credit limits, tax exemption and store credit |
| Repeating expenses recorded | The copies of rent, salaries and other repeating expenses written on their days. When it happens. | Record expenses |
| Batches expiring | Per 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
| Setting | Default | What it changes |
|---|---|---|
| Supplier bills due within | 3 days (0 to 60) | How many days before its due date a bill is mentioned. |
| Remind about dues older than | 30 days (0 to 365) | When a customer's due counts as old, counted from its oldest sale or opening due. |
| Remind again every | 7 days (1 to 90) | How often a customer's reminder repeats while the due stays unpaid. |
| Store credit expiring within | 7 days (1 to 90) | How far ahead expiring store credit is announced, once per credit. |
| Batches expiring within | 30 days (1 to 365) | How far ahead the batches digest looks. |
| Registers closed by | 23:00 | A register still open after this time, on the business's clock, is reported. |
| Daily digests from | 08:00 | The hour from which the day's digests and reminders go out, in the business's time zone. |
Notices that are always sent
| Notice | Goes to | Where |
|---|---|---|
| Background jobs have stopped | Maintenance mode (in the Settings group) | The bell and the dashboard |
| The books need a look | Post journal entries | The bell |
| Stock adjustment waiting | Approve adjustments and counts, at that branch | The bell |
| Stock requested by a branch | Transfer stock, at the branch asked | The bell |
| Access ends soon | Suspend and reactivate staff, for the people they manage | The bell and email |
| Codes by text paused for today | The owners | The bell |
These are not on Settings → Notifications.
- 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
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
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
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
/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
/api/cron/register-watch, hourly at :20: registers still open past Registers closed by. - 3
/api/cron/staff-access, hourly at :25: Access ends soon, 3 days before a staff member's access end date. - 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.
- 1
- 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.
- 1All, Unread and Archived tabs, and Mark all as read.
- 2Open on a notification takes you to what it is about.
- 3See all opens the Notifications page (
/notifications), with every notification and a Kind filter. - 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.
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
| Order | Where it is set |
|---|---|
| 1 | The 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. |
| 2 | The product's Tax class. |
| 3 | Its category's Tax group, then the nearest parent category that names one. |
| 4 | The branch's Default tax group, in Settings → Branches. |
| 5 | The Default tax group in Settings → Tax → Tax defaults. |
| 6 | None 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
| Kind | What it charges | For |
|---|---|---|
| Percentage of the price | A 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 unit | The 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 tax | A 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
| Place | What you see |
|---|---|
| Receipts | Settings → 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 templates | A template prints the tax registration where it shows it. See Invoice Templates. |
| The books | Tax 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 report | Finance → 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
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.orGSTIN - 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
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
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
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
Give products and categories their group
Most businesses set the default group and give a different group only where it differs.
- 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.
- 2A category: its Tax group, or Inherit from parent / business default.
- 3A branch: Default tax group in Settings → Branches, for its sales when neither the product nor its category names a group.
- 4A product import: the
chargeTaxcolumn (falsesells tax-free) andtaxGroup(a group's code or name; empty inherits).
- 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.
- 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.
- 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.
- 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.
- 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
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
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
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.- 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.
- 2Tax-exempt sales lists each sale made without tax, with its reason and whether it came from an exempt customer or the POS.
- 3Sales by tax treatment splits net sales by each group's Reported as.
- 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.
- 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.
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
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
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
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
#2065D1until you change it- Secondary colour
#8b5cf6- Accent colour
#f59e0b
- 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.
- 1Leave a colour empty for its default:
#10b981,#f43f5eand#0ea5e9. - 2The preview warns when two colours look almost the same, or when one almost disappears on the light or dark background.
- 3Reset chart colours empties all three.
- 1Leave a colour empty for its default:
- 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
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.
- 1Dark mode and Contrast.
- 2Right to left, and Collapsed sidebar.
- 3Sidebar → Color: Integrate or Apparent.
- 4Language, and the fullscreen button.
- 5Reset to defaults goes back to the business's default look.
- 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.
- 1The installed app carries your Store Name and an icon made from the favicon, or from the logo when there is no favicon.
- 2It opens in its own window, with shortcuts to POS, Sales and Dashboard.
- 3Installing changes nothing about notifications: there is no push in 1.0.
Browsers allow the offline till only over HTTPS (or onlocalhost), and only from a production build. See Offline Selling. - 8
Change the built-in defaults
For people who change the code only.
config/branding.config.tsholds 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.tstsexport 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.
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
| Language | Code | In the picker | Direction |
|---|---|---|---|
| English | en | English | Left to right |
| Bengali | bn | বাংলা | Left to right |
| Arabic | ar | العربية | Right to left |
| Spanish | es | Español | Left to right |
| French | fr | Français | Left to right |
| German | de | Deutsch | Left to right |
| Turkish | tr | Türkçe | Left to right |
| Hindi | hi | हिन्दी | Left to right |
| Dutch | nl | Nederlands | Left to right |
| Chinese (Simplified) | zh | 中文 | Left to right |
| Japanese | ja | 日本語 | Left to right |
| Zulu | zu | isiZulu | Left to right |
| Xhosa | xh | isiXhosa | Left to right |
| Afrikaans | af | Afrikaans | Left to right |
| Swahili | sw | Kiswahili | Left to right |
| Hausa | ha | Hausa | Left to right |
| Yoruba | yo | Yoruba | Left to right |
| Igbo | ig | Igbo | Left to right |
Which language each message uses
| Message | Language |
|---|---|
| Screens | The language the person picked in this browser, else the business's default. |
| Notifications | The business's default language, in the bell, by email and by text. |
| Customer messages | Receipts sent by email or text, statements, reminders and gift card emails: the business's default language. |
| Invitation email | The language of the page the person adding the staff member had open, when that language is switched on; else the default. |
| Password reset email | The language of the page Forgot password? was used on, when it is switched on; else the default. |
| Printed receipts and invoices | Their template's own language. See Invoice Templates. |
| Maintenance page | English, apart from the headline and message you type in Settings → Maintenance Mode. |
- 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
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.
- 1At least one language stays ticked.
- 2Unticking the default makes the first ticked language the new default.
- 3A link with the prefix of a language you switched off redirects to the same page without the prefix.
- 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 ontxthttps://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
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.
- 1On a first visit, a business whose default is not English opens in its default language.
- 2A business whose default is English follows the browser's language, when that language is switched on.
- 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.
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
| Role | What it is for | Settings pages | Left out |
|---|---|---|---|
| Administrator | Everything in the business: sales, stock, money, staff, roles and settings. The only built-in role that manages roles and sees the activity log. | All | Nothing |
| Manager | Runs 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 sale | Managing 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 |
| Supervisor | Leads a shift: every POS permission but selling from an expired batch, plus Sales reports, Their own sales history and Staff reports. | None | Settings and staff |
| Cashier | Sells 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. | None | Voids, price changes, selling on account, selling tax-free, reports |
| Accountant | Keeps the books: every accounting permission, supplier bills and payments, payments against dues, and the sales, purchasing, financial and tax reports. | Accounting | The POS, stock changes, staff |
| External Accountant | An outside accountant: every accounting permission and the financial and tax reports, with read access to sales, purchases, customers and suppliers. | Accounting | Taking payments against dues, paying suppliers, the POS, staff |
| Stock Keeper | Receives goods, adjusts, transfers and counts stock, and sees costs. | None | Approving adjustments and counts |
| Purchaser | Suppliers, purchase orders, receiving goods and returning them; adds and edits products. | None | Approving purchase orders, supplier bills, supplier payments |
| Read-only | Sees sales, products and their costs, stock, purchases, customers, suppliers, the books and every report, and changes nothing. | None | The 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
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
- 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
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.
- 14 to 8 digits, not one digit repeated and not a run like
1234. - 2They can set or change their own from their profile.
- 3Five wrong tries lock the PIN for five minutes. Clear PIN removes it.
- 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. - 14 to 8 digits, not one digit repeated and not a run like
- 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
Suspend, reactivate or remove someone
The Signing in card on their staff page holds what you need when someone leaves or forgets a password.
- 1Suspend ends every session at once; they cannot sign in until you press Reactivate.
- 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.
- 3Send a password reset emails them a reset link; Send the invitation again does the same while they have not set a password.
- 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
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.
- 1The people who manage them hear 3 days before, in the bell and by email.
- 2Remove end date makes their access last until it is changed.
- 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
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.
- 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.
- 2Opens on sign-in: Dashboard or POS (the till).
- 3Dashboard: the job its dashboard is laid out for (Automatic, Overview, Till, Stock, Buying or Money).
- 4Preview this role shows the menu, dashboard and POS actions it would give, before you save.
- 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
Add sign-in rules and till limits to a role
Two cards on each role add limits on top of its permissions.
- 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.
- 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
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.
- 1Roles to compare picks the columns, and Differences only hides the rows where they agree.
- 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.
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_TOKENandCRON_SECRETare long random values of your own, not the examples.- Neither
DEMO_MODEnorNEXT_PUBLIC_DEMO_MODEis 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_PROXIESnames it.
Settings → Security & Access Control
| Setting | Default | What 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 Attempts | 10 (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 Limiting | On | Limits 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 presets | Default | Signed-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-in | Off | Shows the Two-Factor Authentication card on everyone's profile. Switching it off hides the card but un-enrols nobody. |
| Minimum Password Length | 8 (8 to 128) | Applies to every new password. |
| Require switches | Off | Require 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 message | Off | Forgot 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
| Value | What it protects | Keep in mind |
|---|---|---|
| BETTER_AUTH_SECRET | Signs 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_TOKEN | The 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_SECRET | The 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_KEY | Signs 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 credentials | The 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
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.
- 1Open the account menu → Profile, and under Two-Factor Authentication press Set Up Two-Factor Authentication.
- 2Step 1: scan the QR code with an authenticator app (or type the code shown under Can't scan?).
- 3Step 2: type the 6-digit code from the app.
- 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
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
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 runsbashpnpm create-admin you@example.com "a-new-password" --reset-2faThe owner cannot be reset from a staff page. For the owner,pnpm create-adminwith--reset-2fasets a new password and turns two-step verification off: see Backups & Recovery. - 4
Put Posify into maintenance mode
Use it while you update or repair Posify. Open Settings → Maintenance Mode.
- 1Turn on Enable Maintenance Mode.
- 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.
- 3Optional: a Background image, and Show countdown with Expected back online.
- 4Under Allowlisted IP addresses, add your own address, one per line, to keep using everything.
- 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, setTRUSTED_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
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.
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
| Setting | What it does | New business |
|---|---|---|
| Require an open drawer to sell | Each 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 sale | Prints 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 drawer | Opens 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 discount | The 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 stock | Only 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 sale | Don'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 coins | What 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 close | Cashiers 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 approval | A 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 float | What a new shift's float starts at when the last shift left nothing to go by. 0 starts it empty. | 0 |
| Largest float | A drawer opened with more than this needs a note saying why. 0 sets no limit. | 0 |
| Lock the POS when idle | Minutes 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 window | Hours, 1 to 72, a register keeps selling with no connection after it last reached the server. See Offline Selling. | 12 hours |
| Sending receipts: By email | The 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 message | The 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 keys | Up 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 |
| Sounds | On 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
| Setting | What it does | New business |
|---|---|---|
| Ways to pay | Cash, 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 rounding | Round 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 deposits | The 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 after | Days 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
| Setting | What it does | New business |
|---|---|---|
| Paper width | 58 mm or 80 mm. A browser print is sized to it, with no margins. | 80 mm |
| Print the logo | The business logo (Settings → Branding), or a Receipt logo chosen here. A black-and-white logo prints best. | On |
| Header, Footer | Lines above and below the receipt, up to 500 characters each, such as a VAT number or an exchange policy. | Empty |
| Show the tax breakdown | Tax lines under the totals. A tax-exempt sale always prints its tax line. | On |
| One line per tax rate | Each tax on its own line (VAT 15%, SD 10%) in place of one Tax line. | Off |
| Show tax numbers | The 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 balance | The 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 sell | Use the POS |
| Open or close a drawer | Open a register, Close a register |
| Cash in, Cash out, No sale | Put cash in or take it out |
| Discount a line or the sale | Give discounts, up to Largest discount or the role's own limit |
| Type another price | Change a price at the POS |
| Sell without tax on request | Give discounts, or Sell tax-free when Settings → Tax → Who may sell tax-free asks for it |
| Void a sale | Void a sale |
| Take a return | Take returns, at a branch with Take returns here on |
| Leave the rest on the customer's account | Sell on account |
| See the expected cash on a blind close | See the expected cash when closing a drawer |
| Approve a drawer count that is off | Approve a drawer count that is off |
| Sell from a batch past its expiry | Sell 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
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
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-givesFR-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
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
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.
- 1Card and Bank transfer are recorded with an optional reference. Posify 1.0 does not connect to card terminals.
- 2On account leaves what is unpaid as the customer's due, within their credit limit, for a cashier allowed to sell on account.
- 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
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
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, soSAL-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 readGC-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
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
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
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.
- 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.
- 2Print opening slip prints the opening count.
- 3A drawer still open from an earlier day, or opened by another cashier, offers Carry on in it or Count and close.
- 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
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.
- 1Cash in: cash put into the drawer that is not a sale, such as change from the safe.
- 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.
- 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
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
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.
- 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.
- 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.
- 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.
- 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
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.
- 1With Blind close on, the cashier counts without seeing what the drawer should hold; the difference shows once it is closed.
- 2A count off by more than Count difference needing approval needs a note and the PIN of someone who may approve it.
- 3Sales still waiting to sync must sync first: "Close the drawer once they have."
- 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 theregister-watchjob (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.
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, thenpnpm start, or the prebuilt Docker image.pnpm devhas no offline till (Running the App). - A secure address:
https://(Domain & HTTPS), orlocalhoston the same machine. A till opened on a plainhttp://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
| Area | Works offline | Needs a connection |
|---|---|---|
| Selling | Scanning, the product grid, quantities, line notes, discounts, tax exemption, holding and resuming sales | Returns, voids, and finding an earlier sale in the till's Sales list |
| Payments | Cash, Card, Bank transfer and Other | Loyalty points, Store credit, Gift card, and Receive due (a payment against a customer's dues) |
| The drawer | Opening it, Cash in, Cash out, No sale, closing it | The expected cash and the Z report, which are worked out when the register reconnects |
| Customers | Finding one of the 500 most recently changed active customers; adding a new one with a name and a phone or an email | Any other customer |
| Gift cards | — | Selling or reloading a card, and checking a balance |
| Receipts | Printing, with a provisional number | Sending by email or text, once the sale has synced |
| Cashiers | The last cashier stays on the till | Locking 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 sale | When it arrives |
|---|---|
| Whether it counts as offline | While 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 tax | Worked 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 time | Kept: the sale is dated when it was taken, inside the offline window, so reports and the books put it on the right day. |
| The cashier | The 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 rules | The 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 points | A sale for a named customer earns its points now, dated at the time it was rung up. |
| The books | The sale posts its journal like any other (Accounting). |
Limits
| What | Limit |
|---|---|
| Offline selling window | 1 to 72 hours since the register last reached the server; 12 by default |
| Unsynced sales per register | 500. Then the till says "This register has too many unsynced sales. Reconnect to sync before taking more." |
| Products in the snapshot | 20,000, with their variants, prices and the branch's stock |
| Customers in the snapshot | The 500 most recently changed active customers |
| Product pictures | Up to 400 per download, and the browser keeps up to 600; none on a data-saver connection |
| Snapshot refresh | Every 15 minutes while the till is open and online, and each time the connection comes back |
| Retries while offline | Every 30 seconds |
- 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.
- 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.
- 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.
- 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
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.
- 1After the window, the till locks with "Reconnect to keep selling" until it reaches the server again and someone is signed in.
- 2Nothing taken before is lost: the lock screen counts the sales still saved on the device.
- 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
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."
- 1Pay with Cash, Card, Bank transfer or Other.
- 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.
- 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
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.
- 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.
- 2A drawer opening or closing that has not gone through holds everything queued after it on that register. Other registers are not held.
- 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
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.
- 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.
- 2Until the server has the close, the till keeps that drawer closed and opens no new drawer online on top of it.
- 3Online, sales still waiting must sync first: "Close the drawer once they have."
- 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.
- 1A product was archived ("… is no longer sold").
- 2A price or a tax changed, so the payments no longer cover the sale, or come to more than it.
- 3The customer was archived, or a sale on account would pass their credit limit.
- 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.
- 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
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: …".
- 1Read the reason.
- 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.
- 3Press Send again.
- 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).
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_CERTIFICATEandQZ_TRAY_PRIVATE_KEY.
Barcode formats
| Format | Digits | How Posify checks it |
|---|---|---|
| EAN-13 | 13 | Check digit verified |
| UPC-A | 12 | Check digit verified |
| GTIN-14 | 14 | Check digit verified |
| Code 128 | Anything else: 1 to 80 printable characters | Letters, 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
| Use | Set up in |
|---|---|
| Receipts with no print dialog | Settings → Registers → Receipt printer |
| Opening the cash drawer | Settings → Point of sale → Open the cash drawer, and Settings → Registers → Cash drawer |
| Labels straight to a thermal printer | The 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
| Option | Choices |
|---|---|
| Label size | 40 × 25 mm, 50 × 30 mm or 60 × 40 mm |
| Printer language | ZPL / ZPL emulation (Zebra and printers that emulate it) or TSPL / TSPL emulation (TSC and printers that emulate it) |
| Resolution | 203 or 300 dpi |
| Copies | 1 to 500 per item, or One label per unit on hand |
| Show SKU, Show price | On 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
| Device | What to look for |
|---|---|
| Barcode scanner | Works as a USB or Bluetooth keyboard and sends Enter after the code. On phones and tablets, the camera may be enough. |
| Receipt printer | 58 mm or 80 mm paper, with a driver for the till computer's operating system, so the browser can print to it. |
| Cash drawer | Plugs into the receipt printer's drawer port and opens on the standard ESC/POS pulse, sent through QZ Tray. |
| Label printer | A driver for printing from the browser; or ZPL or TSPL, for the downloaded command files and direct printing. |
- 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.
- 1Send Enter after each code. This is the usual factory setting; without it the till never sees the end of the code.
- 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.
- 3Send codes of at least 4 characters. Shorter bursts are treated as typing.
- 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
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.- 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.
- 2Browsers give the camera only to an
https://address. On a plainhttp://address the till says "This browser cannot scan with the camera." - 3For offline use, open the camera scanner once while online: it downloads the first time it opens.
- 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.- 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.
- 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".
- 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.
- 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
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.
- 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.
- 2Settings → Point of sale → Sending receipts lets the till email or text the receipt instead of, or as well as, printing it.
- 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
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.
bashopenssl req -x509 -newkey rsa:2048 -nodes -days 3650 \ -keyout qz-private-key.pem -out qz-certificate.pem -subj "/CN=Your Business"Keepqz-private-key.pemsecret: whoever has it can send jobs to every till that trusts the certificate. - 6
Give both to Posify
Put both in
.env, each on one line, with\nwhere 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..envbashQZ_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 linebashawk 'NF { sub(/\r/, ""); printf "%s\\n", $0 }' qz-certificate.pem; echoOnly 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
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
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
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.
- 1Settings → Point of sale → Open the cash drawer: on.
- 2Settings → Registers → (the register) → Cash drawer: on, for each register that has one.
- 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
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.
- 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.
- 2Download ZPL or Download TSPL: saves the printer commands as a file, for a tool that sends files to the printer.
- 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.
| Key | Required | Description |
|---|---|---|
QZ_TRAY_CERTIFICATE | Optional | The 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_KEY | Optional | The 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.
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
| Setting | What it does | New business |
|---|---|---|
| Stock below zero in the back office | Refuse: 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 at | An 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 adjustments | Adjustments 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 counts | A finished count waits for approval before its differences are applied. | Off |
| Another person approves | Whoever 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
| Reason | Direction |
|---|---|
| Damaged, Expired, Lost, Theft, Internal use | Takes stock out |
| Found | Brings stock in |
| Correction, Other | Either 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
| Status | What it means |
|---|---|
| Requested | The 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. |
| Draft | Being prepared. Nothing has moved. |
| Ready to ship | Can go back to draft, be shipped or be cancelled. |
| In transit | Ship took the units out of the source. They are in nobody's on-hand figure; the destination's Stock list shows them as incoming. |
| Completed | Every shipped unit was received or rejected, in one go or in parts. |
| Cancelled | Before shipping, nothing moved. In transit, the units go back to the source at the cost they left with; refused once anything has been received. |
| Declined | The 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
| Column | Meaning |
|---|---|
| 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. |
| qty | Units, above 0. |
| unit_cost | Optional. 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
| Document | Posts |
|---|---|
| Adjustment or count, units found | Dr Inventory / Cr Inventory adjustments |
| Adjustment or count, units lost | Dr Inventory adjustments / Cr Inventory |
| Transfer (ship, receive, cancel) | Nothing: one Inventory account serves every branch. Rejected units post as a stock adjustment. |
| Opening stock | Dr 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
| Permission | Allows |
|---|---|
| See stock | See stock, movements, low stock, adjustments, transfers and counts, and export the Stock list. |
| Adjust stock | Make adjustments, edit stock on the Stock list, set reorder points, import opening stock. |
| Transfer stock | Create, request, ship, receive and cancel transfers. |
| Count stock | Start, count, finish and cancel counts. |
| Approve adjustments and counts | Approve or reject adjustments and counts. |
| See costs | See 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
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
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.
- 1The import is all or nothing: one bad row and nothing is written. Fix the rows the preview lists and choose the file again.
- 2An item that already has movements at a branch is refused there: change it with an adjustment or a count.
- 3Importing the same file again with the same request changes nothing.
- 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
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.
- 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.
- 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. - 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
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
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.
- 1Ship transfer takes the units out of the source branch. They stop being available for sale there.
- 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.
- 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
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.
- 1Approve makes the request a transfer ready to ship, and sets the units aside for it: the Stock list shows them as Committed.
- 2Decline ends it with a reason, which the asking branch is told.
- 3The asking end may Withdraw request while it waits. Nothing moves stock until the transfer ships.
- 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.
- 1Click into the Scan box and scan: each scan counts one more unit of that item. The sheet walks the shelves in bin order.
- 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.
- 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.
- 4Finish count applies the count at once as one adjustment (Stock count), or, with Approve stock counts on, waits for approval.
- 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.
- 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.
- 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.
- 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.
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
| Preset | Tab | Paper | What it looks like |
|---|---|---|---|
| Standard receipt | POS receipt | Thermal 80 mm | Today's till receipt as a template: business, sale details, lines, totals, payments, barcode |
| Compact thermal | POS receipt | Thermal 80 mm | A dense receipt with the totals, payments and a QR code of the sale number |
| Thermal 58 mm | POS receipt | Thermal 58 mm | The compact receipt on a narrow roll |
| Standard invoice | Sale invoice | A4 portrait | Business and customer side by side, lines with SKU and discount, totals, payments, signature |
| Minimal | Sale invoice | A4 portrait | Thin rules and white space |
| Premium | Sale invoice | A4 portrait | A coloured header band and boxed sections |
| Compact A5 | Sale invoice | A5 landscape | A dense page for small printers |
| US Letter invoice | Sale invoice | US Letter | The 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
| Size | Width × height | Page length |
|---|---|---|
| A4 portrait | 210 × 297 mm | Fixed page |
| A4 landscape | 297 × 210 mm | Fixed page |
| A5 portrait | 148 × 210 mm | Fixed page |
| A5 landscape | 210 × 148 mm | Fixed page |
| US Letter | 215.9 × 279.4 mm | Fixed page |
| Thermal 80 mm | 80 mm roll | Grows with content (roll) |
| Thermal 58 mm | 58 mm roll | Grows with content (roll) |
| Custom size | Width 20–500 mm, height 20–1000 mm | Fixed 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
| Block | What it prints |
|---|---|
| Business header | Business name, logo, address and phone |
| Customer | The customer's name, phone and address |
| Sale summary | Sale number and date |
| Product table | Name, SKU, qty, unit price and line total; continues across pages |
| Price summary | Subtotal, discount, tax, total, payments, change and due; last page |
| Barcode | The sale number |
| QR code | The sale number |
| Notes | The sale's note |
| Divider | A rule across the printable width |
| Logo | The business logo |
| Product rows | Name, 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
| Element | What it prints |
|---|---|
| Text | Fixed text, the same on every print, or a data field from the sale |
| Image | A picture of your own |
| Barcode | A fixed value you type, in Code 128, EAN-13 or UPC-A |
| QR | A web address you type |
| Line | A horizontal line |
| Box | A box with a thin border |
| Products | Name, qty and total, plain |
Data a text can print
| Group | Fields |
|---|---|
| Sale | Sale number, Date, Payment status, Payment method, Cashier, Register, Sale channel, Sale note, Provisional number note, Tax exemption reason |
| Customer | Customer name, Customer phone, Customer email, Customer address, Tax ID |
| Amounts | Subtotal, Discount, Tax, Rounding, Total, Paid, Change, Balance due, Returned |
| Products | All product names, Number of lines, Total units |
| Business | Business name, Business phone, Business email, Business address, Tax number, Logo |
| Branch | Branch, Branch code, Receipt header, Receipt footer |
| Page | Page number, Page count, Page label |
| Product line | Item, 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
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
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.
- 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.
- 2A tab holds at most 50 templates, and a template at most 300 elements.
- 3A template's name is unique within its tab, up to 80 characters.
Where the pages aretxt/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
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/yyyyoryyyy-MM-dd.- Digits
- Latin (123), Bangla (১২৩) or Arabic (١٢٣).
- 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.
- 1Arrange, above the canvas: Align to the page or the selection, Distribute three or more, Layer order, Duplicate, Lock, Hide and Delete.
- 2The Layers tab lists every element; the top of the list prints on top. Drag a row to change the order.
- 3Keys: arrows nudge by 1 mm (
Shift: 10 mm),Deleteremoves,Ctrl+Dduplicates,Escdeselects,Ctrl+Zundoes andCtrl+Shift+Zredoes. - 4Pages switches the canvas between Single page and First, middle and last pages, to see how a long sale flows.
- 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
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
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
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
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.
- 1If someone else saved the template after you opened it, Posify asks you to Reload (your changes here are lost) or Overwrite.
- 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
Look after your templates
A card's menu holds Rename, Duplicate, Remove default, Restore preset and Delete.
- 1Restore preset puts the preset's layout back; the template keeps its name and default.
- 2Deleting the default makes the tab print the standard design again. It cannot be undone.
- 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.
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-recoveriesjob 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) andrecurring-expenses(hourly) (Background Jobs). - For PDF downloads, Chrome or Chromium on the server (Requirements). CSV works without it.
System accounts
| Code | Name | Type | What it holds |
|---|---|---|---|
| 1000 | Cash on hand | Asset | Cash in the drawers, for every branch without a cash account of its own |
| 1050 | Cash in transit | Asset | Cash put into or taken out of a drawer, until it is banked, spent or put back |
| 1100 | Bank | Asset | Card, bank transfer and Other payments, unless Settings → Accounting names other accounts |
| 1200 | Accounts receivable | Asset | What customers owe: credit sales, deposit balances, opening dues |
| 1300 | Inventory | Asset | Stock, at its moving average cost |
| 1400 | Input tax receivable | Asset | Tax on supplier bills |
| 1500 | Supplier advances | Asset | Money paid to suppliers that no bill has taken yet |
| 1600 | Inter-branch balances | Asset | What the branches owe one another; 0 across the business |
| 1700 | Fixed assets | Asset | What the business's fixed assets cost |
| 1750 | Accumulated depreciation | Asset | What has been written off fixed assets so far |
| 2000 | Accounts payable | Liability | Supplier bills and opening dues still to pay, and expenses entered as unpaid |
| 2100 | Goods received not billed | Liability | Goods received whose supplier bill is not entered yet |
| 2200 | Output tax payable | Liability | Tax charged on sales, less returns |
| 2250 | Withholding tax payable | Liability | Tax held back from supplier payments, owed to the tax office |
| 2300 | Store credit payable | Liability | Store credit customers hold |
| 2400 | Gift card liability | Liability | What is left on gift cards sold, issued or imported |
| 2500 | Loyalty points liability | Liability | Points customers hold, at their value when earned |
| 2600 | Customer advances | Liability | Money from a customer no due has taken yet, and exchange credit not yet spent |
| 2700 | Loans payable | Liability | What the business still owes on loans it took |
| 3000 | Owner's equity | Equity | Money the owner put in, and your own entries |
| 3100 | Opening balance equity | Equity | The other side of opening balances, opening dues and opening stock |
| 3200 | Retained earnings | Equity | No document posts to it (see the balance sheet below) |
| 3300 | Owner's drawings | Equity | Money the owner took out for themselves |
| 4000 | Sales revenue | Income | Sales before discounts, net of tax; never gift cards |
| 4100 | Sales returns | Income | Goods taken back, at their price before discount |
| 4200 | Discounts given | Income | Line and sale discounts |
| 4900 | Other income | Income | Expired store credit; a voided gift card's balance when no customer bought it |
| 4910 | Gift card breakage | Income | What expired gift cards still held, only while breakage is switched on |
| 4950 | Gain or loss on assets sold | Income | A fixed asset sold or scrapped above or below its book value |
| 5000 | Cost of goods sold | Expense | What the units sold cost |
| 5100 | Inventory adjustments | Expense | Stock found or lost: adjustments and stock counts |
| 5200 | Purchase price variance | Expense | A bill's price above (or below) the cost the goods were received at |
| 6000 | Operating expenses | Expense | Charges on supplier bills; the parent of the default expense categories |
| 6100 | Loyalty rewards | Expense | The value of points earned |
| 6150 | Customer goodwill | Expense | Store credit given by hand |
| 6160 | Gift cards given away | Expense | Gift cards issued from the back office with nothing paid |
| 6200 | Bank charges | Expense | An expense category for bank fees |
| 6300 | Cash over and short | Expense | What a drawer count found over or short |
| 6400 | Rounding differences | Expense | Cash rounding and rounding leftovers |
| 6500 | Depreciation | Expense | The month's share of what fixed assets cost |
| 6600 | Bad debts and discounts allowed | Expense | What customers owed that the business wrote off |
| 6700 | Interest expense | Expense | The 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
| Setting | What it decides | Unset |
|---|---|---|
| Accountant tools in the menu | Whether 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 cash | The cash account a branch's tills take, give back and count in. | Cash on hand (1000) |
| Default bank account | Where bank money lands when nothing else is named. | Bank (1100) |
| Card payments | Where card payments land. | The default bank |
| Bank transfers | Where bank transfer payments land. | The default bank |
| Other payments | Where 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
| Event | Debit | Credit |
|---|---|---|
| Sale, at the till or in the back office | Each 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 sold | Sales 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 till | Each payment's account | Accounts receivable |
| Return | Sales returns; Output tax payable; Inventory for units back on the shelf; Gift card liability for a card taken back | Discounts given (those goods' share); Accounts receivable first; the balances paid with; the refund's account; Cost of goods sold |
| Cash in | The branch's cash | Cash in transit |
| Cash out | Cash in transit | The branch's cash |
| Drawer closed over | That payment's account | Cash over and short |
| Drawer closed short | Cash over and short | That payment's account |
| Goods received | Inventory, net of tax | Goods received not billed |
| Supplier bill | Goods received not billed; Purchase price variance; Operating expenses for charges; Input tax receivable | Accounts payable |
| Supplier payment | Accounts payable for each bill it pays; Supplier advances for the rest | The account it was paid from |
| Purchase return | Goods received not billed for unbilled units; Accounts payable for billed ones | Inventory; Input tax receivable; Purchase price variance |
| Stock found | Inventory | Inventory adjustments |
| Stock lost | Inventory adjustments | Inventory |
| Opening stock | Inventory, per branch | Opening balance equity |
| Transfer between branches | Nothing is posted | — |
| Stock true-up | Cost of goods sold when stock sold past zero is worth less than booked; Inventory when worth more | The other one |
| Customer receipt | The account it came into | Accounts receivable for each due it pays; Customer advances for the rest |
| Customer write-off | Bad debts and discounts allowed | Accounts receivable |
| Expense, paid | Its category's account | The account it was paid from |
| Expense, not paid yet | Its category's account | Accounts payable, until Mark as paid |
| Fund transfer | The account the money went to | The account it left |
| Opening balance of an asset | The account | Opening balance equity |
| Opening balance of a liability or equity | Opening balance equity | The account |
| Opening due, a customer's | Accounts receivable | Opening balance equity |
| Opening due, a supplier's | Opening balance equity | Accounts payable |
| Owner put money in | The cash or bank account | Owner's equity |
| Owner took money out | Owner's drawings | The cash or bank account |
| Loan received | The cash or bank account | Loans payable |
| Loan repayment | Loans payable for the principal; Interest expense for the interest | The cash or bank account |
| Fixed asset entered | Its asset account, at cost | The account it was paid from, or Opening balance equity when already owned |
| Monthly depreciation | Depreciation | Accumulated 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
| Correction | Dated |
|---|---|
| A sale voided | When it was voided |
| A return | When the goods came back |
| A customer receipt, supplier payment or fund transfer reversed | When it was reversed |
| An opening balance or opening due reversed | With its own date, so a report between the two never counts both figures |
| An expense corrected, its payment undone, or the expense voided | With the expense's own date, so its month is restated |
| A manual journal reversed | With 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
| Statement | Where | Shows |
|---|---|---|
| Trial balance | Accounting → Trial balance | Every account's debit, credit and balance as of a day; one branch, or each branch apart |
| General ledger | Accounting → General ledger | One account's lines between two days: brought forward, each line with its running balance and a link to its document, carried forward |
| Profit and loss | Statements → Profit and loss | Net sales, cost of sales, gross profit and Gross margin, operating expenses, operating profit, other income and expenses, Net profit; a % of sales column |
| Balance sheet | Statements → Balance sheet | Assets, 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 flow | Statements → Cash flow | Where 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 equity | Statements → Changes in equity | Equity 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 book | Statements → Cash book | Every 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 category | Statements → Expenses by category | Every 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 report | Statements → Tax report | Output and input tax by month and rate, a Not by rate line, tax-exempt sales, and the net payable or reclaimable (Tax) |
| Receivables, Payables | Money in and out | The agings: customers by days since the sale (0–30, 31–60, 61–90, over 90), open bills by days past due |
| Customer and supplier statements | The Statement tab of a customer or supplier | Every 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 check | See the books |
| Read the statements | See the books, or Financial reports |
| Read the tax report | See the books, or Tax reports |
| Add or change accounts | Manage the chart of accounts, and see every branch |
| Post or reverse a manual journal; opening balances and opening dues; Post now; bank reconciliation | Post journal entries |
| Close or reopen a month | Close financial periods, and see every branch |
| Record expenses | Record expenses |
| Move money between cash and bank accounts | Move money between cash and bank accounts |
| Reverse receipts, payments, transfers and goods received; void bills and expenses | Reverse payments, receipts, transfers and goods received; void bills and expenses |
| Write off what a customer owes | Write off what customers owe |
| Take a customer receipt | Take payments against dues |
| Take a return's credit off a bill; record money a supplier paid back | Pay suppliers |
| Change Settings → Accounting | Accounting, 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
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.
- 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.
- 2Your own account's type and kind change only until a journal names it, and only while Settings → Accounting does not use it.
- 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.
- 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
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
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
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.
- 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, not1,200.50. - 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.
- 3It shows a preview and writes nothing until you confirm.
- 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). - 1The file's columns: Name, Phone, Email (and Code for suppliers), Amount, As of, Due date, Branch, Reference, Note. Amounts are plain numbers,
- 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.
- 1A deposit's balance is not paid by a receipt: it is collected at the till, where paying it hands the goods over.
- 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.
- 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
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.
- 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.
- 2Repeats records the expense again by itself on each day it falls due, through the hourly
recurring-expensesjob. - 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
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.
- 1Cash a cashier put in or took out sits in Cash in transit until you say where it went.
- 2Banked: Transfer money from Cash in transit to the bank.
- 3Spent on a paid-out: record an expense paid from Cash in transit.
- 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
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.
- 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.
- 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.
- 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.
- 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
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.
- 1Say what it is for: the memo is required.
- 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.
- 3The date must be after the last closed month. A date after today is allowed, with a warning.
- 4A person limited to some branches names one of their branches on every line.
- 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
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.
- 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.
- 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.
- 3Posify 1.0 posts no year-end closing journal: the balance sheet works out Retained earnings (earlier years) from the journals each time.
- 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
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.
- 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.
- 2Each finding says how it is fixed: Post it, Rebuild the kind, or Review by hand.
- 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 theaccounting-reconcilejob 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
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.bashpnpm 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).
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 points | Settings → Loyalty → Loyalty points |
| Pay with points, at the till or on a back-office sale | Also Settings → Payments → Loyalty points |
| Sell gift cards at the till | Settings → Gift cards → Sell and reload gift cards, and a product of kind Gift card |
| Pay with a gift card | Settings → Gift cards → Accept gift cards as payment (on unless switched off), and Settings → Payments → Gift card |
| Pay with store credit | Settings → Payments → Store credit |
Settings → Loyalty
| Setting | What it means | New business |
|---|---|---|
| Loyalty points | Sales to a customer earn points, which they can spend at the till. | Off |
| Points back on all products | The 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 points | Points are whole: Round down, or Round to nearest. | Round down |
| Value of one point | What one point pays at the till. | 0.01 |
| Fewest points spent at once | A customer spends at least this many at a time. 0 sets no minimum. | 100 |
| Largest share of a sale paid in points | Points pay at most this share of a sale (1–100%). 100% lets them pay all of it. | 50% |
| Services earn points | On, 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 |
| Tiers | Name, 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
| Setting | What it means | New business |
|---|---|---|
| Sell and reload gift cards | The till sells new cards and tops up old ones. | Off |
| Accept gift cards as payment | The till takes cards as payment, with Settings → Payments → Gift card on too. | On |
| Characters | Letters and numbers (leaving out the easily misread 0, O, 1, I and L), or Numbers only. | Letters and numbers |
| Length | Random characters in each code, the prefix not counted: 12 to 24. | 16 |
| Group size | Codes print in groups of this many characters, joined by dashes; 0 prints one block (0–8). | 4 |
| Prefix | Up to 6 letters and digits before every code. | None |
| Smallest amount | The least a card may be sold or topped up for. | 1 |
| Largest amount | The most one card may hold, top-ups included. | 100,000 |
| A new card expires after | Days 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 lasts | When 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 PIN | Every new card gets a PIN, printed with its code, and paying with the card asks for it. | Off |
| PIN length | Digits in a new card's PIN (4–8). Cards already sold keep theirs. | 4 |
| A reload extends the expiry | A top-up gives the card at least the expiry of a card sold that day; never a shorter one. | On |
| Remind the holder before expiry | Days 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 from | Expires |
|---|---|
| A return refunded to store credit | At the end of the last day of Settings → Payments → Store credit from returns expires after (0 keeps it forever) |
| Given by hand | On the date you chose, or never |
| Given back by a return or void of a sale it paid for | When the credit it came from would have |
| A voided gift card | When 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
| Column | Meaning |
|---|---|
| code | The 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. |
| balance | Required: what the card still holds, such as 25.50. |
| expires_at | The last day it can be spent, YYYY-MM-DD, today or later. Empty: it never expires. |
| customer | An existing customer's phone number or email address. |
| note | Up 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
| Event | Debit | Credit |
|---|---|---|
| Points earned, or added by hand | Loyalty rewards (6100) | Loyalty points liability (2500) |
| Points taken back by a return or void, or taken off by hand | Loyalty points liability | Loyalty rewards |
| Points, store credit or a gift card spent on a sale | Its liability, as a line of the sale's journal | The sale's own lines |
| A gift card sold or reloaded | The sale's own lines | Gift card liability (2400), as a line of the sale's journal; never sales revenue |
| Store credit refunded on a return | The return's own lines | Store credit payable (2300), as a line of the return's journal |
| Store credit given by hand | Customer goodwill (6150) | Store credit payable |
| Store credit taken off by hand | Store credit payable | Customer goodwill |
| Store credit expired | Store credit payable | Other income (4900) |
| A gift card voided by hand | Gift card liability | Store credit payable (its buyer), or Other income (no customer) |
| A gift card issued from the back office | Gift cards given away (6160) | Gift card liability |
| Gift cards imported, one journal per batch of 100 | Opening balance equity (3100) | Gift card liability |
| A gift card expired with money on it, while breakage is on | Gift card liability | Gift 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 cards | Loyalty, Gift cards (in the Settings group) |
| Add or take off points by hand | Add or take off points by hand |
| Pay with points | Use the POS at the till, or Create sales on a back-office sale |
| Give or take off store credit by hand | Set credit limits, tax exemption and store credit |
| Sell and reload gift cards at the till | Sell and reload gift cards |
| Take gift cards as payment | Take gift cards as payment |
| Void a gift card by hand | Void gift cards |
| Block and unblock a gift card | Block and unblock gift cards |
| Show a card's code, give it a new PIN, email its code again, print its slip | Show gift card codes and set new PINs (Administrator only to begin with) |
| The Gift cards screen, its export, a card's note and Extend expiry | Manage gift cards |
| Issue a card with nothing paid for it | Issue gift cards with nothing paid (Administrator only to begin with) |
| Import existing cards from a file | Import existing gift cards (Administrator only to begin with) |
| The four loyalty points reports | Sales reports, or See the loyalty points reports |
| The gift card report | Sales reports |
| A customer's Loyalty tab | See 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
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
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.
- 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.
- 2The lines' points are added up and rounded once for the whole sale, and a tier's multiplier scales the total.
- 3A sale keeps the % each line earned at: changing a rate later changes only the sales made after it.
- 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
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.
- 1The first tier always starts at 0 points, so every customer is in one. Two tiers cannot start at the same number of points.
- 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.
- 3The tier counts the points earned before the sale.
- 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.
- 1Walk-in sales earn nothing: a sale earns only for the customer on it.
- 2The basis is each line's amount after its own discount and its share of the sale discount, before tax.
- 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.
- 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.
- 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
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.
- 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.
- 2Points and gift cards never pay for a gift card.
- 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.
- 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
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
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.
- 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.
- 2At the till, Store credit pays no more than the customer holds, spending the credit that expires soonest first.
- 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.
- 4Archived customers cannot be given new store credit.
- 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.
- 1The kind is fixed once the product is created.
- 2A gift card holds no stock and is never taxed when sold; tax is charged on what it buys.
- 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
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).
- 1A card is sold at its value: no tax, no discount, no points. A back-office sale refuses a gift card.
- 2A sale with a gift card takes no sale-wide discount; line discounts on the other lines still work.
- 3Points, gift cards, store credit and exchange credit cannot buy a gift card; Cash, Card, Bank transfer and Other can.
- 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
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.
- 1No PIN is needed to see a balance, and the code is not kept.
- 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.
- 3A card that is void, blocked, expired or empty is refused, as is more than it holds.
- 4Code lookups are limited per person: 30 lookups and 10 codes not found in 15 minutes.
- 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.
- 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.
- 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.
- 3A card sold by mistake goes back through its sale instead, with a void or a return, which gives the money back.
- 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).
- 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.
- 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.
- 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.
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_dumpandpg_restore, of the server's major version or newer. On Windows they are inC:\Program Files\PostgreSQL\17\bin. - Your
DATABASE_URL. The examples usepostgresql://posify:a-strong-password@127.0.0.1:5432/posify: put yours in its place. - For the
pnpmcommands: a terminal in the app's folder (the one with.env), or in the container (Docker Image).
What to keep, and where it lives
| What | Where it lives | How to keep it |
|---|---|---|
| Business data | The PostgreSQL database: sales, stock, customers, journals, settings and sign-ins. | pg_dump, before every upgrade and every night (steps 1 to 4). |
| Files | Your 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
Back up the database now
pg_dumpwrites 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 macOSbashpg_dump --format=custom --file=posify-$(date +%Y%m%d-%H%M).dump "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"Windows PowerShellpowershell& "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.dumpis in the current folder, and it is not empty. - 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.
- 1Create
/var/backups/posifyfirst, writable by the account whose crontab runs the lines. - 2In a crontab, write each
%as\%, as above: crontab treats%as a special character. - 3The second line deletes backups older than 14 days. Keep as many as you need.
crontab -ebash30 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 -deleteCheck: The next morning,
ls -lh /var/backups/posifylists a new.dumpfile. - 1Create
- 3
Back up PostgreSQL that runs in Docker
Run the tools inside the database container and copy the file out.
posify-pgis the database container's name in these examples.bashdocker exec posify-pg pg_dump -U posify --format=custom --file=/tmp/posify.dump posify docker cp posify-pg:/tmp/posify.dump ./posify.dumpCopy the file withdocker cp, as here. Redirectingdocker exec … pg_dumpoutput into a file with>damages it in Windows PowerShell, which rewrites the bytes as text.Check:
posify.dumpis in the current folder on the host, and it is not empty. - 4
Back up a managed database
pg_dumpandpg_restorework 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
Restore a backup
A restore replaces Posify's tables with the backup's. Stop the app first (
sudo systemctl stop posify,pm2 stop posifyordocker stop posify), then run:- 1
--clean --if-existsdrops each of Posify's tables before restoring it. - 2
--single-transactionmakes the restore all or nothing. - 3
--no-ownermakes the user in the string the owner of what it restores. - 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. - 5Start the app, then run
pnpm accounting:reconcile --dry-run(step 10).
bashpg_restore --clean --if-exists --no-owner --single-transaction \ --dbname="postgresql://posify:a-strong-password@127.0.0.1:5432/posify" ./posify-20260101-0300.dumpCheck: The app opens with the backup's data, and the reconcile ends with
Dry run: nothing was written. - 1
- 6
Restore into PostgreSQL in Docker
Copy the file into the database container and restore it there. Stop the app first.
bashdocker 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.dumpCheck: The command ends without an error, and the app opens with the backup's data after you start it.
- 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.
bashsudo -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.dumpCheck: A test copy of the app whose
DATABASE_URLends in/posify_checkopens with the backup's sales and products. - 8
Get back into the owner account
pnpm create-admincreates 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.- 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.
- 2No account with that email: one is created on the Administrator role, and made the owner unless another active owner exists.
- 3The password: the one you type. Without one,
ADMIN_PASSWORDfrom.envis used. If that is empty too, a new account gets a random password, printed once, and an existing account keeps its password. - 4Setting a password ends every open session of that account.
- 5If the business was not yet marked installed, the command marks it, and the install wizard closes.
bashpnpm create-admin you@example.com "a-new-password" "Your Name".env.exampleshipsADMIN_PASSWORD=change-me. If that line is still in.envand you type no password, the password becomeschange-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
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.bashpnpm create-admin you@example.com "a-new-password" --reset-2faIt 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
Check the books
Every sale, purchase, payment and stock change posts a journal.
pnpm accounting:reconcilereplays 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.- 1Exit code 0: the books follow the documents.
- 2Exit code 1: something failed, or the trial balance does not balance. Read the output.
- 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. - 4Exit code 3: it stopped on
--budget. Run it again to continue. - 5
--fromand--toread the days in the business's time zone.--kindtakes kinds such assale,sale_return,goods_receipt,supplier_billandexpense; an unknown kind stops the command and lists the known ones. - 6
--rebuildworks 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.
bashpnpm 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 JSONThe nightlyaccounting-reconcilejob 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
Run these commands in the Docker image
The image ships the tools these commands need.
pnpm db:migratereadsDATABASE_URLstraight from the container's environment. The other commands read a.envfile, which the image does not hold, so create an empty one first: the container's environment still supplies every value.bashdocker 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-runposifyis the app container's name. The image has nopg_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, aftercd /app.Check:
pnpm db:migrate --listends 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).
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-runis a health check that writes nothing. Exit code 0 means everything is in order. - Schedule database backups (Backups & Recovery).
pnpm db:migrate --list # every migration: applied
pnpm accounting:reconcile --dry-run # exit code 0: the books are in orderBranches 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.
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:migrateis 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.mdfor 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
| Rule | What it means |
|---|---|
| Only what is missing | The 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 nothing | Every pending migration is applied in one transaction. If one fails, nothing is applied: fix the cause and run it again. |
| Safe to run twice | With nothing pending it says "The database is up to date. Nothing to apply." |
| One run at a time | A second run on the same database waits for the first to finish. |
| Unknown migrations | It refuses a database that holds a migration this code does not know: a newer or a different build migrated it. |
| Changed migrations | It 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 database | DATABASE_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
Check Node.js and PostgreSQL
The release's
package.jsonnames the minimum Node.js underengines(24.11.0 for 1.0). A release that needs a newer PostgreSQL than 16 says so in its section.bashnode --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
Put the new code in a new folder
Unzip the new release into a new folder and copy your
.envinto 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.envwith the new.env.example.Check: The new folder holds the release and your
.env, and the old folder is untouched. - 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.envdoes not have. Most new names are optional; the release's section says when one is required.Linux and macOSbashcomm -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 PowerShellpowershell$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 InputObjectCheck: The list is empty, or holds only names you have decided about.
- 4
Turn on maintenance mode
Settings → Maintenance Mode closes the app to everyone whose address is not on its allow-list.
- 1Switch on Enable Maintenance Mode.
- 2Under Allowlisted IP addresses, add your own IP address, one per line, to keep working.
- 3Optional: a Headline, a Maintenance Message, a background image, and Show countdown with Expected back online.
- 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
Back up the database
Use your own
DATABASE_URL. For PostgreSQL in Docker and managed databases, see Backups & Recovery.Linux and macOSbashpg_dump --format=custom --file=posify-$(date +%Y%m%d-%H%M).dump "postgresql://posify:a-strong-password@127.0.0.1:5432/posify"Windows PowerShellpowershell& "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
.dumpfile is there, and it is not empty. - 6
Install and build the new release
In the new folder, install the packages and build. The old app keeps running meanwhile.
- 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.
bashpnpm install --frozen-lockfile pnpm buildCheck: The build ends with
check:chunks — … preloaded chunk references, all in .next. - 1On a server with 8 GB of RAM or less, or while the old app runs beside it, build with
- 7
Stop the app and run the migrations
The app never changes its tables itself, so the new code needs
pnpm db:migrateto have run first. Stop the app (sudo systemctl stop posifyorpm2 stop posify), then, in the new folder:- 1Then do any other step the release's section lists for a release you cross.
bashpnpm db:migrate --dry-run # what will be applied; writes nothing pnpm db:migrate # apply itCheck: 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
Start the new code, then turn maintenance mode off
Point your service at the new folder and start it.
- 1systemd: set
WorkingDirectoryin/etc/systemd/system/posify.serviceto the new folder, then runsudo systemctl daemon-reloadandsudo systemctl start posify. - 2pm2: run
pm2 delete posify, then thepm2 startcommand from the new folder (Node Server), thenpm2 save. - 3Then open Settings → Maintenance Mode, switch Enable Maintenance Mode off and click Save Maintenance Settings.
Check: The app opens for everyone, with your data.
- 1systemd: set
- 9
Check the books
pnpm accounting:reconcile --dry-runwrites nothing. Its exit code says what to do: in bash,echo $?right after the command shows it; in PowerShell,$LASTEXITCODE.- 10: the books follow the documents. Nothing to do.
- 22: something needs posting or a look. Run
pnpm accounting:reconcilewithout--dry-runto post what is missing and rebuild the customer and supplier balances. - 3Still 2 after that: a journal differs from the posting rules. Accounting → Books check names it and the repair.
- 41 or 3: see step "Check the books" in Backups & Recovery.
bashpnpm accounting:reconcile --dry-runCheck: The command exits with code 0.
- 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
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.- 1Turn on maintenance mode and back up the database (steps 4 and 5).
- 2Put the new release into your GitHub repository and push. The workflow builds and pushes a new image (Docker Image).
- 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.
- 4Turn maintenance mode off.
bashdocker 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 posifyto 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
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.
- 1Node server: stop the app, restore the backup (Backups & Recovery), and point the service back at the old folder.
- 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.
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 -funder systemd, orpm2 logs posify. - The Docker image:
docker logs posify --tail 100. - A deploy panel: the application's logs.
- Commands such as
pnpm db:migrateprint their own messages in the terminal. - The till: its banner and dialogs.
Installing and building
| Problem | What to do |
|---|---|
| pnpm install fails | Check 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 memory | The 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 fails | No 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 refused | Log 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 found | pnpm 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
| Problem | What to do |
|---|---|
| DATABASE_URL not set | The 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 refused | password 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 denied | permission 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 missing | relation "…" 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
| Problem | What to do |
|---|---|
| Database check fails | Its 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 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. |
| 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 found | The 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
| Problem | What to do |
|---|---|
| Sign-in fails here | Sign-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 configuration | The 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 elsewhere | Links 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 lost | Forgot 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 lost | Sign 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 limit | Behind 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 all | Sign 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
| Problem | What to do |
|---|---|
| Jobs answer 401 | CRON_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 stopped | The 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 Failing | It 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 found | A 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 hour | Digests 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 secret | Change 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
| Problem | What to do |
|---|---|
| No password reset emails | Email 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 retried | Emails and texts that fail their first try are retried only by the email-deliveries job. Check that it runs (Background Jobs). |
| No text messages | Texts 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 used | SMTP 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 nothing | For 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 unavailable | Storage 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 nginx | nginx 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 size | Images 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
| Problem | What 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 PDF | The same cause: the server has no Chrome or Chromium. The email itself still goes out. |
| Empty boxes in PDFs | Bengali, 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 image | The 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
| Problem | What 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 offline | The 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 selling | The 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 review | The 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 time | Receipts 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 marks | ZPL 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.