VTunedocs

Getting started

Installation#

Public installation artifacts remain gated until stable v2. This page documents the release contract being validated; it is not a claim that the image or repository is available today.

Requirements#

  • A Linux AMD64 or ARM64 host with Docker Engine and Docker Compose.
  • A domain name with HTTPS and a reverse proxy such as Nginx.
  • A persistent volume with enough room for member quotas and backups.
  • A Discord application you control, including bot and OAuth credentials.

Stable-v2 install shape#

When public artifacts activate, the supported workflow will be:

mkdir vtune && cd vtune
# Download compose.release.yaml and .env.example from the stable-v2 release.
install -m 600 .env.example .env
# Add Discord credentials, allowed guilds, and PUBLIC_BASE_URL.
docker compose -f compose.release.yaml pull
docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/doctor.js
docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/invite-url.js
# Open the printed URL, add the bot only to an allowed server, then register commands.
docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/register-commands.js allowed
docker compose -f compose.release.yaml up -d
docker compose -f compose.release.yaml logs --tail=100 vtune

The default doctor is a pre-start gate: it validates the complete application configuration, runtime tools, persistent storage, and existing VTune data without echoing configuration values or credentials. The --image-smoke mode is reserved for secret-free release-image CI and does not establish that an instance is configured or ready.

VTUNE_IMAGE_TAG is an exact container tag without the Git tag's leading v. Stable v2.0.0 publishes 2.0.0, 2.0, 2, and latest; a prerelease such as v2.0.0-alpha.1 publishes only 2.0.0-alpha.1. Keep production pinned to the exact stable tag rather than a floating major, minor, or latest tag.

WEB_PORT is both the dashboard listener inside the container and the target of its health check. VTUNE_BIND_PORT selects the host-loopback port exposed to the reverse proxy. The defaults map 127.0.0.1:3000 to container port 3000. Compose scopes the vtune-data volume to its project. Keep the installation directory or explicit Compose project name stable across upgrades, and use a different project name for every staging, test, or second production instance on the same host. Before moving an installation, identify and back up its exact <project>_vtune-data volume rather than assuming another project can reuse it.

Network boundary#

Bind the container to host loopback and publish only the reverse proxy. The data volume, SQLite files, media tree, and health endpoints must remain private. Uploaded media has no HTTP download route.

Before the first start#

  1. Complete Discord application setup.
  2. Copy .env.example to .env and review Configuration.
  3. Run the image-contained doctor and resolve every blocking check.
  4. Generate the invite URL from the published container and add the bot only to an allowed server.
  5. Register commands in the allowed servers from the published container.
  6. Create a persistent data volume and an operator-controlled backup target.
  7. Configure TLS and reverse proxying.
  8. Start the pinned service and follow First run.