Self-Hosting the Team Server

1. How activation works

Five steps, end to end. The admin does the first three. Everyone else just opens an email.

1. Admin deploys the team server (Docker or Node — covered below).
2. Admin activates the org license on the server, once, using the Lemon Squeezy key from their purchase email.
3. Admin invites employees by email from the admin panel.
4. Employees click the invite link in their email and set a password in the browser. No install required.
5. Optional: any employee can download the desktop app and point it at the team server URL for offline access and native integrations.

2. Prerequisites

• Docker and Docker Compose installed on your server
• Alternatively, Node.js 18+ if running without Docker
• A Team license key — purchase at getvrge.com/pricing
• A server with at least 1 GB RAM and 1 CPU core (any Linux VPS, on-premises machine, or cloud instance)

3. Quick Start with Docker

The rest of this page documents the configuration contract — env vars, persistence, security — so you can plan your deployment ahead of access. Once you have the image, the only flow-specific steps are docker compose up -d and verifying via http://localhost:8080; the first user to register becomes the org admin.

Generating your secrets now

The server refuses to boot without two secrets. You can generate them today and have them ready for when you receive the image:

echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env
echo "SERVER_TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

Each is a 64-character hex string (256 bits of entropy). Keep both backed up somewhere safe — see the Environment Variables section for what they do and the consequences of losing them.

4. Environment Variables

5. Database & Data Persistence

• Vrge uses SQLite — no external database server required
• Data is stored in a Docker volume called vrge-data at the path specified by DATABASE_PATH
• The volume persists across container restarts and updates

Backing up your database

docker cp vrge-server-1:/app/data/vrge.db ./backup.db

We recommend scheduling regular backups (e.g., via cron) to protect against data loss.

6. Activate the Org License

Once the server is running and you've registered as the first admin, activate your Team license on the server— not on anyone's laptop.

1. Open the server at your URL (e.g., https://vrge.yourcompany.com)
2. Sign in as the admin and go to Settings → Organization → License
3. Paste the license key from your purchase email (format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX — a UUID from Lemon Squeezy)
4. Click Activate

That's it. Your whole organization is now licensed. Nobody else on your team will ever see or enter a license key.

7. Invite Your Team

Once the org license is active, send email invites from the admin panel.

1. Go to Settings → Team → Invite
2. Enter the employee's email and role (admin or member)
3. Click Send invite — they get an email with a signed, single-use join link

Invite links expire after 7 days. Revoke or resend any invite from the same panel.

8. How Employees Join

Employees need nothing but their invite email to get working.

1. Open the invite email and click Join your team
2. The link opens the team server in a browser — set a password, you're in
3. Work from the browser on any device — no install, no license key

Optional: desktop app for offline + native integrations

Any employee can also download the Vrge desktop app, enter the team server URL and their email + password, and unlock offline support, local AI (Ollama), and native OS integrations. The org license already covers them — the desktop app never prompts for a key.

9. Permissions & Audit Log

Two team-mode behaviours worth knowing about as an admin — both designed to make multi-user collaboration safer without putting you in the middle of every change.

Owner-or-admin edits

When a team member creates a client, project, task, note, invoice, or expense, they become its owner. By default:

• Everyone can read every shared entity (the team is small enough that segmentation adds friction without much benefit)
• Only the creator (or an admin) can edit a given entity — preventing well-meaning teammates from accidentally overwriting each other's work
• Only admins can delete shared entities — the destructive path stays narrow on purpose. Members can still delete their own comments and uploads.

Rows that pre-date the upgrade have no recorded creator and stay editable by any member, so legacy data isn't locked behind the new gate.

Activity log (Settings → Activity)

Every create, edit, and delete is recorded with the actor, entity, action, and timestamp. Filter by user, entity type, action, or date range. Useful for:

• Investigating "who changed this client on Tuesday?"
• Compliance evidence in regulated verticals (legal, medical, financial)
• Recovering after an accidental edit — the audit row points at the entity even if it's since been deleted

Logs are retained for the life of the database — there's no automatic pruning. Capture them in your regular SQLite backups.

Sessions & sign-in

Vrge uses short-lived (15 minute) access tokens that silently refresh from a 7-day rotating cookie. End-users see this as "stays signed in" — they don't hit a re-login screen unless they've been away for more than a week. If a refresh token is ever reused after rotation, the entire session family is revoked automatically and that user is forced to sign in again on all devices — Vrge's built-in defence against stolen-cookie replay attacks.

10. Updating

To update the Vrge server to the latest version:

docker compose pull
docker compose up -d

Your data volume is preserved across updates. We recommend backing up your database before updating.

11. Security Recommendations

• Use HTTPS— place Vrge behind a reverse proxy (e.g., Nginx, Caddy, or Traefik) with TLS certificates
• Use 256-bit secrets for both keys — generate with openssl rand -hex 32. The encryption key requires exactly 64 hex characters; the JWT secret requires at least 32.
• Rotate JWT_SECRET annually — or after any suspected compromise. Rotation invalidates every active session, so users will need to log back in. Do this during a low-traffic window.
• Rotate SERVER_TOKEN_ENCRYPTION_KEY with care — rotation makes existing OAuth ciphertext unreadable. Employees will be prompted to reconnect their Gmail/Outlook/ Calendar grants. No CRM data is affected. Annual rotation is a reasonable default.
• Restrict network access — only expose the server on your internal network or behind a VPN if possible
• Keep Docker updated — regularly update Docker and your host OS to patch security vulnerabilities
• Back up regularly — schedule automated backups of the SQLite database file
• Monitor logs— check container logs with docker compose logs -f for any issues