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