📣

TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →

Mount a File System in Docker

To mount a file system from TiDB Cloud Filesystem inside a Docker container, the container must have access to FUSE on the Linux host. In addition to installing fuse3 inside the container, you need to expose /dev/fuse and grant the container permission to create the mount.

This guide covers both Docker and Docker Compose on a Linux host. If your environment does not provide FUSE access or allow the required container privileges, use direct ti fs commands such as copy-file, read-file, and list-files instead.

Note

TiDB Cloud Filesystem is currently in public preview. Its features and interfaces are subject to change without notice.

Prerequisites

Before you begin:

Use a Linux Docker host where /dev/fuse is available.
Have permission to start containers with access to /dev/fuse and the capabilities required to create a mount.
Have a file system token and region code for an existing file system. See Access an Existing File System.

Docker Desktop and managed container or sandbox environments might not expose /dev/fuse or allow the required privileges.

Warning

The examples in this guide grant the container SYS_ADMIN and disable its AppArmor profile with apparmor=unconfined. These settings give the container broader privileges than a standard Docker container.

Use them only when permitted by your environment's security policy. Do not run untrusted code with these privileges unless your environment provides an appropriate additional isolation boundary. A scoped file system token can restrict access to file system data, but it does not reduce the privileges granted to the container by Docker.

Provide file system access to the container

On the Docker host, set the file system token and region code:

export TI_FS_TOKEN="<filesystem-token>"
export TI_REGION_CODE="<filesystem-region-code>"

Treat the file system token as a secret. Do not put it in a Dockerfile or commit it to source control.

The Docker and Docker Compose examples below pass these environment variables from the host into the container.

Start the container

Choose either Docker or Docker Compose.

Use Docker

On the Docker host, start an interactive Ubuntu container with access to FUSE:

docker run --rm -it \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  --env TI_FS_TOKEN \
  --env TI_REGION_CODE \
  ubuntu:24.04 bash

This command does the following:

Exposes the host's /dev/fuse device to the container;
Grants the capability required to create the mount; and
Passes the file system token and region code into the container.

After the container starts, continue with Install and mount inside the container.

Use Docker Compose

Alternatively, create the following compose.yaml file on the Docker host:

services:
  agent:
    image: ubuntu:24.04
    command: ["sleep", "infinity"]
    devices:
      - /dev/fuse:/dev/fuse
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor=unconfined
    environment:
      TI_FS_TOKEN: ${TI_FS_TOKEN:?Set TI_FS_TOKEN}
      TI_REGION_CODE: ${TI_REGION_CODE:?Set TI_REGION_CODE}

Start the container and open a shell in it:

docker compose up -d
docker compose exec agent bash

Then continue with the steps below inside the container.

Install and mount inside the container

The following steps run inside the container. They use the ubuntu:24.04 image from the preceding examples, which runs as root by default.

Install fuse3 and the tools required to install ti:

apt-get update
apt-get install -y --no-install-recommends ca-certificates curl fuse3

Install TiDB Cloud CLI:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes

Add ti to the current shell and create a local directory for the mount:
```
export PATH="$HOME/.ti/bin:$PATH"

mkdir -p "$HOME/workspace"
```
Mount the file system:
```
ti fs mount-file-system --mount-path "$HOME/workspace"
```
On Linux, ti uses FUSE by default. After the command succeeds, you can access the file system through $HOME/workspace. If the mount fails to start, inspect the diagnostic log path reported by ti.
If your file system token grants access only to a specific remote path, use the following command instead of the preceding mount command:
```
ti fs mount-file-system \
  --remote-path /workspace \
  --mount-path "$HOME/workspace"
```
In this example, the remote /workspace directory becomes the root of the local mount. For more information, see Mount only part of the file system.
To prevent writes through the local mount, add --read-only to the mount command. For example, to mount the file system root as read-only:
```
ti fs mount-file-system \
  --mount-path "$HOME/workspace" \
  --read-only
```
The --read-only option affects this local mount only. Use a scoped token with read-only permissions to enforce read-only access at the file system service.
Verify that you can access the mounted file system:
```
ls "$HOME/workspace"
```

Run the mount and the application that accesses it as the same OS user. If your application image uses a non-root user, install the required packages when building the image and create the mount as the application user at runtime.

Flush FUSE writes without unmounting

If you need pending writes to reach the file system while keeping the mount running, stop applications from writing to the relevant files and close those files first. Then drain the mount inside the container:

ti fs drain-file-system \
  --mount-path "$HOME/workspace" \
  --timeout 30s

A successful drain confirms that pending writes have reached the file system while leaving the mount running. If the drain times out or returns an error, keep the container and Docker host available, resolve the error, and verify the files before stopping or removing the container. For command syntax, see drain-file-system.

Stop the container safely

Before stopping or removing the container:

Inside the container, stop applications that are writing to the mounted directory and close open files.
Unmount the file system:
```
ti fs unmount-file-system --mount-path "$HOME/workspace"
```
Wait for the unmount to succeed before stopping or removing the container. A successful FUSE unmount flushes pending writes.
Stop the container:
- If you started it with docker run --rm -it, exit the shell after the unmount succeeds:
```
exit
```
  Docker removes the container automatically because it was started with --rm.
- If you used Docker Compose, exit the container shell, and then run the following command on the Docker host:
```
docker compose down
```

Stopping or removing the container does not delete the remote file system or its data.