Skip to content

Best Practices

Kyle Ebbinga edited this page Nov 19, 2026 · 2 revisions

Best practices

These recommendations follow from how Vertex works internally. Vertex is in pre-alpha, so expect them to change as features land.

Warning

Vertex is in early development. Keep another copy of anything important (a backup, or a vx-mirror push to git or Perforce) until it reaches a stable release.

Projects

  • One project per game or product. A project is the unit of history, locks, and access. Everything that ships together (code, content, configs) belongs in a single project so that a single revision can change all of it at once.
  • Split unrelated teams into separate projects. Writes to one project (submits, merges, lock changes) run one transaction at a time, so the database's commit speed limits a project's write throughput. Two teams that never touch each other's files gain nothing from sharing a project, and they queue behind each other.
  • Write .vxignore before the first submit. Build output, caches, and editor files are regenerated anyway, and nothing reclaims storage yet: a DerivedDataCache/ submitted by mistake stays on the server even after you delete it. Start from the file vx init writes, and check vx status before submitting. See Ignore rules.
  • Keep generated files out, source assets in. Submit .uasset, .blend, .psd, source textures, and audio. Don't submit anything a build will produce. Chunk dedup makes repeated versions of large sources cheap, so don't be afraid to submit them.
  • Name branches simply. They appear in commands, so lowercase names without spaces (shooter, release-1.2) are easiest to type.

Daily work

  • Keep vx open in your workspace. The interactive session locks files as you save them and shows others' updates and locks as they happen, so you find out someone else has a file before you've spent an hour on it. Without a session, locks are only taken and seen when you run vx status.
  • Sync before you start, and before you submit. A submit is refused when a file you changed was changed on the server since your last sync. Syncing often keeps that rare and keeps conflicts small.
  • Submit small, focused revisions, often. Each revision is atomic and easy to find, and submitting releases your locks so others can work. Use paths to split unrelated work: vx submit -m "New level" Content/Maps.
  • Write messages for the people reading history. Say what changed and why: "Fix jump height on low gravity planets".
  • Don't sit on locks. A lock blocks everyone else from submitting your file. If you're done for the day with unfinished binary work, consider whether someone may need the file; vx revert releases it if you don't need the change.
  • Check vx locks before big edits to shared files such as persistent levels and data tables.
  • Clean up after dead machines. When a workstation is reinstalled with locks still held, its owner runs vx unlock <paths> from their new workspace. Anyone with manage access can clear anyone's.
  • Don't edit read-only files by clearing the flag. A read-only file means it's locked by someone else, and the server will refuse your submit anyway. Ask them, or wait for their submit and sync.

Branches

  • Keep main releasable, and branches short-lived. Branches are cheap to create (a server-side copy with no upload), but every day a branch lives, more files change on both sides, and Vertex merges whole files: a file changed on both is a conflict you settle by picking a side.

  • Use branches for releases and risky experiments, not for every task. With exclusive locks on binary files, most game teams work best directly on main, the Epic way. Branch when you need to stabilize a release or try something you may throw away.

  • Let fixes flow forward with merge chains. Give each release branch a merge target, oldest to newest, ending at main:

    vx branch release-1.0 --merge-to release-2.0
    vx branch release-2.0 --merge-to main

    Fix bugs on the oldest release that needs them, and the server carries the fix forward. Watch the hops vx submit prints. When one stops on a conflict, settle it soon with vx merge <branch> --into <target> and a side, because any later fix will wait behind it.

  • Merge before deleting. vx branch -d deletes the branch's revisions too.

  • Use --blank only for unrelated content. A blank branch shares no history, so it can never be merged with others.

Access

  • Grant groups, not people. Create artists, programmers, contractors, grant each group once per project, and manage membership as people come and go.
  • Use read for people who only need builds or reference, write for contributors, and manage for the few who manage access and branches.
  • Gate projects with groups. Projects have no default access. For a project the whole studio should see, grant read to an everyone group once; keep secret work (unannounced projects, licensed third-party source) to the groups that need it.
  • Keep server admins few. They can manage all users and projects.
  • Disable, don't delete. When someone leaves, vx user disable ends their sessions and keeps their history.
  • Give automation its own user. Create a user such as ci-bot with a token, rather than logging in with --password.

Running a server

  • Pin a release. Run the stable tag or a specific version, never latest, and upgrade deliberately.
  • Back up PostgreSQL and S3 together. PostgreSQL holds history and the index of stored chunks; S3 holds the chunks. A restore needs both from the same point in time, and a database restored without its chunks has revisions whose content is gone. Use continuous archiving (or pg_dump at minimum) for PostgreSQL, and bucket versioning or replication for S3. Back up PostgreSQL first and S3 after, so every chunk the database refers to is in the S3 copy (chunks are never deleted, so a newer S3 copy is always a superset). Test a restore.
  • Make commits fast. Per-project write throughput is bounded by PostgreSQL's commit latency. Put PostgreSQL on storage with fast, power-safe synchronous writes; on ZFS, add a SLOG. See Performance.
  • Run Redis as a pure cache, one per deployment, with persistence off. See Configuration.
  • Terminate TLS properly behind proxies. Give the server a certificate, have the proxy speak HTTP/2 to it, and set VX_TRUSTED_PROXIES so login throttling sees real client addresses. See Deploying the server.
  • Monitor it. Turn on VX_METRICS_PORT, keep that port off the internet, and alert on project write saturation, slow commits, Unavailable errors, and Redis being down. See Monitoring.
  • Load-test before people depend on it. Run vx-bench with the team profile from outside your network to see what users will feel, and standard to find the ceiling. See Benchmarking.
  • Run an integrity canary. A vx-mirror pull of a busy repository on a test server checks every byte it submits, all day. See Mirroring.
  • Keep secrets out of files. Configure the server with environment variables or the orchestrator's secret store. Never commit .env, connection strings, S3 keys, or certificates.
  • Change the bootstrap admin. VX_ADMIN_PASSWORD only applies on first start. Afterward, create named admins and stop using the shared admin account.

Known gaps

Plan around these until they land (see the feature table in the README):

  • No garbage collection: deleted content and abandoned uploads keep their storage.
  • No code review, build automation, or issue tracking yet.
  • No content merging: conflicts are settled by choosing a whole file.
  • Pre-release schema changes need a manual migration step (see Deploying the server).

Clone this wiki locally