Warning

The product is in closed beta and not open to the public.

Deploy with Docker Compose

Follow these steps to deploy VisionByte Server with Docker Compose, enable file locking, and create your first repository.

Prerequisites

Install Docker with Docker Compose. Make sure port 8080 is available, or choose a different port in the configuration below.

Create a deployment directory and run the remaining commands from it:

mkdir -p visionbyte
cd visionbyte

Create the configuration

Create a file named docker-compose.yaml with the following contents:

name: visionbyte

services:
  postgres:
    image: postgres:18.7-alpine3.24
    container_name: visionbyte-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env file}
    volumes:
      - visionbyte-postgres-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "postgres", "-d", "postgres"]
      interval: 5s
      timeout: 3s
      retries: 30
      start_period: 10s
    restart: unless-stopped

  visionbyte:
    image: ${VB_IMAGE:-softbridge/vb-server:latest}
    container_name: visionbyte-server
    user: "499:499"
    environment:
      VB_HOME: /museum
    command: ["--repolist", "--jsmode", "inline", "--port", "8080", "/repo"]
    ports:
      - "${VB_PORT:-8080}:8080"
    volumes:
      - ./repo:/repo
      - vb-config:/museum
    restart: unless-stopped

volumes:
  visionbyte-postgres-data:
    name: visionbyte-postgres-data
  vb-config:
    name: vb-config

Create a file named .env alongside docker-compose.yaml:

VB_IMAGE=softbridge/vb-server:latest
VB_PORT=8080
POSTGRES_PASSWORD='replace-with-postgres-admin-password'

Set POSTGRES_PASSWORD to a strong password, keeping the surrounding single quotes. Change VB_PORT if you want to use a port other than 8080.

Create the repository directory and grant the service access to it:

mkdir -p repo
sudo chown -R 499:499 repo

Start the services

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps

Confirm that postgres is healthy and visionbyte is running before continuing. If startup fails, inspect the logs:

docker compose logs postgres visionbyte

Initialize PostgreSQL for locks (once)

Important

Run this initialization once for this server deployment. It applies to every repository on the server, including repositories created later. Do not repeat initialization for each repository or after normal restarts.

Initialize the database:

docker compose exec visionbyte /usr/local/bin/vb pq init --host postgres --port 5432 --database visionbyte --admin-user postgres --runtime-user vb_runtime

Enter the two passwords when prompted:

  • PostgreSQL administrator password: the POSTGRES_PASSWORD value in .env.

  • VisionByte runtime password: a separate strong password for VisionByte to access the database.

Keep the host and port values shown in the command, even if you changed VB_PORT in .env.

Confirm that initialization prints:

PostgreSQL initialized for VisionByte database visionbyte.

Then verify the saved connection:

docker compose exec visionbyte /usr/local/bin/vb pq test

The output must include PostgreSQL connection OK. If either command reports an error, resolve it and repeat the failed step before continuing.

For more information, see Deploy a Lock server.

Create a repository

Create a repository named Demo:

docker compose exec visionbyte /usr/local/bin/vb init --admin-user admin --project-name "Demo" /repo/demo.vbyte

The repository is saved as repo/demo.vbyte on the host. The command prints the initial administrator account and password. To set a new password interactively, run:

docker compose exec visionbyte /usr/local/bin/vb user password admin -R /repo/demo.vbyte

To create another repository, repeat the creation command with a different project name and filename. You can also place existing repositories in the repo directory and grant the service read and write access to them.

Open http://localhost:8080/ to view the repository list. The example repository is available at http://localhost:8080/demo/. Substitute the configured VB_PORT if different, and the server hostname when connecting from another machine. Refresh the list after adding repositories; no server restart is required.

Verify file locks

On a client connected to a repository on this server, use a repository account with the required permissions and run the following commands in its working directory. Replace the example path with a tracked file:

vb lock Content/Hero.uasset
vb lock-info Content/Hero.uasset
vb unlock Content/Hero.uasset

The commands should report LOCK, show the lock information, and then report UNLOCK.

For command options and examples, see lock, lock-info, and unlock.

Persistence and maintenance

The deployment stores data in three locations:

  • ./repo: repository files on the host.

  • vb-config: saved server settings.

  • visionbyte-postgres-data: database contents, including file locks.

To stop the services while keeping your data, run:

docker compose down

To start them again, run:

docker compose up -d

Warning

docker compose down -v deletes the saved server settings and database contents. Back up all three data locations before removing the deployment.

Changing POSTGRES_PASSWORD in .env does not change the password in an existing PostgreSQL data volume. Update the database password separately before using the new value for administrator operations.

If you need to change the database connection or VisionByte runtime password, repeat the initialization command with the new values, then run vb pq test to verify the connection. Follow the release instructions when upgrading.