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 127.0.0.1:8080:80 nginx

This runs an Nginx container named my-app in the background, mapping port 8080 on the seedbox loopback address (127.0.0.1) to port 80 inside the container. Binding to 127.0.0.1 keeps the container off the internet, but other accounts on the same server can still connect to it; Serving a Container Over HTTPS shows how to reach it from your browser.

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 127.0.0.1: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:
      - "127.0.0.1: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.

Serving a Container Over HTTPS

A rootless container can't bind to port 443 directly (see Rootless Limitations below) — you reach it over HTTPS through your own lighttpd instance instead, the same reverse proxy pattern used for any proxied application on the panel. There is no automatic per-container subdomain; you write the proxy fragment yourself.

Bind the container to a local port:

docker run -d --name myapp \
  -p 127.0.0.1:9090:80 \
  myimage

Create a config fragment in ~/.lighttpd/custom.d/:

$HTTP["url"] =~ "^/user-USERNAME/myapp/" {
  auth.require = ()
  proxy.server = ( "" => ( (
    "host" => "127.0.0.1",
    "port" => 9090
  ) ) ),
  proxy.header = (
    "upgrade" => "enable",
    "map-urlpath" => (
      "/user-USERNAME/myapp/" => "/",
      "/user-USERNAME/myapp"  => ""
    )
  )
}

Replace USERNAME, the path, and the port with your own. Save the file; lighttpd restarts within about a minute and the container becomes reachable at https://SERVER.pulsedmedia.com/user-USERNAME/myapp/.

auth.require = () switches off your panel login for that one path, so keep it only when the application has its own login. Leaving the line out keeps your panel login in front of the application's web address, but not in front of its port: other accounts on the same server can connect to 127.0.0.1 directly, so an application without a login of its own is open to them. "upgrade" => "enable" lets WebSocket connections through, which many web applications need for live updates and players. There is no automatic per-container subdomain: each container you want on HTTPS gets its own short fragment like the one above.

The full walkthrough — including what auth.require and map-urlpath do, and fixes for 502s and login loops — is on Lighttpd Custom Configuration. Self-Hosted Apps on PMSS lists 39 applications with the sub-path setting, login default and memory needs of each.

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.