> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doviconvert.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Docker
> Run dovi_convert in a container with a web-based terminal
The dovi\_convert Docker container provides a self-contained environment with all dependencies pre-installed. It includes a web-based terminal, so you can access the tool from any browser without installing anything on your host system.
## Features
* **Web terminal** — Access dovi\_convert through your browser at `http://your-host:7681`
* **Pre-configured environment** — All dependencies (ffmpeg, dovi\_tool, mkvtoolnix, mediainfo) included
* **NAS-friendly** — Designed for network storage devices and servers
* **User mapping** — Run with your own UID/GID and set UMASK to avoid file permission issues
* **Persistent sessions** — The container has `tmux` for session management installed
## Quick Start Examples
Save this as `docker-compose.yml`:
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
services:
dovi_convert:
image: cryptochrome/dovi_convert:latest
container_name: dovi_convert
hostname: dovi-convert
environment:
- PUID=1000 # Your user ID (run 'id' to find)
- PGID=1000 # Your group ID
- TZ=UTC # Your timezone
- TMUX_HISTORY_LIMIT=50000 # Number of lines to reserve for `tmux` buffer
volumes:
# Mount your media folder(s) here
- /mnt/media/movies:/data/movies
- /mnt/media/tv:/data/tv
# - /path/to/ssd:/cache # Optional: fast temp storage
ports:
- 7681:7681
restart: unless-stopped
```
Then start the container:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
docker compose up -d
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
docker run -d \
--name=dovi_convert \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Europe/Berlin \
-p 7681:7681 \
-v /path/to/media:/data \
--restart unless-stopped \
cryptochrome/dovi_convert:latest
```
Then open `http://your-docker-host:7681` in your browser.
## Configuration
### User and Group IDs
The `PUID` and `PGID` environment variables control which user the container runs as. Set these to match your host user to avoid permission problems when accessing files.
To find your user and group IDs:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
id
```
This outputs something like `uid=1000(yourname) gid=1000(yourname)`. Use these values for `PUID` and `PGID`.
### Environment Variables
| Variable | Default | Description |
| -------------------- | ------- | -------------------------------------------- |
| `PUID` | `1000` | User ID for file permissions |
| `PGID` | `1000` | Group ID for file permissions |
| `TZ` | `UTC` | Timezone for log timestamps |
| `UMASK` | `022` | Set file permission UMASK if necessary |
| `TMUX_HISTORY_LIMIT` | `50000` | Number of lines to reserve for `tmux` buffer |
### Volume Mounts
Mount your media directories to `/data` inside the container. You can mount multiple paths, or just your root media folder (subdirectories are automatically included):
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-v /mnt/movies:/data/movies \
-v /mnt/tv:/data/tv
```
Inside the container, access your files at `/data/movies`, `/data/tv`, etc.
### Temp Directory for Faster Conversions
If your media is on slow storage (mechanical HDDs), you can bind-mount a faster drive for temporary files:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-v /path/to/ssd:/cache
```
Then use the `--temp` flag when converting:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /data/movie.mkv --temp /cache
```
Temporary files are written to the fast drive while the source and final output stay on your media volume.
### Port Configuration
The web terminal runs on port 7681 inside the container. Map it to any available port on your host:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-p 8080:7681 # Access at http://your-host:8080
```
## Using the Web Terminal
Once the container is running, open `http://your-docker-host:7681` in your browser. You'll see a terminal session with dovi\_convert ready to use.
The container includes a `dovi` alias for convenience - for example:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi help # Same as dovi_convert --help
dovi scan # Same as dovi_convert scan
# etc.
```
## Session Persistence
If you run longer, unattended conversions and close your browser window, the session will be terminated and the conversion interrupted. To avoid this, you can use `tmux` to create persistent sessions. This allows you to close your browser and later re-attach to the session to check on status or continue working where you left off.
`tmux` sessions persist as long as the container is running, unless you manually terminate them.
### Using `tmux`
This will start a new `tmux` session. You are automatically attached to it and can start working with dovi\_convert.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux new -s mysession
```
You can simply close your browser and the session will continue running in the background. For a more graceful exit, you can use this keyboard shortcut to detach: Press `Ctrl+b` followed by `d`.
When you later come back and login to the container again, you can re-attach to the existing session with:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux attach -t mysession
```
To list all running sessions, use:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux ls
```
To kill a detached session, use:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux kill-session -t mysession
```
To end a session you are currently attached to, simply exit the shell by typing:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
exit
```
To scroll through the session history after re-attaching, use `Ctrl+b` followed by `[`, then use the arrow or Page Up/Down keys to scroll. Press `q` to exit scroll mode.
For more info on how to use `tmux`, see the [official tmux documentation](https://github.com/tmux/tmux/wiki).
### Session Buffer
By default, the container reserves a buffer of 50,000 lines of text for `tmux`. This should be plenty for scrolling back in sessions after you re-attach (to check on progress, for example). However, 50k lines consume about 50-100 MB of RAM. If you are memory constrained, or want an even larger buffer, you can change the buffer size by setting the `TMUX_HISTORY_LIMIT` environment variable for the Docker container. An example is provided in the Docker Compose file on this page.
***
## Next Steps
Analyze your files to identify formats and FEL status
Convert files or directories to Profile 8.1