Skip to main content

Run Visor in Docker

Run Visor as a container built from the upstream build/Dockerfile. This is the recommended way to keep the Postgres + Visor + TSS stack reproducible.

Prerequisites​

On-host layout that will be mounted​

Keep Visor's config and the TSS binary assets on the host and mount them into the container:

./deploy/
├── config.yaml                # Visor config
└── binary/
    ├── tss                    # TSS binary         -> mounted at /binary/tss
    └── configs/
        ├── tss.yaml           # TSS binary config  -> /binary/configs/tss.yaml
        └── certs/             # certificates dir   -> /binary/configs/certs

Matching config.yaml snippet (note the in-container paths):

deploy/config.yaml
tss:
  binary_path: "/binary/tss"
  binary_params: ""
  api_params: ""
  config_path: "/binary/configs/tss.yaml"
  certificates_path: "/binary/configs/certs"
  core_address: "bridge1..."

See Configuration file for the full field reference.

1. Build the image​

docker build -f build/Dockerfile -t tss-wrapper-svc .

The image's entrypoint is tss-wrapper-svc, so any arguments you pass to docker run are treated as CLI arguments to Visor — including the -c / --config flag.

Option 1 — plain docker run​

Bring up Postgres (once)​

docker compose -f build/docker-compose.yaml up -d db

This exposes Postgres on localhost:5435 with user / password / db tss-wrapper / tss-wrapper / db. For alternative Postgres setups see Set up database.

Apply migrations (one-off)​

docker run --rm \
  --network host \
  -v $(pwd)/deploy/config.yaml:/config.yaml \
  tss-wrapper-svc service migrate up -c /config.yaml

Run Visor​

docker run -d --name tss-wrapper \
  --network host \
  -v $(pwd)/deploy/config.yaml:/config.yaml \
  -v $(pwd)/deploy/binary:/binary \
  -p 8080:8080 -p 9090:9090 \
  tss-wrapper-svc service run -c /config.yaml

Notes:

  • --network host is the simplest way to let the container reach the Postgres exposed on localhost:5435. If you don't use host networking, change db.url to point at the Postgres container's service name and place both containers on the same Docker network.
  • The -v .../binary:/binary mount covers tss.binary_path, tss.config_path and tss.certificates_path in one shot, as long as those paths live under the binary/ tree.
  • -p 8080:8080 -p 9090:9090 publishes Visor's HTTP gateway and gRPC server.

Option 2 — docker-compose​

build/docker-compose.yaml already defines the db service and ships a commented-out tss-wrapper-svc service. Its entrypoint already runs migrations before the service:

entrypoint: sh -c "tss-wrapper-svc service migrate up && tss-wrapper-svc service run"

To use it:

  1. Uncomment the tss-wrapper-svc block in build/docker-compose.yaml.

  2. Adjust volumes: to mount your config.yaml and, if needed, the binary/ tree.

  3. Update db.url in your config.yaml to use the compose service name db instead of localhost, for example:

    config.yaml
    db:
      url: postgres://tss-wrapper:tss-wrapper@db:5432/db?sslmode=disable

  4. Start the stack:

make docker-up
# equivalent to: docker-compose -f build/docker-compose.yaml up

Verify​

  • HTTP gateway:
curl http://localhost:8080/
  • gRPC:
grpcurl -plaintext localhost:9090 list
  • Container logs:
docker logs -f tss-wrapper

You should see the orchestrator log started default mode once Visor has launched the TSS binary, plus observer lines for events consumed from Bridgeless-core.