On this page
Start here
Choose how you want to run VendKit.
For a real installation, use Docker Compose on a Linux server. For development, run the monorepo locally with Node.js and PostgreSQL.
Docker installation
The recommended path for a production or self-hosted installation. One Compose stack runs the web app, the API and PostgreSQL.
Follow the Docker setupLocal development
Run the web app, API and PostgreSQL locally. Use this path for development, review and contributing.
Set up local developmentPrerequisites
Know what the host needs before you start.
VendKit is small enough for a modest VPS, but it still needs a supported runtime, a domain and a backup plan. Decide these before you install anything.
Production server
Recommended starting point for a single store. VendKit does not publish a hard capacity limit; size the disk for images and backups, not just the database.
- Operating system
- A current 64-bit Linux distribution with Docker support
- Container runtime
- Docker Engine and the Docker Compose plugin
- CPU
- 2 vCPU minimum; 4 vCPU for a busy store
- Memory
- 2 GB minimum; 4 GB recommended
- Disk
- 20 GB plus space for product images and backup archives
- Network
- A public IPv4 or IPv6 address, a domain and ports 80 and 443
Local development
Use the monorepo only when you are working on the code. The Docker path does not need Node.js or PostgreSQL on the host.
- Node.js
- 24 or newer
- pnpm
- 11 or newer
- PostgreSQL
- 16 or newer, running locally
- Git
- Any current version
Ports and exposure
Only the web app is published by Compose. The API and database stay on the internal Docker network.
- Web app
- 3000, published; change with WEB_PORT
- API
- 4000, internal only
- PostgreSQL
- 5432, internal only
- HTTPS
- 443 at the reverse proxy
Disk planning
Before you install
Have these ready so the first run does not stall.
- A Linux host you can administer, with a non-root sudo user
- Docker Engine and the Compose plugin installed
- A domain name with DNS pointed at the server
- A TLS certificate, usually issued by the reverse proxy
- A plan for off-server backups and host updates
- The administrator name and email for the first account
Check the host
Confirm Docker, Compose and Git are available before cloning. If any command is missing, install it first.
For local development, confirm the language and database tools:
Docker installation
From clone to first sign-in.
Follow these steps on a Linux server with Docker and the Compose plugin. The configure command generates the required secrets for you.
Before you begin
- Git installed
- Docker with the Compose plugin
- Persistent storage for the vendkit-db and vendkit-data volumes
- A reverse proxy with HTTPS for public access
- 01
Clone the repository
Download the source into a directory on the server. This is the public VendKit repository.
- 02
Create the environment file
Generate the three required secrets and write them into a new .env file from the template. The command also restricts the file to your user.
- 03
Start the stack
The API container applies migrations automatically. The first build can take a few minutes.
- 04
Create the first account
Open the app and create the administrator account. Public registration closes after that.
Check the installation
Both containers should report healthy and the health endpoint should return a successful response.
If the health check fails, read the API log before changing configuration.
First-run checklist
After the administrator account exists, complete these steps so the workspace matches how you sell.
- Open Settings → Business profile and add the details printed on invoices.
- Review Settings → Invoice for numbering, currency display, due period and terms.
- Add categories, brands and products before creating orders.
- Create a test customer and order, then download the invoice PDF.
- Download a backup and confirm the archive appears in the backup history.
Upgrade later
Pull the latest source and rebuild. Applied migrations are skipped, so the command is safe to repeat.
Development
Run VendKit locally.
Use this path when working on the codebase. You need Node.js 24+, pnpm 11+ and PostgreSQL 16+.
Before you begin
- Node.js 24 or newer
- pnpm 11 or newer
- PostgreSQL 16 or newer
- Git
- 01
Clone the repository
Download the source and move into the project root.
- 02
Install dependencies
Install the workspace packages with pnpm.
- 03
Create the database
Create a local PostgreSQL database named vendkit. You can use createdb or your PostgreSQL client.
- 04
Create the environment files
Copy the API, database and web environment templates. Set the same DATABASE_URL in the API and database files, and the same API_KEY in the API and web files.
- 05
Apply migrations
Run the database migrations before starting the apps.
- 06
Start the development servers
Run the web app and API in watch mode.
Environment files
The local setup uses three environment files: apps/api/.env, packages/database/.env and apps/web/.env. Keep DATABASE_URL and API_KEY aligned across the files.
Never commit an .env file.
Local URLs
- Web app
- http://localhost:3000
- API
- http://localhost:4000/api
- Health check
- http://localhost:4000/api/health
Useful commands
pnpm devDevelopment server for web and APIpnpm buildProduction build for the workspacepnpm lintLint the workspacepnpm check-typesType-check the workspacepnpm testRun the test suitepnpm db:migrateCreate or apply development migrationspnpm db:studioOpen Prisma Studio
Before opening a pull request
Run lint, type checks, tests and the production build:
Configuration
Environment variables
The API validates required environment variables at startup and refuses to boot with a list of every problem. Business details and invoice settings are stored in the database.
Local development
- DATABASE_URL
- PostgreSQL connection string used by the API and Prisma.
- JWT_SECRET
- Access-token signing secret, at least 32 characters.
- API_KEY
- Shared key used by the web app to call the API. Keep it private.
- APP_URL
- Public web URL. Compose passes it to the API as the allowed CORS origin.
- ALLOW_PUBLIC_REGISTRATION
- Off by default. Enable only if you intentionally want sign-up after the first account.
- BACKUP_SAFETY_SNAPSHOT
- Creates a safety backup before a restore. Enabled by default.
Full environment reference
Compose reads the root .env file. The API and web services receive their values from Compose in Docker, or from their own files in local development.
Compose (.env)
Read by docker compose
POSTGRES_PASSWORD- Required
- Password for the bundled PostgreSQL service. Use URL-safe characters only; it is embedded in DATABASE_URL.
JWT_SECRET- Required (32+ chars)
- Signs access tokens.
API_KEY- Required
- Shared key between the web app and the API.
APP_URL- http://localhost:3000
- Public web URL. Compose passes it to the API as CORS_ORIGINS.
ALLOW_PUBLIC_REGISTRATION- false
- Allow sign-up after the first administrator.
WEB_PORT- 3000
- Host port published for the web container.
APP_VERSION- 0.1.0
- Version recorded in backup metadata.
API
Validated at startup
DATABASE_URL- Required
- PostgreSQL connection string used by the API and Prisma.
JWT_SECRET- Required (32+ chars)
- Signs access tokens.
API_KEY- Required
- Shared key between the web app and the API.
PORT- 4000
- API port inside the container.
CORS_ORIGINS- From APP_URL
- Comma-separated allowed web origins. Compose derives it from APP_URL.
ALLOW_PUBLIC_REGISTRATION- false
- Allow sign-up after the first administrator.
IMAGE_STORAGE_DIR- uploads/images
- Image upload directory. Compose sets /data/images.
IMAGE_MAX_FILE_SIZE- 5 MB (bytes)
- Largest accepted image upload.
BACKUP_STORAGE_DIR- uploads/backups
- Backup archive directory. Must not be inside the image directory. Compose sets /data/backups.
BACKUP_MAX_FILE_SIZE- 1 GB
- Largest accepted backup upload or archive.
BACKUP_MAX_EXTRACTED_SIZE- 2 GB
- Largest uncompressed restore accepted.
BACKUP_RESTORE_TRANSACTION_TIMEOUT_MS- 10 minutes
- Timeout for snapshot and restore transactions.
BACKUP_SAFETY_SNAPSHOT- true
- Create a safety backup before restoring.
APP_VERSION- 0.1.0
- Version recorded in backup metadata.
Web
Must match the API key
NEST_API_URL- Required
- API base URL including /api. Compose sets http://api:4000/api.
API_KEY- Required
- Shared key between the web app and the API.
Data and backups
Know where your data lives.
VendKit stores business records in PostgreSQL and uploaded files on disk. Both live in named Docker volumes and must survive container replacement.
vendkit-dbThe PostgreSQL data directory: products, customers, orders, payments, invoices, inventory and settings.
vendkit-dataUploaded images and backup archives written by the API container.
Paths inside the API container
Backups are written to the API host filesystem, not to a cloud service. The backup directory must not sit inside the image directory.
- /data/images
- Image uploads, mounted from the vendkit-data volume.
- /data/backups
- Backup archives, also on the vendkit-data volume.
What a backup contains
Each archive is a versioned, gzip-compressed tar file with a manifest, checksums and the business data.
- Categories, brands, products and product images
- Customers, orders, order items, payments and returns
- Invoices and document sequences
- Inventory movements and business settings
- Every uploaded image referenced by the database
What it leaves out
Some records are deliberately excluded so a restore cannot lock you out or overwrite its own history.
- User accounts, password hashes and refresh tokens
- Backup and restore history
- Environment variables, database URLs and secrets
List backups on the server
Archives are created from Settings → Backup & Restore. The API writes them to /data/backups, which is the vendkit-data volume.
Copy archives off the server
Download backups from the app, or copy the archive directory to your workstation. Storage on the same host is not enough.
Restore a backup
Restore from Settings → Backup & Restore. The archive is validated before any current data is replaced.
- 1Create a fresh backup of the current data, even though a safety snapshot is created by default.
- 2Upload the archive you want to restore from the backup screen.
- 3Confirm the restore. The manifest version must match the running application.
- 4Wait for the job to finish and check the backup history for the result.
- 5Open an order, an invoice and a product image to confirm the restored data.
No automatic scheduler
Deployment
Deploy VendKit to production.
Run one Compose stack behind HTTPS. Keep the API private and back up both persistent volumes.
Before deploying
- A Linux server with Docker and the Compose plugin
- A domain pointed at the server
- A reverse proxy with a valid TLS certificate
- Durable storage and an off-server backup plan
- 01
Set the public URL
Set APP_URL to the final HTTPS origin in .env. It is used for CORS and generated links.
- 02
Start the stack
Build and start the web app, API and PostgreSQL. Migrations run automatically when the API container starts.
- 03
Put it behind HTTPS
Terminate TLS at a reverse proxy such as Caddy, nginx or Traefik. Forward traffic to the web app only.
Example Caddy configuration
This is a minimal reverse proxy for a single installation. Adapt it to your domain and server setup. Replace vendkit.example.com with your domain. If you changed WEB_PORT, update the upstream port.
- 04
Verify the deployment
Confirm both containers are healthy and check the API health endpoint.
- 05
Create the first account
Open the public URL and create the administrator account. Public registration closes afterward.
Run it safely
- Run one API instance. Authentication rate limiting is in memory.
- Do not expose the API port publicly.
- Persist the vendkit-db and vendkit-data volumes.
- Copy backup archives off the server as part of your host backup policy.
- Use HTTPS. Production session cookies are marked Secure.
Upgrade a production install
Pull the latest source and rebuild. Applied migrations are skipped, so the command is safe to repeat.
Upgrades
Upgrade and roll back safely.
VendKit applies database migrations when the API container starts. Plan the update, keep a known-good backup and verify the stack before you close the window.
Before you upgrade
Record what is running and protect the current data.
- Read the release notes or the repository commits you are about to deploy.
- Create a backup from Settings → Backup & Restore and download it.
- Note the current commit so you can return to it.
- Choose a low-traffic window; the API restarts during the rebuild.
Apply the update
Pull the latest source and rebuild both application images. The database container is left running.
Applied migrations are skipped, so the command is safe to repeat. The first build after a large change can take several minutes.
Verify after the upgrade
Confirm both containers are healthy, then sign in and check an order, an invoice and a product image.
Roll back
If the new version fails, return to the previous commit and rebuild. Then restore the backup you took before the upgrade.
Replace previous-commit with the commit you recorded. Keep the backup until the new version has been stable for a few days.
Operations
Operate it without surprises
Check the stack, read the logs and keep the volumes. Most incidents are visible in docker compose ps and the API log.
Backups
Create a complete archive in Settings → Backup & Restore. Copy archives off the server as part of your host backup routine.
Health check
GET /api/health reports API and database status for containers and monitoring.
Deployment
Do not expose the API port. Run one API instance, persist both volumes and terminate HTTPS at a reverse proxy.
Restore
Restores validate the archive and replace business data in one transaction. A safety snapshot is created first by default.
Everyday commands
Run these from the repository root on the server.
docker compose psContainer state and healthdocker compose logs -f --tail=100 apiFollow the API log; use web for the Next.js appdocker compose restart apiRestart one service without rebuildingdocker compose exec api wget -qO- http://localhost:4000/api/healthAsk the API and database for their statusdocker system dfSee how much space images and containers usedocker compose downStop and remove containers and the network; volumes staydocker compose up -dStart the existing containers again
There is no automatic backup scheduler or background worker in this release. Host cron and off-server copies are your responsibility.
Security
Harden a self-hosted installation.
You control the server, the secrets and the data. These are the minimum practices for a real store.
Use HTTPS
Production session cookies are marked Secure. Plain HTTP will not sign users in. Terminate TLS at a reverse proxy and redirect HTTP to HTTPS.
Keep the API private
Only the web app is published. The browser calls Next.js, which proxies to the API with the shared key. Do not publish port 4000.
Guard the secrets
Use long random values for POSTGRES_PASSWORD, JWT_SECRET and API_KEY. Keep .env at mode 600, never commit it and never reuse a value across installations.
Keep registration closed
The first account becomes the administrator and public sign-up then closes. Enable ALLOW_PUBLIC_REGISTRATION only when you intentionally want self-service accounts.
Manage people
Administrators can create members and reset passwords from Team. Remove access you no longer need and avoid sharing one administrator account.
Protect backups
Archives contain customer contact details and business records. Store copies on encrypted, access-controlled storage and delete them when they are no longer needed.
Harden the host
Keep the operating system and Docker updated, restrict SSH, and allow only the ports you need: SSH, 80 and 443. Do not expose PostgreSQL.
Track updates
Watch the repository for releases and security fixes. Read the upgrade guide, back up first and verify after every update.
If a secret leaks
Report a vulnerability privately
VendKit is licensed under AGPL-3.0. If you run a modified version as a network service, the licence requires you to offer its source code to the people using it.
Troubleshooting
Fix the common failures.
Start with the container state and the API log. VendKit validates its environment at startup and reports missing or invalid values in the log.
Read the API log
The API refuses to boot when a required variable is missing and lists every problem it found.
Validate the Compose file
Check that .env is present and the Compose file resolves before rebuilding.
Compose stops with “Set … in .env”
The root .env file is missing or a required value is empty. Copy .env.example to .env and generate the secrets again.
The API container restarts repeatedly
Read the API log. A missing DATABASE_URL, JWT_SECRET or API_KEY, or a JWT_SECRET shorter than 32 characters, stops the API at startup.
Sign-in loops or does nothing
Production cookies are Secure. Use the HTTPS URL, not a plain HTTP address, and make sure APP_URL matches the public origin.
The web app cannot reach the API
Confirm the API is healthy. In Compose, NEST_API_URL must be http://api:4000/api and API_KEY must be identical in the web and API services.
Port 3000 is already in use
Set WEB_PORT to another port in .env, restart the stack and update the reverse proxy upstream. The container still listens on 3000 internally.
Data disappeared after a restart
The stack was probably removed with volumes. Never use docker compose down --volumes on a real installation. Restore the last backup and keep both named volumes.
A restore is rejected
The manifest version must match the running app, and every checksum and media size must validate. Use an archive whose format matches the running app and check the backup history for the reason.
Builds fail or the app slows down
Check free disk with df -h and Docker usage with docker system df. Prune unused images and build cache only when you have a current backup.
Architecture
One web app, one API, one database
The browser talks only to the Next.js app. Server-side route handlers proxy requests to NestJS with a shared API key, so the API does not need to be publicly exposed.
Repository
apps/webNext.js frontend and server-side API proxy.
apps/apiNestJS API, business logic, invoice PDFs and backups.
packages/databasePrisma schema, migrations and generated client.
packages/uiShared UI primitives for the application.
docker-compose.ymlWeb, API and PostgreSQL, with persistent volumes for data and uploads.
References
The repository is the source of truth
These links point at the VendKit repository. They are updated with the application, not with this website.