Documentation

Install, run, and deploy VendKit.

Set up VendKit on your own server, run it locally, understand its configuration, and deploy it with confidence. Every command is ready to copy.

Reviewed against the VendKit repository README and backup guide on November 21, 2026.

At a glance

Runtime
Docker Compose
Database
PostgreSQL 16+
Local URL
localhost:3000
Licence
AGPL-3.0
Open the repository
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.

Prerequisites

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

Product images and backup archives grow faster than the database. Keep the vendkit-data volume on durable disk, monitor free space and copy archives off the server. A backup on the same disk is not disaster recovery.

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.

Terminal
docker --version
docker compose version
git --version

For local development, confirm the language and database tools:

Terminal
node --version
pnpm --version
psql --version

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
  1. 01

    Clone the repository

    Download the source into a directory on the server. This is the public VendKit repository.

    Terminal
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 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.

    Terminal
    POSTGRES_PASSWORD="$(openssl rand -hex 24)"
    JWT_SECRET="$(openssl rand -hex 32)"
    API_KEY="$(openssl rand -hex 32)"
    
    awk -v pw="$POSTGRES_PASSWORD" -v jwt="$JWT_SECRET" -v key="$API_KEY" '
      /^POSTGRES_PASSWORD=/ { print "POSTGRES_PASSWORD=" pw; next }
      /^JWT_SECRET=/        { print "JWT_SECRET=" jwt; next }
      /^API_KEY=/           { print "API_KEY=" key; next }
      { print }
    ' .env.example > .env
    
    chmod 600 .env
  3. 03

    Start the stack

    The API container applies migrations automatically. The first build can take a few minutes.

    Terminal
    docker compose up -d --build
  4. 04

    Create the first account

    Open the app and create the administrator account. Public registration closes after that.

Running on a public server? Set APP_URL to your HTTPS origin in .env before starting the stack. The default is http://localhost:3000.

Check the installation

Both containers should report healthy and the health endpoint should return a successful response.

Terminal
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

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.

Terminal
git pull
docker compose up -d --build

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
  1. 01

    Clone the repository

    Download the source and move into the project root.

    Terminal
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 02

    Install dependencies

    Install the workspace packages with pnpm.

    Terminal
    pnpm install
  3. 03

    Create the database

    Create a local PostgreSQL database named vendkit. You can use createdb or your PostgreSQL client.

    Terminal
    createdb vendkit
  4. 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.

    .env
    cp apps/api/.env.example apps/api/.env
    cp packages/database/.env.example packages/database/.env
    cp apps/web/.env.example apps/web/.env
  5. 05

    Apply migrations

    Run the database migrations before starting the apps.

    Terminal
    pnpm db:migrate
  6. 06

    Start the development servers

    Run the web app and API in watch mode.

    Terminal
    pnpm dev

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 API
  • pnpm buildProduction build for the workspace
  • pnpm lintLint the workspace
  • pnpm check-typesType-check the workspace
  • pnpm testRun the test suite
  • pnpm db:migrateCreate or apply development migrations
  • pnpm db:studioOpen Prisma Studio

Before opening a pull request

Run lint, type checks, tests and the production build:

Terminal
pnpm lint && pnpm check-types && pnpm test && pnpm 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

Local values live in apps/api/.env, packages/database/.env and apps/web/.env. Docker reads the root .env file.
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.
Do not put business details, invoice numbering or terms in environment variables. They belong in Settings and are included in backups.

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-db

The PostgreSQL data directory: products, customers, orders, payments, invoices, inventory and settings.

vendkit-data

Uploaded 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.

Terminal
docker compose exec api ls -lh /data/backups

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.

Terminal
mkdir -p offsite-backups
docker compose cp api:/data/backups/. ./offsite-backups/

Restore a backup

Restore from Settings → Backup & Restore. The archive is validated before any current data is replaced.

  1. 1Create a fresh backup of the current data, even though a safety snapshot is created by default.
  2. 2Upload the archive you want to restore from the backup screen.
  3. 3Confirm the restore. The manifest version must match the running application.
  4. 4Wait for the job to finish and check the backup history for the result.
  5. 5Open an order, an invoice and a product image to confirm the restored data.
Restores replace business data. Users and backup history survive, but writes made during the swap window are not guaranteed to be preserved. Run restores during low traffic.

No automatic scheduler

This release does not include a background scheduler. Use your host cron or platform scheduler to trigger host-level snapshots, and download archives regularly. Keep the backup directory writable by the API process and on durable storage.

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
  1. 01

    Set the public URL

    Set APP_URL to the final HTTPS origin in .env. It is used for CORS and generated links.

    .env
    APP_URL=https://your-domain.example
  2. 02

    Start the stack

    Build and start the web app, API and PostgreSQL. Migrations run automatically when the API container starts.

    Terminal
    docker compose up -d --build
  3. 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

    Caddyfile
    vendkit.example.com {
      encode zstd gzip
      reverse_proxy 127.0.0.1:3000
    }

    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.

  4. 04

    Verify the deployment

    Confirm both containers are healthy and check the API health endpoint.

    Terminal
    docker compose ps
    docker compose exec api wget -qO- http://localhost:4000/api/health
  5. 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.

Terminal
git pull
docker compose up -d --build

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.
Terminal
git rev-parse --short HEAD
docker compose exec api ls -lh /data/backups

Apply the update

Pull the latest source and rebuild both application images. The database container is left running.

Terminal
git pull
docker compose up -d --build

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.

Terminal
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

Roll back

If the new version fails, return to the previous commit and rebuild. Then restore the backup you took before the upgrade.

Terminal
git log --oneline -5
git checkout <previous-commit>
docker compose up -d --build
Database migrations are forward-only. If the upgrade changed the schema, an older commit may not run against the newer database. Restore the pre-upgrade backup before starting the old code.

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 health
  • docker compose logs -f --tail=100 apiFollow the API log; use web for the Next.js app
  • docker compose restart apiRestart one service without rebuilding
  • docker compose exec api wget -qO- http://localhost:4000/api/healthAsk the API and database for their status
  • docker system dfSee how much space images and containers use
  • docker compose downStop and remove containers and the network; volumes stay
  • docker compose up -dStart the existing containers again
Never add --volumes to docker compose down unless you intend to delete the database and every uploaded file. Use it only when you are deliberately destroying the installation.

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

Generate a new value, update .env and restart the stack. Rotating JWT_SECRET invalidates existing access tokens. API_KEY must stay identical in the web and API containers. If you change the database password, change it inside PostgreSQL as well as in .env.

Report a vulnerability privately

Do not open a public issue for a security problem. Follow the repository security policy and contact the maintainer 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.

Terminal
docker compose logs --tail=200 api

Validate the Compose file

Check that .env is present and the Compose file resolves before rebuilding.

Terminal
docker compose config --quiet

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.

Before changing volumes, ports or environment values, download a fresh backup. If you cannot explain how to restore it, do not run the change on a live store.

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/web

    Next.js frontend and server-side API proxy.

  • apps/api

    NestJS API, business logic, invoice PDFs and backups.

  • packages/database

    Prisma schema, migrations and generated client.

  • packages/ui

    Shared UI primitives for the application.

  • docker-compose.yml

    Web, 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.