dockette/viewdoc repository overview

⁠Dockette / Viewdoc

📄 🎞️ 🖼️ Browser-embeddable remote viewer for PDFs, office docs, audio, video, and images. A small Go control-center fronts a fixed pool of Kasm⁠ / LinuxServer Webtop⁠ desktop containers — pass ?url=... and the file opens in the right app inside an iframe.

🕹 f3l1x.io⁠ | 💻 f3l1x⁠ | 🐦 @xf3l1x⁠

⁠Why

Embedding rich file viewers in your product is a thousand papercuts: PDF.js for some types, an office viewer for others, a media player for the rest — each with its own quirks, sandbox story, and asset list. Viewdoc skips it. Open a real desktop in a tab, let the desktop open the file with its native app, and stream the pixels back. One iframe, every file type.

flowchart LR
    browser["Browser<br/>localhost:8080/?url=…"]

    subgraph cc["control-center (Go)"]
        proxy["reverse-proxy<br/>/slot/{i}/*"]
        api["POST /api/slot/{i}/params"]
    end

    subgraph viewer["viewer-i (Kasm / Webtop)"]
        novnc["KasmVNC :6901<br/>or Webtop :3000"]
        sidecar["sidecar :7000"]
        hook["viewdoc.sh"]
        apps["chromium · libreoffice · vlc<br/>xarchiver · wireshark · claws-mail"]
    end

    browser -->|iframe src=/slot/i/| proxy
    browser -->|"{url:…}"| api
    proxy -->|HTTP + WS| novnc
    api -->|POST /params| sidecar
    sidecar -->|fork| hook
    hook -->|dispatch by ext| apps

⁠Quickstart

docker compose build
docker compose up -d

open https://localhost:8443/                                   # iframe + URL bar + slot tabs
open "https://localhost:8443/?url=https://example.com/x.pdf"   # auto-opens in slot 0
curl -sk https://localhost:8443/healthz                        # {"ready":4,"total":4}

Default pool (VIEWER_SLOTS): 2× Kasm + 2× Webtop.

⁠File Types

The dispatcher routes by extension:

Only http:// and https:// URLs are accepted; anything else is refused before dispatch. Both images also ship exiftool for metadata inspection from a terminal, and Office-metric fonts (Liberation, Carlito, Caladea) so documents keep their original layout.

⁠Services

The system exposes two HTTP services. The control-center is the public entrypoint; the sidecar runs inside every viewer image on the compose network.

⁠Control Center — :8080 (plain), :8443 (TLS)

⁠Endpoints

⁠Environment

⁠TLS certificate

TLS_ADDR serves the same UI over HTTPS (browsers only allow clipboard access in a secure context). The startup log prints which cert is used and its SHA-256 fingerprint.

⁠Slot configuration

Each entry in VIEWER_SLOTS has the shape <vnc>[|<sidecar>]. The pipe is optional — omit it when the sidecar lives on the same host as the VNC endpoint (the compose default).

VNC half — accepted forms (port falls back to VIEWER_KASM_DEFAULT_PORT, except webtop:// which uses VIEWER_WEBTOP_DEFAULT_PORT):

Sidecar half — accepted forms (port falls back to VIEWER_SIDECAR_DEFAULT_PORT; kasm:// / webtop:// are not allowed here):

Worked examples

# Compose (DNS-friendly, sidecar implicit on same host:7000)
VIEWER_SLOTS="kasm://viewer-kasm-1,kasm://viewer-kasm-2,webtop://viewer-webtop-1,webtop://viewer-webtop-2"

# Equivalent fully-explicit form
VIEWER_SLOTS="https://viewer-kasm-1:6901,https://viewer-kasm-2:6901,http://viewer-webtop-1:3000,http://viewer-webtop-2:3000"

# Nomad / dynamic ports — VNC and sidecar published on different host ports
VIEWER_SLOTS="kasm://10.0.0.5:23456|10.0.0.5:34567,kasm://10.0.0.6:11111|10.0.0.6:22222"

# Override the pool-wide defaults so bare entries become 7901 / 3100 / 7900
VIEWER_KASM_DEFAULT_PORT=7901
VIEWER_WEBTOP_DEFAULT_PORT=3100
VIEWER_SIDECAR_DEFAULT_PORT=7900
VIEWER_SLOTS="kasm://node-1,webtop://node-2"
# → slot 0 vnc=https://node-1:7901 sidecar=http://node-1:7900
# → slot 1 vnc=http://node-2:3100  sidecar=http://node-2:7900

⁠Sidecar — :7000 (inside each viewer)

⁠Endpoints

⁠Environment

⁠Restarting a slot

The Restart button (POST /api/slot/{i}/restart) makes the viewer container exit; whatever supervises it brings up a fresh one. The sidecar can't kill the container itself (on Webtop it runs as abc, PID 1 is root), so it exits with code 42 and the image's wrapper does the rest:

• Kasm — custom_startup.sh loops on the sidecar; on 42 it sends SIGTERM to PID 1 (vnc_startup.sh, same uid), which exits.
• Webtop — the s6 finish script (runs as root) calls /run/s6/basedir/bin/halt; the container exits with code 42.

Any other sidecar exit just respawns the sidecar. Restarting requires a restart policy: compose's restart: unless-stopped works as-is. On Nomad, the default restart stanza (attempts = 2 per 30m, mode = "fail") runs out after a few clicks, and the allocation gets rescheduled — possibly to another node with new dynamic ports, which breaks a static VIEWER_SLOTS. Allow many quick in-place restarts:

restart {
  attempts = 100
  interval = "30m"
  delay    = "2s"
  mode     = "delay"
}

⁠Development

Requires Go 1.27.2+ (go.mod pins the toolchain; older Go downloads it automatically) and Docker with Compose v2.

make test          # go test ./...
go vet ./...
make build         # build all three images, stamped with VERSION
make cert          # regenerate the embedded certs/server.{crt,key} for your host IPs
make version       # print VERSION
make release       # set VERSION to today's date (see Versions)

CI (.github/workflows/docker.yml) checks the VERSION format and runs go vet, go test -race, staticcheck, govulncheck, shellcheck and hadolint, then builds every image. Pushes to master publish linux/amd64 + linux/arm64 images to Docker Hub (see Versions). The Kasm and Webtop base images are pinned by digest; Dependabot opens weekly PRs for new digests, Go builder images and GitHub Actions.

⁠Versions

viewdoc is versioned by release date: YYYY.MM.DD, or YYYY.MM.DD.N for another release on the same day. The current version is in VERSION⁠. It is built into both binaries (logged at startup, returned by the control-center's /healthz and the sidecar's /status) and set as the org.opencontainers.image.version label.

<variant> is control-center, viewer-kasm or viewer-webtop. Like other dockette images, release tags are rebuilt by the weekly schedule to pick up base-image updates; use the <short-sha> tag for a byte-identical image.

To release: make release sets VERSION to today's date (UTC; .1, .2, … if that date is already tagged), then commit and push to master. Once all images are pushed, CI tags the commit and creates the GitHub release <VERSION> with generated notes. A plain docker compose build stamps dev; make build uses VERSION.

⁠Maintenance

See how to contribute⁠ to this package. Consider to support⁠ f3l1x. Thank you for using this package.