PiFi: Docker, Plex, and Rclone Caching

General
1

I’ve been experimenting with PiFi (mine is Raspberry Pi 4b with 8GB RAM with an Argon M.2. case that has 250gb SSD) and discovered a few tips for installing Docker, setting up Plex in a container, and using local caching for remote media to speed up access. Below is a summary of what I’ve learned.

1. Installing Docker and Containers on PiFi (OpenWrt)

OpenWrt supports Docker, but there is sometimes a strict installation order required to avoid errors. The simplest approach is to install all necessary packages from the command line (SSH), rather than through the LuCI web interface. You can do this with:

opkg update
opkg install docker luci-app-dockerman docker-compose dockerd --force-maintainer
  • docker: the Docker CLI
  • luci-app-dockerman: a web-based Docker management GUI in LuCI
  • docker-compose: for multi-container orchestration (optional, command-line based)
  • dockerd: the Docker daemon (service)

After installing these packages, you will see a “Docker” menu in the LuCI interface.

2. Installing Plex in a Docker Container

Plex requires a claim token to associate a new server with your Plex account. The token is only valid for a short time. Follow these steps:

  1. Obtain a Plex Claim Token
  • Go to Sign In | Plex in a web browser where you’re logged into Plex.
  • Copy the token (it starts with claim-...).
  1. Pull the Plex Image
  • In LuCI → Docker → Images, Pull the image linuxserver/plex:latest.
    Alternatively, do it via SSH:
docker pull linuxserver/plex:latest
  1. Run Plex with --network=host (Recommended)
    When Docker is used on OpenWrt, bridging modes can sometimes create firewall or NAT complications. Using --network=host binds Plex directly to the Pi’s network interface, making it easier to reach from your LAN.
    In LuCI → Docker → Containers, click Resolve CLI and paste:
docker run -d \
  --name=plex \
  --restart=unless-stopped \
  --network=host \
  -v /storage/plex/config:/config \
  -v /storage/plex/transcode:/transcode \
  -v /mnt/htpc:/data:ro \
  -e TZ=Etc/UTC \
  -e PUID=0 \
  -e PGID=0 \
  -e VERSION=docker \
  -e PLEX_CLAIM="claim-token" \
  linuxserver/plex:latest
  1. Here’s what each parameter does:
  • --network=host: No additional port mappings are required. Plex listens on port 32400 (and other Plex ports) directly on the Pi’s IP.
  • -v /storage/plex/config:/config: Stores Plex configuration and metadata on your local SSD.
  • -v /storage/plex/transcode:/transcode: Stores transcoding temp files on your SSD.
  • -v /mnt/htpc:/data:ro: This is your media directory mounted via rclone (see below). The container sees it as /data.
  • -e PLEX_CLAIM=...: Your temporary claim token from Sign In | Plex.
  • -e PUID=0 and -e PGID=0: Runs Plex as the root user inside the container (simplest on OpenWrt).
  1. Access Plex
  • Within ~30 seconds, Plex should be running. Open a browser on the same LAN and go to:
http://<Your-Pi-IP>:32400/web
  • Sign in with your Plex account and complete the setup wizard.

If you prefer bridging mode (with -p 32400:32400 etc.), you can do that as well, but be sure the OpenWrt firewall or Docker NAT rules are configured so you can access the server from your LAN.

3. Using Local Storage as a “Cache” for Remote Media (Rclone)

Goal: If you’re traveling or otherwise remote, your PiFi device (with an SSD) can locally cache media from your home server. This way, repeated access is faster and less dependent on Internet speed at home or at your remote location.

3.1 Installing Rclone

  1. In LuCI → System → Software, install rclone-webui-react. This also installs the rclone binary itself.
  2. (Optional) You can then launch an interactive Web UI by running:
rclone rcd --rc-web-gui --rc-user=admin --rc-pass=secret --rc-addr=:5572

and connect to http://<Pi-IP>:5572 for a nice GUI to configure rclone.

3.2 Configuring Rclone to Mount SMB/Windows Shares

Let’s say your home server is at 192.168.1.69 and the share is named htpc. You can create a config file like this:

[home_server]
type = smb
host = 192.168.1.69
user = guest
pass =

Here, user = guest and pass = (blank) if your share really allows guest access.

3.3 Mounting the Remote Share with Local Caching

To mount it permanently on boot, edit /etc/rc.local (or create a custom init script) so it reads something like:

#!/bin/sh
# (Other commands if needed)

/usr/bin/rclone mount home_server:htpc /mnt/htpc \
  --config /root/.config/rclone/rclone.conf \
  --vfs-cache-mode full \
  --vfs-cache-max-size 220G \
  --cache-dir=/storage/rclone_cache \
  --allow-other \
  --daemon

exit 0

Explanations:

  • --config /root/.config/rclone/rclone.conf: Ensures it uses the correct config file where [home_server] is defined.
  • --vfs-cache-mode full: Enables rclone’s local caching.
  • --vfs-cache-max-size 220G: Limits the cache usage to 220 GB on your SSD. Adjust as needed.
  • --cache-dir=/storage/rclone_cache: Directory on your SSD to store cached files (so it doesn’t fill your SD card).
  • --allow-other: Allows other system users (e.g., Plex) to read the mount.
  • --daemon: Runs in the background.

After a reboot, run:

ls /mnt/htpc

You should see your remote folders. The first time you access a file, rclone fetches it from your home server. Subsequent accesses come from the local SSD cache.

Tips & Troubleshooting

  1. Plex Server Access
  • If you have trouble accessing http://<Pi-IP>:32400/web, try --network=host (as shown above) to simplify networking.
  • Ensure the Pi is on the same subnet as your client device.
  1. DNS Issues in Docker
  • If the Plex container can’t resolve plex.tv, add --dns=8.8.8.8 in your docker run command or configure Docker’s DNS in /etc/docker/daemon.json.
  1. Rclone Startup Timing
  • If you’re mounting a share over a VPN, sometimes /etc/rc.local runs before the VPN is active. Adding sleep 15 or sleep 30 can help.
  • Check logs with logread | grep rclone or cat /tmp/rclone.log if you enabled --log-file.
  1. Cache Location
  • Always confirm your SSD is mounted at /storage or another path before rclone tries to write cache data there. Use df -h or mount to verify.

Final Thoughts

With Docker and Rclone caching, you can run a local Plex server on your PiFi device, backed by an SSD, all while storing media remotely on your home server. This setup reduces bandwidth usage and speeds up repeated access. Enjoy!

This whole project started because I had an SSD connected to the RaspberryPi and was looking for ways to better utilize it. In the future I’ll explore more dockers that could be useful for installation on this device. With the steps described above it’s now really easy. Enjoy!

2 Likes
2

Great! Super helpful write-up

Will try this over the weekend

3

Nice guide. Keen to build more docker features directly into the project at some stage too.

4

The really cool thing, once Docker is installed, would be to have a sort of a “community app store”, which is a list of Dockers that the community tried, verified working etc, like my Plex example. This would be similar to what I have in my Unraid server, which has a “community apps” section, which is nothing more than a list of Dockers that were tested by users.

5

That would be great!! Tried this guide and works very well