Rootless DOCKER

Docker packages software into isolated containers, each with its own filesystem, network, and process space. On a shared seedbox, that means you can run additional applications without interfering with other users or needing root access.

Pulsed Media provides rootless Docker on all seedboxes as part of PMSS. Containers run entirely as your user — no sudo, no elevated privileges. A platform watchdog starts the Docker daemon automatically, so there is nothing to install or enable. Do not try to run dockerd-rootless.sh manually — the watchdog handles startup and will conflict with manual attempts.

Typical uses: Jellyfin for media streaming, Sonarr/Radarr for download automation, VPN clients for routing specific traffic, or any containerized application you want isolated from your main environment.

Getting Started

Docker rootless starts automatically on PMSS. A watchdog runs every 5 minutes and ensures the daemon is running for all active users. You do not need to start it manually.

Verify Docker is running:

docker ps

If you see an empty container list (or your running containers), Docker is working. If you get a socket error, wait a few minutes for the next watchdog cycle and try again. If the error persists after a couple of cycles, contact support.

If docker is not found, add the binary directory to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Environment Variables

If Docker commands fail, check that XDG_RUNTIME_DIR is set:

echo $XDG_RUNTIME_DIR

It should show something like /run/user/1042. If it is empty or missing, contact support — this indicates a session configuration issue that needs server-side attention.

If a specific tool cannot find the Docker socket, you can point it explicitly:

export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock"

Common Commands

Command	What it does
`docker ps`	List running containers
`docker ps -a`	List all containers (including stopped)
`docker images`	List downloaded images
`docker pull <image>`	Download an image from Docker Hub
`docker run <image>`	Create and start a container
`docker stop <name>`	Stop a running container
`docker start <name>`	Start a stopped container
`docker restart <name>`	Restart a container
`docker rm <name>`	Remove a stopped container
`docker rmi <image>`	Remove a downloaded image
`docker logs <name>`	View container output
`docker exec -it <name> sh`	Open a shell inside a running container

Running a Container

docker run -d --name my-app -p 8080:80 nginx

This runs an Nginx container named my-app in the background, mapping port 8080 on your seedbox to port 80 inside the container.

Persistent Data with Volumes

Containers lose their data when removed. To keep data, mount a directory from your home folder:

docker run -d --name my-app \
  -v ~/appdata:/data \
  -p 8080:8080 \
  some-image

Docker Compose

Docker Compose defines multi-container setups in a YAML file. Check if it is available on your server:

docker compose version

If available, create a docker-compose.yml in a project directory:

services:
  app:
    image: nginx
    ports:
      - "8080:80"
    volumes:
      - ./data:/usr/share/nginx/html
    restart: unless-stopped

Start all services:

docker compose up -d

Stop them:

docker compose down

View logs:

docker compose logs -f

Keep each project in its own subdirectory under your home folder. Compose is the standard way to run stacks like Sonarr + Radarr + Prowlarr together — see Install Media Stack for a one-command installer that sets this up.

Rootless Limitations

Running Docker without root has constraints:

Ports below 1024 are unavailable: Containers cannot bind to ports like 80 or 443. Use ports 1024 and above.

No system-level access: Containers cannot write to /etc, load kernel modules, or modify host network interfaces.

No privileged mode: --privileged containers will not work. Anything requiring raw device access or elevated kernel capabilities is not available.

User-space networking: Rootless Docker uses a user-space network stack (slirp4netns or pasta). Throughput is slightly lower than root Docker for high-bandwidth workloads. Containers that require raw sockets, macvlan, or ipvlan networking will not work without modification.

These constraints protect other users on the same server and keep environments isolated.

Troubleshooting

Socket error on `docker ps`

The Docker daemon may not have started yet. Wait a few minutes for the PMSS watchdog to start it, then try again. Do not run dockerd-rootless.sh manually — the watchdog handles startup.

If the error persists, contact support.

`docker` command not found

Add ~/.local/bin to your PATH — see #Getting Started.

Container fails with "fuse-overlayfs not found"

If containers fail to start and the error mentions fuse-overlayfs not being found, this is a server-side package issue. Contact support with the error message — the fix requires root access.

Container fails with cgroup permission error

If you see errors about unable to start unit or Permission denied related to cgroups, contact support with the full error message. This is a server-side configuration issue.