Self-Hosting the Team Server

Deploy the Vrge collaboration server on your own infrastructure. This guide is for Team license customers who need real-time collaboration across their organization.

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 from the admin panel. The server emails each invite once you have given it a mail provider (section 5).
4. Employees click the invite link 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. The server download comes with it.
• 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

tar -xzf vrge-team-server-*.tar.gz
cd vrge-team-server-*
cp .env.example .env
# fill in the secrets below, then:
docker compose up -d --build

Then open http://localhost:8080. The first user to register becomes the org admin. The first run compiles the web client from source, so expect a few minutes; later runs reuse the Docker cache.

Generating your secrets

The server needs three secrets, and .env.example carries no real values for them — what is there is placeholder text. Generate them before the first boot; a later duplicate of the same key in a .env file wins, so appending is enough:

echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env
echo "CSRF_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 them backed up somewhere safe. See the Environment Variables section for what they do and the consequences of losing them.

LICENSE_KEY is placeholder text in .env.example as well. Replace it with the key from your purchase email: Compose only stops you when the value is empty, so a leftover placeholder starts a server whose licence key was never bought (section 7).

4. Environment Variables

Changing WEB_PORT does not move CORS_ORIGIN or APP_URL with it. Set all three when you change the port or put a domain in front.

5. Email & Payment Links

Two more server capabilities switch on when their environment variables are set. Both credentials live only on your server — the desktop app never holds them, and they are unrelated to the read-only bank-feed connections teammates set up in the app.

Outbound email: invites, invoices, notifications

Set this up before you invite anyone. Email is how the server delivers an invite link; without it there is nothing to deliver one with. Configuring it also gives the invoice editor a working Send Invoice button that emails the invoice straight to the client. Vrge supports two delivery paths — set one:

Verify it from Settings → Email delivery → Send a test email as the admin. Invoice sending stays hidden until delivery is set up.

Invoice payment links (Stripe)

With a Stripe key on the server, every unpaid invoice gains a Generate Payment Link button. The server creates a Stripe Checkout page for the invoice amount (charged in USD), saves the link on the invoice for copying, and includes it in the invoice email. If you also connect the webhook, the loop closes itself: when the client pays, Stripe notifies your server and the invoice flips to paid on every teammate's screen — no bookkeeping click.

Webhook setup (for the auto-paid flip): in the Stripe dashboard, add a webhook endpoint pointing at https://your-server/api/webhooks/stripe subscribed to the checkout.session.completed event, then put its signing secret in STRIPE_WEBHOOK_SECRET. The server verifies every delivery's signature and rejects stale or unsigned calls. If you skip the webhook, mark invoices paid yourself — or let a connected bank feed propose the match when the payout lands.

6. 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
• Attachments are written to disk rather than into the database, in a second volume called vrge-uploads
• Both volumes persist across container restarts and updates

Backing up your server

Backing up the server is your job, and nothing in the app does it for you. Vrge's in-app backup controls — Download Backup, automatic folder backups, and Vrge Cloud Backup — all act on the local database of a soloinstall. In team mode your records live in this server's database, so the app hides those controls rather than write a file that would not contain your team's work. Hosted backup for team servers is planned after launch.

Stop the server first. SQLite is mid-write on a running server, and a hot copy can capture a torn file that restores into corruption. The downtime is a few seconds.

docker compose stop server
docker compose cp server:/app/data/vrge.db ./vrge-$(date +%F).db
docker compose cp server:/app/uploads ./vrge-uploads-$(date +%F)
docker compose start server

Restore the same way, with the server stopped. Migrations run on boot, so an older database restored onto a newer server is migrated forward; the reverse will not boot. Two things make a backup useless if you skip them: the team_user_oauth_tokens rows are encrypted with SERVER_TOKEN_ENCRYPTION_KEY, so back up your .env alongside the database — either is useless without the other — and the attachments volume is separate from the database, so a database-only backup restores rows pointing at files that no longer exist. Schedule it with cron, and test a restore before you need one.

7. Activate the Org License

Your Team license is activated on the server, once, not on anyone's laptop. Nobody else on your team will ever see or enter a license key.

On the Docker stack: set it in .env

Compose will not start without LICENSE_KEY, and the server reads it at boot ahead of anything stored later, so on a Docker deployment this is the licence:

LICENSE_KEY=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
LICENSE_TIER=team-starter

The key is the UUID from your purchase email. You do not have to get the tier right: the server confirms the key with Lemon Squeezy in the background and corrects the tier if you declared the wrong one, logging a warning so you can fix the setting. The seat count it settled on is printed in the boot log.

Outside Docker: paste it into the admin UI

Where LICENSE_KEY is not set, sign in as the admin, go to Settings → Workspace → License, paste the key and click Activate. It is verified with Lemon Squeezy and stored in the database. On the Docker stack LICENSE_KEY wins back at the next restart, so change .env there rather than the UI.

8. Invite Your Team

Once the org license is active and email delivery is set up (section 5), send 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. The server emails them a signed, single-use join link

Invite links expire after 7 days. You can revoke an invite from the same panel; if someone never received theirs or let it lapse, revoke it and send a fresh invite.

When every place is taken, the next invite (and the next signup against it) is refused with USER_LIMIT_REACHED rather than quietly failing. The check runs in the same database transaction that creates the account, so two people accepting invites at the same moment cannot both slip through. Free a place up by removing someone who has left, or move up a tier and update your license. Need more than 40? Get in touch.

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

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

Who can change what

Vrge uses flat collaboration: the team shares one workspace, and the only hard line is around deleting.

• Everyone can read every shared entity (the team is small enough that segmentation adds friction without much benefit)
• Any member can edit any client, project, task, note, invoice or expense. Vrge records who made each change in the activity log rather than blocking the edit. The assumption is that a small team wants to fix each other's records, not queue up behind whoever created them.
• Only admins can delete shared entities. The destructive path stays narrow on purpose. A misclick, a departing employee or a compromised account should not be able to wipe a coworker's project. Members can still delete their own comments and uploads.
• Viewers cannot change anything. Assign the viewer role to anyone who should only read.

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.

11. Updating

New versions arrive as a new tarball on the same Lemon Squeezy download link. There is no docker compose pull step: these images are built from the source in the tarball, not pulled from a registry.

tar -xzf vrge-team-server-<new>.tar.gz
cd vrge-team-server-<new>
cp ../vrge-team-server-<old>/.env .
docker compose up -d --build

Your data lives in the vrge-data and vrge-uploads Docker volumes, not in the folder you extracted, so it survives the swap. Migrations run on boot. Back up first anyway.

Upgrading from a build before 6 August 2026: attachments used to be written into the container's own filesystem rather than a volume, so rebuilding discarded them. Rescue them while the old container still exists, before your first up --build on the new version, then copy them into the new volume afterwards. Databases were always on a volume and were never affected.

docker compose cp server:/app/uploads ./uploads-rescue
docker compose up -d --build
docker compose cp ./uploads-rescue/. server:/app/uploads

12. Security Recommendations

• Use HTTPS: place Vrge behind a reverse proxy (e.g., Nginx, Caddy, or Traefik) with TLS certificates, then set REQUIRE_HTTPS=1 so the server refuses plaintext. Your proxy has to set X-Forwarded-Proto — Caddy and Traefik do by default; for nginx add proxy_set_header X-Forwarded-Proto $scheme;
• 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