Full guide

Two ways to install

OficinaOS is always the same program — what differs is how it runs on the shop PC. The installer picks the right path automatically, but it helps to understand both:

Docker is the normal, recommended way: a free program that packages the app and database in isolated «containers». It needs a processor feature called virtualization — most PCs have it, but some ship with it disabled in the BIOS or don't support it at all.

Portable mode exists for those PCs: a single bundle with everything inside (the app, the PostgreSQL database and the runtime) — no Docker, no virtualization, no Windows services.

Normal install — Docker (once, ~10 minutes)

Download the installer ZIP, extract to a folder (e.g. C:\OficinaOS) and double-click INSTALAR.bat. If Windows SmartScreen warns: «More info» → «Run anyway».

The installer does everything: checks whether the PC can run Docker, installs Docker Desktop if missing, generates passwords and secrets, downloads the app and starts it. If it asks for a reboot, reboot and run INSTALAR.bat again.

At the end the browser opens at http://localhost:4000. First login: user admin, password braindead — the app forces you to change both.

On Linux or Mac there's no auto-installer — Docker is used directly:

              git clone https://github.com/braindeadpt/OficinaOS.git
cd OficinaOS && cp .env.example .env
docker compose up -d
docker compose exec app bun run db:seed
            

The «virtualization support not detected» error

If the PC can't run Docker, the installer detects it before trying and offers two options:

• Enable it in the BIOS — reboot, press F2/F10/DEL/ESC at startup, look for «Intel VT-x», «Virtualization Technology» or «SVM Mode», enable and save (F10). The normal Docker path then works.
• Portable install — the installer downloads oficinaos-portable.zip (~540 MB) and runs without Docker: same app, same database, same features.

Day to day — start, stop, files

Once installed, daily use is a double click on a file. The names are the same in both modes — only the folder changes:

• Docker mode: in the folder where you extracted the installer.
• Portable mode: inside the oficinaos-portable folder — data lives in data\, backups in app\uploads\backups.
• Other shop devices (tablet, phone, another PC) install nothing — they open http://<PC-IP>:4000 in a browser.

Backups and restore

Backups are compressed files (.sql.gz) containing the whole database. The app shows the last backup status under Settings → Shop → Backups — it works the same in both modes.

In Docker mode a dedicated service backs up every 24 hours, keeps 14 days, and can optionally copy to external storage (S3, Backblaze, etc.) and automatically verify restores.

In portable mode the backup runs at every startup and via BACKUP.bat. Restoring is done with RESTAURAR.bat (pick a file from backups). Since there's no automatic off-PC copy, copy the app\uploads\backups folder to an external drive or USB stick — backups on the same disk don't protect against failure, theft or ransomware.

Updates

The app shows a banner when a new version exists. To update, double-click ATUALIZAR.bat — it backs up, downloads the new version and restarts. Database migrations run by themselves.

Practical difference: Docker only downloads what changed; portable re-downloads the whole bundle (~540 MB). Docker can also update fully automatically (Watchtower).

In the shop — phones, tablets and PCs

Any device on the shop's Wi-Fi opens the app in a browser — nothing to install. Just type the address the setup gives you and log in:

Works without internet for daily use. Bookmark the address — it never changes.

              http://192.168.1.33:4000   # the server PC's address
            

Icon on the phone's home screen

To open with one tap, like a normal app — takes 10 seconds:

• iPhone/iPad: Safari → Share button → “Add to Home Screen”
• Android: Chrome → ⋮ menu → “Add to Home Screen”
• With remote access on, Android may even offer “Install app” — a real install

Outside the shop — remote access

With the shop PC on, a free Cloudflare Tunnel gives the shop its own https:// address — no router changes, works with any ISP, even the ones blocking ports (CGNAT).

It lets staff check the app from anywhere and makes customer links — tracking, quotes, warranty QR — open everywhere.

• Create a free Cloudflare account + a domain (~$10/year)
• In the Zero Trust dashboard: create the tunnel and copy the token
• Two lines in the .env file and restart the app
• In the app: Settings → Shop → Tracking base URL → the public address

Private by default

The tunnel is optional: the app keeps working 100% on the local network even without internet. Customer data stays in the shop — Cloudflare only carries encrypted traffic while the tunnel is on.

Anyone wanting an extra barrier can enable Cloudflare Access (free): email + code before the login, while customer-facing public pages stay open.

Common problems

The most frequent situations and how to solve each:

Full documentation

This guide covers the essentials. The GitHub repository has the complete technical documentation — detailed install, remote access, mobile devices, backups with off-site copies and how the portable bundle works inside: