vBoxStock replaces spreadsheets and handwritten lists with one browser-based place to track each physical unit from receipt through sale. It records the identifiers that matter for electronics inventory—UID, serial number, and MAC address—along with condition, cost, customer, payment, shipping, and support history.

It was developed with Unraid in mind, but Unraid is not required. vBoxStock is a standard OCI/Docker container and can run on a Docker-compatible Linux server, NAS, home lab, or cloud VM. The application is self-contained: the web server and SQLite database live inside one image, while durable data is stored in a mounted /data directory.

Why vBoxStock exists

General inventory tools can be larger and more complicated than a small reseller needs. vBoxStock focuses on a straightforward workflow:

Receive an individually identifiable device into inventory.
Record its cost, model, condition, and notes.
Complete a sale with customer, payment, shipping, and transaction details.
Revisit the customer or sale later for support and follow-up.
Back up the complete business record without managing a separate database server.

Highlights

Track available and sold devices by UID, serial number, or MAC address.
Start with vSeeBox V3 Plus, V5 Pro, V6 Plus, and V6 Pro, then add any additional model you carry.
Manage the model catalog from the Admin page: rename unused models, archive end-of-life models, reactivate them later, or delete models that have never been used.
Record New, Used, or Refurbished condition and purchase cost.
Capture customer name, phone number, shipped-to address, and shipping notes.
Record Cash, Venmo, or PayPal payments with an optional reference.
Attach transaction notes to a sale and time-stamped support notes to a customer.
Browse inventory, sales, and customers in searchable 10-record pages.
View sale details and complete purchase history for each customer.
Void a sale and return the device to available inventory.
Use Admin and Read-Only accounts with server-enforced permissions.
Create, download, restore, and delete SQLite backups from the Admin page.
Review an audit log of authentication, account administration, backups, and data changes.
Keep all persistent application data in one mounted directory.

Screenshots

User administration, backups, and audit history

Accounts and security

On a new installation—or an upgraded installation with no configured accounts—sign in with:

Username: admin
Password: admin

vBoxStock immediately requires a new password and blocks access to application data until it is changed. Passwords must contain at least 8 characters and are stored as salted scrypt hashes, never as readable text.

Capability	Admin	Read-Only
View and search inventory, sales, customers, and notes	Yes	Yes
Receive inventory and record sales	Yes	No
Edit notes, void sales, or delete records	Yes	No
Manage product models, users, and view the audit log	Yes	No
Create, download, delete, or restore backups	Yes	No
Access the Admin page	Yes	No

Additional protections include HTTP-only SameSite session cookies, a 12-hour inactivity timeout, login throttling, required password confirmation before a restore, automatic session invalidation after a restore, and protection against disabling or deleting the final enabled administrator.

For use outside a trusted private network, place vBoxStock behind an HTTPS reverse proxy. The application does not provide TLS certificates directly.

Quick start with Docker

docker run -d \
  --name vboxstock \
  --restart unless-stopped \
  -p 3000:3000 \
  -e TZ=America/New_York \
  -e PUID=99 \
  -e PGID=100 \
  -v /your/persistent/path:/data \
  ghcr.io/mfwadejr/vboxstock:latest

Open http://YOUR-SERVER-IP:3000, sign in with the initial credentials above, and change the password when prompted.

The host path mounted at /data is essential. Removing the container is safe when this mount remains intact; running without a persistent mount means the database can be lost when the container is replaced. PUID and PGID determine which host user and group own the mounted data. The defaults are Unraid's nobody:users IDs, 99:100.

Docker Compose

The included docker-compose.yml has the explicit project name vboxstock and stores data in ./data alongside the Compose file:

docker compose up -d

The docker run example above is a terminal command. Do not paste it into a Compose or YAML editor; use the Compose file instead.

To update later:

docker compose pull
docker compose up -d

ZimaOS

Use docker-compose.zimaos.yml with ZimaOS's custom app/Compose installer. It includes the required vboxstock project name, ZimaOS dashboard metadata, the application icon, and a persistent data mapping to /DATA/AppData/vboxstock.

If entering the configuration manually, replace any ZimaOS-generated <your project name> placeholder with vboxstock. The angle brackets and placeholder text must not remain in the saved YAML. Do not paste the docker run command into the YAML editor.

ZimaOS settings:

Setting	Value
Project name	`vboxstock`
Image	`ghcr.io/mfwadejr/vboxstock:latest`
WebUI port	`3000`
Container data path	`/data`
ZimaOS host path	`/DATA/AppData/vboxstock`
PUID	`1000`
PGID	`1000`

After installation, open http://YOUR-ZIMAOS-IP:3000. The ZimaOS-specific Compose file supplies the icon automatically through its x-casaos metadata.

Container icon

Use this direct PNG URL in ZimaOS, Unraid, Portainer, or another container dashboard that accepts a custom icon:

https://raw.githubusercontent.com/mfwadejr/vboxstock/main/public/assets/vboxstock-icon-512.png

The included ZimaOS Compose file and Unraid XML template already contain this URL.

Unraid

Use the included vboxstock-unraid.xml template or create a container with these settings:

Setting	Value
Repository	`ghcr.io/mfwadejr/vboxstock:latest`
WebUI port	`3000`
Container data path	`/data`
Suggested Unraid host path	`/mnt/user/appdata/vboxstock`
Network mode	`bridge`
Timezone (`TZ`)	`America/New_York`
PUID	`99`
PGID	`100`

Add TZ, PUID, and PGID as Unraid container variables:

Name	Key	Value
Timezone	`TZ`	`America/New_York`
User ID	`PUID`	`99`
Group ID	`PGID`	`100`

Open the container's WebUI after installation. Updates can be applied with Force Update or through the CA Auto Update Applications plugin. At startup, the container creates /data/backups, applies the configured PUID and PGID ownership to /data, and then runs the application with those IDs.

Data and backups

vBoxStock uses SQLite and does not require MySQL, PostgreSQL, Redis, or another service. Persistent content is stored under /data:

/data/vboxstock.db — active application database
/data/backups/ — locally retained database snapshots

/data is the path inside the container. When /mnt/user/appdata/vboxstock is mapped directly to /data, the Unraid host folder contains vboxstock.db and backups/; it does not contain another nested folder named data.

A fresh installation creates an empty inventory, sales history, and customer list. Only the initial admin account is created. Replacing or upgrading the container preserves existing records because vboxstock.db remains in the mounted host folder. Removing or changing the /data mapping starts a separate empty database, so keep that mapping consistent across upgrades.

The Admin page can create a transactionally consistent snapshot, download it to another device, restore a local snapshot, or upload and restore a downloaded copy. A pre-restore snapshot is created automatically before the active database is replaced.

Product model catalog

Administrators manage product models from Admin → Product models. Active models appear alphabetically in the Receive Product dropdown. Archiving a model removes it from that dropdown but does not change existing inventory, sales, customer history, or reports. Available units that use an archived model can still be sold, and an archived model can be reactivated at any time.

Model names are unique regardless of capitalization and may contain up to 60 characters. An unused model can be renamed or permanently deleted. Once a model has been used by an inventory or sales record, its name is preserved for historical accuracy; archive it and create a new model instead of renaming or deleting it. The Admin page displays separate available and sold usage counts before an archive is confirmed.

The model catalog is stored in vboxstock.db, so it is included automatically in every backup and restore. Upgrading from a release with the original fixed model list migrates the existing database in place and first creates a pre-model-catalog-*.db safety backup in /data/backups.

Backups contain customer information and password hashes. Store downloaded copies securely. Restoring a database also restores the user accounts contained in that backup and signs out every active session. An older backup without user accounts starts the first-login admin / admin setup flow.

Emergency administrator recovery

If every administrator is inaccessible, run this on the Docker host, replacing the container name, username, and temporary password if needed:

docker exec -it vboxstock node server.mjs reset-admin admin NewPassword123

The account is enabled as an administrator and must change the supplied password on its next login. The reset is recorded in the audit log. Because command arguments may briefly appear in process listings, the password can instead be supplied through an environment variable:

docker exec -e RESET_ADMIN_PASSWORD=NewPassword123 -it vboxstock node server.mjs reset-admin admin

Container details

Image: ghcr.io/mfwadejr/vboxstock:latest
Application port: 3000/tcp
Persistent volume: /data
Runtime ownership: configurable with PUID and PGID (99:100 by default)
Health check: GET /api/health
Runtime: Node.js 22
Database: SQLite
Restart policy recommendation: unless-stopped

Intended scope

vBoxStock is designed for a single reseller or small team operating one shared installation. It is not an accounting platform, payment processor, shipping-label service, or public storefront. Payment details are records of how a sale was accepted; vBoxStock does not connect to Cash, Venmo, or PayPal or move money itself.

Updating and versioning

The latest image follows the current stable release. Patch releases contain fixes and small refinements, minor releases add backward-compatible features, and major releases may change setup or access behavior. Keep /data persistently mounted and create or download a backup before significant upgrades.

README.md

vBoxStock